okstra 0.145.0 → 0.146.0

package/runtime/python/okstra_ctl/dispatch_state.py

@@ -22,9 +22,13 @@ import os
 from dataclasses import dataclass
 from datetime import datetime, timezone
 from pathlib import Path
-from typing import Any, Mapping, Sequence
+from typing import Any, Callable, Mapping, Sequence
 
-from .worker_prompt_contract import PromptRecord, validate_initial_prompt_records
+from .worker_prompt_contract import (
+    PromptRecord,
+    validate_initial_prompt_records,
+    validate_reverify_prompt,
+)
 
 BACKEND_CLI_WRAPPER = "cli-wrapper"
 BACKEND_TMUX_PANE = "tmux-pane"
@@ -35,6 +39,10 @@ BACKEND_MIXED = "mixed"
 # analysis phases write their artifacts under project-root (see the contract in
 # scripts/okstra-codex-exec.sh).
 WORKTREE_TASK_TYPES = frozenset({"implementation", "final-verification"})
+WORKER_STATUSES = frozenset(
+    {"in-progress", "completed", "timeout", "error", "not-run"}
+)
+REASON_REQUIRED_STATUSES = frozenset({"timeout", "error", "not-run"})
 
 
 class DispatchError(Exception):
@@ -171,14 +179,24 @@ def worker_state(team_state: Mapping[str, Any], worker_id: str) -> Mapping[str,
     raise DispatchError(f"team-state has no workerId={worker_id}")
 
 
-def set_worker_status(
+def transition_worker_status(
     team_state_path: Path,
     worker_id: str,
     status: str,
     reason: str,
     *,
     model_execution_value: str = "",
+    at: str | datetime | None = None,
 ) -> None:
+    if status not in WORKER_STATUSES:
+        allowed = ", ".join(sorted(WORKER_STATUSES))
+        raise DispatchError(
+            f"unsupported worker status `{status}`; expected one of: {allowed}"
+        )
+    reason = reason.strip()
+    if status in REASON_REQUIRED_STATUSES and not reason:
+        raise DispatchError(f"worker status `{status}` requires a non-empty reason")
+    timestamp = _utc_timestamp(at)
     payload = load_json_object(team_state_path, "team-state")
     workers = payload.get("workers")
     if not isinstance(workers, list):
@@ -187,6 +205,14 @@ def set_worker_status(
         if isinstance(worker, dict) and worker.get("workerId") == worker_id:
             worker["status"] = status
             worker["reason"] = reason
+            if status == "in-progress":
+                worker["startedAt"] = timestamp
+                worker.pop("endedAt", None)
+            elif status == "not-run":
+                worker.pop("startedAt", None)
+                worker.pop("endedAt", None)
+            else:
+                worker["endedAt"] = timestamp
             if model_execution_value:
                 worker["model"] = model_execution_value
                 worker["modelExecutionValue"] = model_execution_value
@@ -195,6 +221,23 @@ def set_worker_status(
     raise DispatchError(f"team-state has no workerId={worker_id}: {team_state_path}")
 
 
+def _utc_timestamp(value: str | datetime | None) -> str:
+    if value is None:
+        instant = datetime.now(timezone.utc)
+    elif isinstance(value, datetime):
+        instant = value
+    elif isinstance(value, str):
+        try:
+            instant = datetime.fromisoformat(value.replace("Z", "+00:00"))
+        except ValueError as exc:
+            raise DispatchError(f"invalid UTC timestamp `{value}`") from exc
+    else:
+        raise DispatchError(f"invalid UTC timestamp `{value}`")
+    if instant.tzinfo is None or instant.utcoffset() != timezone.utc.utcoffset(instant):
+        raise DispatchError(f"invalid UTC timestamp `{value}`")
+    return instant.astimezone(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
 def set_dispatch_mode(team_state_path: Path, dispatch_mode: str) -> None:
     payload = load_json_object(team_state_path, "team-state")
     payload["dispatchMode"] = dispatch_mode
@@ -227,5 +270,126 @@ def validate_initial_prompts(
         raise DispatchError(f"{task_type} prompt contract: " + "; ".join(errors))
 
 
+def validate_dispatch_prompts(
+    manifest: Mapping[str, Any],
+    active_context: Mapping[str, Any],
+    jobs: Sequence[WorkerJob],
+) -> None:
+    initial_jobs = [
+        job for job in jobs if not job.dispatch_kind.startswith("reverify-r")
+    ]
+    if initial_jobs:
+        validate_initial_prompts(manifest, initial_jobs)
+
+    reverify_jobs = [
+        job for job in jobs if job.dispatch_kind.startswith("reverify-r")
+    ]
+    if not reverify_jobs:
+        return
+    task_type = require_string(manifest, "taskType")
+    workflow = active_context.get("workflow")
+    if not isinstance(workflow, Mapping):
+        raise DispatchError("reverify prompt contract: active run workflow is missing")
+    forbidden_actions = string_value(workflow.get("forbiddenActions"))
+    if not forbidden_actions:
+        raise DispatchError(
+            "reverify prompt contract: workflow.forbiddenActions is missing"
+        )
+
+    errors: list[str] = []
+    for job in reverify_jobs:
+        try:
+            text = job.prompt_path.read_text(encoding="utf-8")
+        except OSError as exc:
+            errors.append(f"{job.worker_id}: cannot read prompt {job.prompt_path}: {exc}")
+            continue
+        errors.extend(
+            f"{job.worker_id}: {error}"
+            for error in validate_reverify_prompt(
+                text,
+                task_type=task_type,
+                forbidden_actions=forbidden_actions,
+            )
+        )
+    if errors:
+        raise DispatchError("reverify prompt contract: " + "; ".join(errors))
+
+
+def worker_jobs_from_file(
+    project_root: Path,
+    jobs_file: Path,
+    *,
+    backend: str,
+    idle_timeout_seconds: int,
+    default_dispatch_kind: str,
+    resolve_wrapper: Callable[[str], Path],
+    default_provider: Callable[[str], str],
+) -> list[WorkerJob]:
+    payload = load_json_object(
+        resolve_project_path(project_root, str(jobs_file)),
+        "jobs file",
+    )
+    dispatch_kind = string_value(payload.get("dispatchKind")) or default_dispatch_kind
+    workers = payload.get("workers")
+    if not isinstance(workers, list):
+        raise DispatchError("jobs file workers must be an array")
+    return [
+        _worker_job_from_file(
+            project_root,
+            item,
+            backend=backend,
+            idle_timeout_seconds=idle_timeout_seconds,
+            dispatch_kind=dispatch_kind,
+            resolve_wrapper=resolve_wrapper,
+            default_provider=default_provider,
+        )
+        for item in workers
+        if isinstance(item, Mapping)
+    ]
+
+
+def _worker_job_from_file(
+    project_root: Path,
+    item: Mapping[str, Any],
+    *,
+    backend: str,
+    idle_timeout_seconds: int,
+    dispatch_kind: str,
+    resolve_wrapper: Callable[[str], Path],
+    default_provider: Callable[[str], str],
+) -> WorkerJob:
+    worker_id = require_string(item, "workerId")
+    provider = string_value(item.get("provider")) or default_provider(worker_id)
+    prompt_path = resolve_project_path(
+        project_root, require_string(item, "promptPath")
+    )
+    result_path = resolve_project_path(
+        project_root, require_string(item, "resultPath")
+    )
+    worker_result_path = resolve_project_path(
+        project_root, require_string(item, "workerResultPath")
+    )
+    completion_paths = tuple(
+        resolve_project_path(project_root, path)
+        for path in string_list(item.get("completionPaths"))
+    ) or (result_path,)
+    return WorkerJob(
+        worker_id=worker_id,
+        provider=provider,
+        backend=backend,
+        project_root=project_root,
+        model_execution_value=require_string(item, "modelExecutionValue"),
+        wrapper_path=resolve_wrapper(provider),
+        prompt_path=prompt_path,
+        result_path=result_path,
+        worker_result_path=worker_result_path,
+        completion_paths=completion_paths,
+        worktree_path=string_value(item.get("worktreePath")),
+        role=require_string(item, "role"),
+        idle_timeout_seconds=idle_timeout_seconds,
+        dispatch_kind=dispatch_kind,
+    )
+
+
 def utc_now() -> str:
     return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")

package/runtime/python/okstra_ctl/path_hints.py

@@ -188,6 +188,7 @@ def _hydrate_active_run(ctx: Mapping[str, str]) -> dict[str, str]:
         "teamStatePath": ctx.get("TEAM_STATE_RELATIVE_PATH", ""),
         "promptSnapshotPath": ctx.get("RUN_PROMPT_SNAPSHOT_RELATIVE_PATH", ""),
         "finalReportPath": ctx.get("FINAL_REPORT_RELATIVE_PATH", ""),
+        "convergenceStatePath": ctx.get("CONVERGENCE_STATE_RELATIVE_PATH", ""),
         "finalStatusPath": ctx.get("FINAL_STATUS_RELATIVE_PATH", ""),
         "validatorScriptPath": ctx.get("RUN_VALIDATOR_RELATIVE_PATH", ""),
         "resumeCommandPath": ctx.get("CLAUDE_RESUME_COMMAND_RELATIVE_PATH", ""),
@@ -430,6 +431,7 @@ def _run_files(
         "team_state": run_state / f"team-state{suffixes['state']}.json",
         "active_run_context": run_state / f"active-run-context{suffixes['state']}.json",
         "lead_events": run_state / f"lead-events-{task_type_segment}-{sequences['state']}.jsonl",
+        "convergence_state": run_state / f"convergence-{task_type_segment}-{sequences['state']}.json",
         "claude_resume_command": run_sessions / f"claude-resume{suffixes['sessions']}.sh",
         "claude_worker_result": worker_results / f"claude-worker{suffixes['worker_results']}.md",
         "codex_worker_result": worker_results / f"codex-worker{suffixes['worker_results']}.md",
@@ -540,6 +542,7 @@ def _absolute_run_fields(paths: Mapping[str, Any]) -> dict[str, str]:
         "RUN_CONTEXT_FILE": str(paths["run_context_file"]),
         "RUN_PROMPT_SNAPSHOT_FILE": str(paths["run_prompt_snapshot"]),
         "FINAL_REPORT_PATH": str(paths["final_report"]),
+        "CONVERGENCE_STATE_PATH": str(paths["convergence_state"]),
         "FINAL_STATUS_PATH": str(paths["final_status"]),
         "TEAM_STATE_PATH": str(paths["team_state"]),
         "ACTIVE_RUN_CONTEXT_PATH": str(paths["active_run_context"]),
@@ -629,6 +632,9 @@ def _relative_file_fields(project_root: Path, paths: Mapping[str, Any]) -> dict[
         "ANTIGRAVITY_WORKER_PROMPT_RELATIVE_PATH": _rel(project_root, paths["antigravity_worker_prompt"]),
         "REPORT_WRITER_WORKER_PROMPT_RELATIVE_PATH": _rel(project_root, paths["report_writer_worker_prompt"]),
         "FINAL_REPORT_RELATIVE_PATH": _rel(project_root, paths["final_report"]),
+        "CONVERGENCE_STATE_RELATIVE_PATH": _rel(
+            project_root, paths["convergence_state"]
+        ),
         "FINAL_STATUS_RELATIVE_PATH": _rel(project_root, paths["final_status"]),
         "TEAM_STATE_RELATIVE_PATH": _rel(project_root, paths["team_state"]),
         "ACTIVE_RUN_CONTEXT_RELATIVE_PATH": _rel(project_root, paths["active_run_context"]),

package/runtime/python/okstra_ctl/paths.py

@@ -66,19 +66,6 @@ def _newest_report(reports_dir: Path) -> Optional[Path]:
     return max(found, key=lambda p: (p.stat().st_mtime, p.name))
 
 
-def _report_dirs(type_dir: Path, include_stages: bool) -> list[Path]:
-    """한 task-type 의 report 디렉터리들. flat 은 항상, stage-<N> 은 opt-in.
-
-    stage-isolated task-type(implementation / final-verification)만 stage 하위를
-    갖는다. `include_stages` 가 꺼져 있으면 flat `reports/` 만 돌려준다 —
-    `latest_under` 의 원래 범위이자 resume-clarification 이 의존하는 계약이다.
-    """
-    dirs = [type_dir / "reports"]
-    if include_stages and type_dir.name in _STAGED_TASK_TYPES:
-        dirs += sorted(type_dir.glob("stage-*/reports"))
-    return dirs
-
-
 def _project_root_of(task_root: Path) -> Optional[Path]:
     """canonical `<project>/.okstra/tasks/<g>/<t>` 일 때만 project root.
 
@@ -264,42 +251,19 @@ class RunRef:
         return None if best is None else cls.from_report_path(best)
 
     @classmethod
-    def latest_across(
+    def latest_under(
         cls,
-        project_root: Path,
-        task_group: str,
-        task_id: str,
+        task_root: Path,
         task_types: Optional[tuple[str, ...]] = None,
-        *,
-        include_stages: bool = False,
     ) -> Optional["RunRef"]:
-        """여러 task-type 을 가로질러 최신 final-report 를 가리키는 ref.
+        """task_root 아래 여러 task-type 을 가로질러 최신 final-report 를 찾는다.
 
         `task_types` 를 주지 않으면 runs/ 에 실제로 존재하는 모든 task-type 을
         훑는다. 비교 규칙은 `latest` 와 같다(mtime, 동률이면 basename).
 
-        `include_stages` 를 켜면 stage-isolated task-type 의 `stage-<N>/reports/`
-        도 함께 훑는다 — phase-cleanup 이 staged run 을 자동발견할 때 쓴다.
-        """
-        return cls.latest_under(
-            task_dir(project_root, task_group, task_id),
-            task_types,
-            include_stages=include_stages,
-        )
-
-    @classmethod
-    def latest_under(
-        cls,
-        task_root: Path,
-        task_types: Optional[tuple[str, ...]] = None,
-        *,
-        include_stages: bool = False,
-    ) -> Optional["RunRef"]:
-        """`latest_across` 의 task_root 진입점.
-
         task-key 단축키/오타 진단을 이미 거쳐 task_root 를 손에 쥔 호출자
         (bash resume-clarification)가 쓴다. 그 호출자는 언제나 flat 분석 phase 만
-        넘기므로 기본값(`include_stages=False`)이 그 범위를 그대로 보존한다.
+        넘기므로 stage 하위는 훑지 않는다 — flat `reports/` 고정이 그 계약이다.
         """
         runs_dir = runs_dir_of(task_root)
         if task_types is None:
@@ -308,10 +272,9 @@ class RunRef:
             task_types = tuple(sorted(p.name for p in runs_dir.iterdir() if p.is_dir()))
         candidates: list[Path] = []
         for task_type in task_types:
-            for reports_dir in _report_dirs(runs_dir / task_type, include_stages):
-                found = _newest_report(reports_dir)
-                if found is not None:
-                    candidates.append(found)
+            found = _newest_report(runs_dir / task_type / "reports")
+            if found is not None:
+                candidates.append(found)
         if not candidates:
             return None
         return cls.from_report_path(

package/runtime/python/okstra_ctl/render.py

@@ -347,6 +347,7 @@ def _active_run(ctx: dict) -> dict:
         "teamStatePath": ctx.get("TEAM_STATE_RELATIVE_PATH", ""),
         "promptSnapshotPath": ctx.get("RUN_PROMPT_SNAPSHOT_RELATIVE_PATH", ""),
         "finalReportPath": ctx.get("FINAL_REPORT_RELATIVE_PATH", ""),
+        "convergenceStatePath": ctx.get("CONVERGENCE_STATE_RELATIVE_PATH", ""),
         "finalStatusPath": ctx.get("FINAL_STATUS_RELATIVE_PATH", ""),
         "validatorScriptPath": ctx.get("RUN_VALIDATOR_RELATIVE_PATH", ""),
         "resumeCommandPath": ctx.get("CLAUDE_RESUME_COMMAND_RELATIVE_PATH", ""),
@@ -1389,6 +1390,7 @@ def render_run_manifest(run_manifest_path: str, ctx: dict) -> None:
         "expectedStatusPath": ctx.get("FINAL_STATUS_RELATIVE_PATH", ""),
         "teamStatePath": ctx.get("TEAM_STATE_RELATIVE_PATH", ""),
         "activeRunContextPath": ctx.get("ACTIVE_RUN_CONTEXT_RELATIVE_PATH", ""),
+        "convergenceStatePath": ctx.get("CONVERGENCE_STATE_RELATIVE_PATH", ""),
         "analysisPacketPath": ctx.get("ANALYSIS_PACKET_RELATIVE_PATH", ""),
         "analysisEvidencePath": (
             ctx.get("INSTRUCTION_SET_RELATIVE_PATH", "") + "/analysis-evidence.md"

package/runtime/python/okstra_ctl/wizard.py

@@ -160,6 +160,7 @@ _BRIEF_ENTRY_TASK_TYPES = (
 
 CANONICAL_BASE_REFS = ["main", "dev", "staging", "preprod", "prod"]
 BASE_REF_FREE_INPUT_TOKEN = "__free_input__"
+HOST_PICK_OPTION_CAP = 4
 
 CLAUDE_MODEL_OPTIONS = ["default", *picker_options("claude")]
 CODEX_MODEL_OPTIONS = ["default", *picker_options("codex")]
@@ -498,6 +499,8 @@ class Prompt:
             "echoTemplate": self.echo_template,
             "multi": self.multi,
         }
+        if self.kind == "pick" and len(self.options) > HOST_PICK_OPTION_CAP:
+            out["presentation"] = "numbered-text"
         if self.kind == "pick_group":
             out["questions"] = [
                 {"step": q.step, "label": q.label,
@@ -512,6 +515,35 @@ class WizardError(Exception):
     """validation failure surfaced to user."""
 
 
+def _normalize_numbered_pick_item(prompt: Prompt, answer: str) -> str:
+    candidate = (answer or "").strip()
+    exact_values = [option.value for option in prompt.options if option.value == candidate]
+    if exact_values:
+        return exact_values[0]
+
+    if candidate.isdecimal():
+        number = int(candidate)
+        if 1 <= number <= len(prompt.options):
+            return prompt.options[number - 1].value
+        raise WizardError(f"numbered-text answer is out of range: {candidate}")
+
+    label_values = [option.value for option in prompt.options if option.label == candidate]
+    if len(label_values) == 1:
+        return label_values[0]
+    if len(label_values) > 1:
+        raise WizardError(f"numbered-text answer label is ambiguous: {candidate}")
+    raise WizardError(f"numbered-text answer is not an option: {candidate}")
+
+
+def _normalize_numbered_pick_answer(prompt: Prompt, answer: str) -> str:
+    if prompt.multi:
+        return ",".join(
+            _normalize_numbered_pick_item(prompt, item)
+            for item in (answer or "").split(",")
+        )
+    return _normalize_numbered_pick_item(prompt, answer)
+
+
 # ---- Validation helpers --------------------------------------------------
 
 _SLUG_OK = re.compile(r"[a-z0-9]")
@@ -4328,6 +4360,8 @@ def submit(state: WizardState, value: str) -> dict[str, Any]:
         return {"echo": "", "next": prompt_payload(state, prompt)}
     if prompt.kind == "pick_group":
         return _submit_group(state, prompt, value)
+    if prompt.kind == "pick" and len(prompt.options) > HOST_PICK_OPTION_CAP:
+        value = _normalize_numbered_pick_answer(prompt, value)
     step = STEP_BY_ID[prompt.step]
     echo = step.submit(state, value or "")
     if prompt.step not in state.answered:

package/runtime/python/okstra_ctl/worker_liveness.py

@@ -15,10 +15,10 @@ Two probes, matching the two ways a pending worker goes quiet:
 * ``--audit`` — an in-process worker audit sidecar. Stale past the heartbeat
   cadence (or present with no heartbeat at all) means the worker hung. Uses
   the same line shape and budget the Phase 7 validator applies.
-* ``--prompt`` — a CLI-wrapper prompt-history path. Neither `<prompt>.log` nor
-  `<prompt>.status.json` past the launch grace means the wrapper never ran —
-  the dispatch itself failed, which no artifact otherwise distinguishes from a
-  worker that has merely not finished.
+* ``--team-state`` + ``--worker`` — a CLI-wrapper assignment. Neither the
+  worker's `<prompt>.log` nor `<prompt>.status.json` past the launch grace means
+  the wrapper never ran. The grace starts at the persisted dispatch timestamp,
+  not when the prompt was materialized.
 """
 from __future__ import annotations
 
@@ -28,6 +28,7 @@ import sys
 from datetime import datetime, timezone
 from pathlib import Path
 
+from okstra_ctl.dispatch_state import DispatchError, load_json_object
 from okstra_ctl.worker_heartbeat import (
     HEARTBEAT_MAX_GAP_SECONDS,
     latest_heartbeat,
@@ -80,43 +81,97 @@ def probe_heartbeat(sidecar: Path, now: datetime, max_idle: float) -> dict:
     }
 
 
-def probe_launch(prompt: Path, now: datetime, grace: float) -> dict:
+def probe_launch(
+    prompt: Path, dispatched_at: datetime, now: datetime, grace: float
+) -> dict:
     """Whether the wrapper behind *prompt* ever started."""
     log, status = _log_path(prompt), Path(f"{prompt}.status.json")
     probe = {"kind": "launch", "path": str(prompt)}
     if log.exists() or status.exists():
         return {**probe, "state": "live", "reason": ""}
-    if not prompt.is_file():
-        return {**probe, "state": "pending", "reason": "prompt history not written yet"}
-    waited = now.timestamp() - prompt.stat().st_mtime
+    waited = (now - dispatched_at).total_seconds()
     if waited <= grace:
-        return {**probe, "state": "pending", "reason": "within launch grace"}
+        return {
+            **probe,
+            "state": "pending",
+            "waitedSeconds": int(waited),
+            "reason": "within launch grace",
+        }
     return {
         **probe,
         "state": "did-not-launch",
         "waitedSeconds": int(waited),
         "reason": (
             f"neither {log.name} nor {status.name} exists {int(waited)}s after the "
-            f"prompt was written (grace {int(grace)}s)"
+            f"dispatch started (grace {int(grace)}s)"
         ),
     }
 
 
 def probe_all(
     audits: list[str],
-    prompts: list[str],
+    launches: list[tuple[str, datetime]],
     *,
     now: datetime,
     max_idle: float,
     launch_grace: float,
 ) -> dict:
     probes = [probe_heartbeat(Path(p), now, max_idle) for p in audits]
-    probes += [probe_launch(Path(p), now, launch_grace) for p in prompts]
+    probes += [
+        probe_launch(Path(prompt), dispatched_at, now, launch_grace)
+        for prompt, dispatched_at in launches
+    ]
     unhealthy = [p for p in probes if p["state"] in ("stalled", "did-not-launch")]
     return {"ok": not unhealthy, "checkedAt": now.isoformat(), "probes": probes,
             "unhealthy": unhealthy}
 
 
+def _parse_utc(value: object, label: str) -> datetime:
+    if not isinstance(value, str) or not value:
+        raise DispatchError(f"{label} must be a UTC ISO timestamp")
+    try:
+        instant = datetime.fromisoformat(value.replace("Z", "+00:00"))
+    except ValueError as exc:
+        raise DispatchError(f"{label} must be a UTC ISO timestamp") from exc
+    if instant.tzinfo is None or instant.utcoffset() != timezone.utc.utcoffset(instant):
+        raise DispatchError(f"{label} must be a UTC ISO timestamp")
+    return instant.astimezone(timezone.utc)
+
+
+def _project_root_for_team_state(team_state_path: Path) -> Path:
+    for parent in team_state_path.resolve().parents:
+        if parent.name == ".okstra":
+            return parent.parent
+    raise DispatchError(
+        f"team-state is outside a project .okstra directory: {team_state_path}"
+    )
+
+
+def _launch_target(team_state_value: str, worker_id: str) -> tuple[str, datetime]:
+    team_state_path = Path(team_state_value).resolve()
+    state = load_json_object(team_state_path, "team-state")
+    workers = state.get("workers")
+    if not isinstance(workers, list):
+        raise DispatchError(f"team-state workers must be an array: {team_state_path}")
+    worker = next(
+        (
+            row for row in workers
+            if isinstance(row, dict) and row.get("workerId") == worker_id
+        ),
+        None,
+    )
+    if worker is None:
+        raise DispatchError(f"team-state has no workerId={worker_id}: {team_state_path}")
+    prompt_value = worker.get("promptPath")
+    if not isinstance(prompt_value, str) or not prompt_value.strip():
+        raise DispatchError(f"worker {worker_id} has no promptPath")
+    prompt = Path(prompt_value)
+    if not prompt.is_absolute():
+        prompt = _project_root_for_team_state(team_state_path) / prompt
+    dispatched_at = _parse_utc(worker.get("startedAt"), f"worker {worker_id} startedAt")
+    return str(prompt), dispatched_at
+
+
 def main(argv: list[str] | None = None) -> int:
     parser = argparse.ArgumentParser(
         prog="okstra worker-liveness",
@@ -124,12 +179,10 @@ def main(argv: list[str] | None = None) -> int:
     )
     parser.add_argument("--audit", action="append", default=[],
                         help="in-process worker audit sidecar path (repeatable)")
-    parser.add_argument("--prompt", action="append", default=[],
-                        help="CLI-wrapper (codex/antigravity) prompt-history path "
-                             "(repeatable). Only the wrappers write the artifacts "
-                             "this probe looks for, so passing an in-process "
-                             "claude-worker path here always reports "
-                             "did-not-launch — probe those with --audit")
+    parser.add_argument("--team-state", action="append", default=[],
+                        help="team-state path for a CLI-wrapper assignment (repeatable)")
+    parser.add_argument("--worker", action="append", default=[],
+                        help="worker id paired with --team-state (repeatable)")
     parser.add_argument("--max-idle", type=float, default=HEARTBEAT_MAX_GAP_SECONDS,
                         help="heartbeat staleness budget in seconds")
     parser.add_argument("--launch-grace", type=float, default=DEFAULT_LAUNCH_GRACE_SECONDS,
@@ -137,12 +190,22 @@ def main(argv: list[str] | None = None) -> int:
     parser.add_argument("--json", action="store_true", help="emit JSON (always on)")
     args = parser.parse_args(argv)
 
-    if not args.audit and not args.prompt:
-        parser.error("pass at least one --audit or --prompt path")
+    if len(args.team_state) != len(args.worker):
+        parser.error("each --team-state must have one paired --worker")
+    if not args.audit and not args.team_state:
+        parser.error("pass at least one --audit or --team-state/--worker pair")
+
+    try:
+        launches = [
+            _launch_target(team_state, worker)
+            for team_state, worker in zip(args.team_state, args.worker, strict=True)
+        ]
+    except DispatchError as exc:
+        parser.error(str(exc))
 
     result = probe_all(
         args.audit,
-        args.prompt,
+        launches,
         now=datetime.now(timezone.utc),
         max_idle=args.max_idle,
         launch_grace=args.launch_grace,

package/runtime/python/okstra_ctl/worker_prompt_body.py

@@ -90,8 +90,8 @@ def report_writer_prompt_body(
         "",
         "## Role",
         (
-            "You are the Report writer worker. Author the final-report data.json "
-            "and the worker-results audit file."
+            "You are the Report writer worker. Author the final-report data.json, "
+            "its rendered Markdown sibling, and the worker-result pointer."
         ),
         "",
         "## Task",
@@ -104,9 +104,15 @@ def report_writer_prompt_body(
         mcp_pointer_line(),
         "",
         "## Output Contract",
-        "You are the author of TWO files:",
+        "You are the author of THREE files:",
         "- The final-report data.json at Result Path.",
-        "- The worker-results audit file at Audit sidecar path.",
+        "- The rendered Markdown sibling produced through okstra render-final-report.",
+        "- The worker-result pointer at Worker Result Path.",
+        (
+            "Keep the pointer to three entries: the data.json path, rendered "
+            "Markdown path, and Convergence state input path."
+        ),
+        "Maintain the separate audit sidecar at Audit sidecar path.",
         (
             'After writing the data.json, invoke "okstra render-final-report '
             '<Result Path>" so the markdown sibling is rendered before you return.'
@@ -129,6 +135,7 @@ def report_writer_input_lines(
         ("Clarification response", instruction_path(manifest, active_context, "clarificationResponsePath")),
         ("Final report template", instruction_path(manifest, active_context, "finalReportTemplatePath")),
         ("Final report schema", instruction_path(manifest, active_context, "finalReportSchemaPath")),
+        ("Convergence state", run_path(manifest, active_context, "convergenceStatePath")),
         ("Worker results directory", _string_value(manifest.get("workerResultsDirectoryPath"))),
     ]
     lines = existing_input_lines(inputs)
@@ -171,6 +178,19 @@ def instruction_path(
     return _string_value(manifest.get(key))
 
 
+def run_path(
+    manifest: Mapping[str, Any],
+    active_context: Mapping[str, Any],
+    key: str,
+) -> str:
+    run = active_context.get("run")
+    if isinstance(run, Mapping):
+        value = _string_value(run.get(key))
+        if value:
+            return value
+    return _string_value(manifest.get(key))
+
+
 def mcp_pointer_line() -> str:
     return (
         '**MCP servers:** follow the task brief\'s "## Available MCP Servers" '