okstra 0.173.0 → 0.174.0

package/runtime/python/okstra_ctl/adapters/hosts/external/relay.md

@@ -2,7 +2,7 @@
 
 ## Scope
 
-This adapter maps the neutral Okstra lead operations to a generic host using Okstra-owned tmux panes. Read it only when the rendered launch prompt selects `leadRuntime=external`.
+This adapter maps the neutral Okstra lead operations to a generic host. Workers run as Okstra-owned CLI wrapper subprocesses; the host is not asked to provide a pane for them. Read it only when the rendered launch prompt selects `leadRuntime=external`.
 
 ## Capability declaration
 
@@ -11,11 +11,11 @@ This adapter maps the neutral Okstra lead operations to a generic host using Oks
 | `runtime` | `external` |
 | `leadRoleLabel` | `Okstra lead` |
 | `userPromptMode` | `host-text` |
-| `workerDispatchBackend` | `tmux-pane` |
-| `initialPromptDeliveryMode` | `lazy-path-reference` |
+| `workerDispatchBackend` | `cli-wrapper` |
+| `initialPromptDeliveryMode` | `eager-include` |
 | `sessionAccounting` | `artifact-only` |
 | `resumeMode` | `artifact-checkpoint` |
-| `teardownMode` | `pane-teardown` |
+| `teardownMode` | `process-cleanup` |
 | `leadEventSource` | `lead-events-jsonl` |
 
 ## Wizard interaction relay

package/runtime/python/okstra_ctl/adapters/providers/claude/adapter.py

@@ -54,6 +54,11 @@ class ClaudeExecution:
 
     def build_command(self, request: WorkerExecRequest) -> ExecCommand:
         argv = ["claude", "-p", "--model", request.model]
+        # The dispatcher's id, not the CLI's own: it is what team-state records,
+        # so token collection reads this worker's jsonl instead of guessing at
+        # `agentName` — which a pane-dispatched CLI never writes.
+        if request.session_id:
+            argv += ["--session-id", request.session_id]
         for directory in request.policy.write_scope:
             if directory != request.project_root:
                 argv += ["--add-dir", str(directory)]

package/runtime/python/okstra_ctl/conformance.py

@@ -25,6 +25,74 @@ EXTERNAL_ADVISORY_CAPABILITIES: frozenset[str] = frozenset(
 )
 
 
+# --- 계획 산출물의 stage conformance 선언 파싱 ---
+#
+# 정본 형식은 prompts/profiles/implementation-planning.md 의
+# `Conformance tests: stage-<N> — <script> (requires=[db|io|http|external,...])`
+# 이고, data.json 의 `conformanceTests` 는 그 줄에서 `stage-<N> — ` 접두사를 뗀
+# 나머지다. 승인 경계(run.py `_validate_approved_plan`)와 구현 런 끝
+# (validators/validate-run.py)이 이 한 규칙을 같이 읽는다 — 규칙을 두 곳에
+# 복제하면 승인은 통과하는데 구현 런은 막히는 상태가 다시 만들어진다.
+_CONFORMANCE_TESTS_RE = re.compile(
+    r"^(?P<script>\S+)\s+\(requires=\[(?P<requires>[^\]]+)\]\)$"
+)
+
+
+def normalize_conformance_script(script: str) -> str:
+    """`<task_root>/` 접두사를 뗀다. 선언과 매니페스트 entry 가 같은 스크립트를
+    서로 다른 접두사로 적을 수 있어, 대조 전에 양쪽을 이 형태로 맞춘다."""
+    prefix = "<task_root>/"
+    return script[len(prefix):] if script.startswith(prefix) else script
+
+
+def parse_conformance_tests(value: object) -> tuple[str, frozenset[str]] | None:
+    """stage 선언의 `<script> (requires=[cap,...])` 를 파싱. 형식이 아니면 None."""
+    if not isinstance(value, str):
+        return None
+    match = _CONFORMANCE_TESTS_RE.fullmatch(value.strip())
+    if match is None:
+        return None
+    script = normalize_conformance_script(match.group("script"))
+    capabilities = [part.strip() for part in match.group("requires").split(",")]
+    if (
+        not script
+        or any(not capability for capability in capabilities)
+        or len(set(capabilities)) != len(capabilities)
+        or any(capability not in CAPABILITY_WHITELIST for capability in capabilities)
+    ):
+        return None
+    return script, frozenset(capabilities)
+
+
+def malformed_conformance_stages(data: object) -> list[int]:
+    """`conformanceTests` 를 선언했으나 파싱되지 않는 stage 번호들.
+
+    선언이 아예 없는 stage 는 대상이 아니다 — 둘 중 하나를 요구하는 XOR 은
+    validators/validate-implementation-plan-stages.py 의 check S11 이 계획
+    단계에서 이미 판정한다. `stage` 가 양의 정수가 아닌 경우도 여기 몫이 아니다:
+    스키마(`stage: integer, minimum 1`)가 계획 런의 validate-run 에서 먼저 막는다.
+    `conformanceTests` 가 문자열이 아닌 경우도 같은 이유로 뺀다 — 스키마가
+    `type: string, minLength: 1` 로 못박아 그 값은 계획 런의 validate-run 을
+    통과하지 못한다. 여기서 그것까지 malformed 로 세면 스키마가 이미 낸 판정을
+    이 게이트가 다른 문구로 되풀이한다.
+    """
+    planning = data.get("implementationPlanning") if isinstance(data, dict) else None
+    stages = planning.get("stages") if isinstance(planning, dict) else None
+    bad: list[int] = []
+    for stage in stages if isinstance(stages, list) else []:
+        if not isinstance(stage, dict):
+            continue
+        declared = stage.get("conformanceTests")
+        if not isinstance(declared, str) or not declared.strip():
+            continue
+        number = stage.get("stage")
+        if not isinstance(number, int) or isinstance(number, bool) or number < 1:
+            continue
+        if parse_conformance_tests(declared) is None:
+            bad.append(number)
+    return bad
+
+
 def is_advisory_conformance_entry(entry: object) -> bool:
     """Return whether one entry depends on user-owned external QA."""
     if not isinstance(entry, dict):

package/runtime/python/okstra_ctl/dispatch_core.py

@@ -10,18 +10,18 @@ from pathlib import Path
 from typing import Any, Mapping, Sequence
 
 from . import cmux
-from . import tmux
 from .dispatch_state import (
     BACKEND_CLI_WRAPPER,
     BACKEND_CMUX_PANE,
     BACKEND_MIXED,
-    BACKEND_TMUX_PANE,
     append_worker_dispatch as _append_worker_dispatch,
+    build_dispatch_id as _build_dispatch_id,
     DispatchError,
     WorkerJob,
     dispatch_completion_paths as _completion_paths,
     dispatch_mode as _dispatch_mode,
     dispatch_result_path as _result_path_for_worker,
+    dispatch_session_id as _dispatch_session_id,
     LIVENESS_AUDIT_HEARTBEAT,
     LIVENESS_WRAPPER_STATUS,
     load_json_object as _load_json_object,
@@ -203,6 +203,9 @@ def build_dispatch_plan(
             requested_workers,
             options,
         )
+    # Ahead of the per-prompt checks: a batch the lead must split is a plan-shape
+    # problem, and reporting a prompt-header error for a doomed batch buries it.
+    _validate_implementation_phase_order(jobs)
     _validate_dispatch_prompts(manifest, active_context, jobs)
     _reject_stale_schema_excerpt(project_root, manifest, jobs)
     return DispatchPlan(
@@ -219,12 +222,13 @@ def build_dispatch_plan(
 
 def dispatch_plan(plan: DispatchPlan, *, wait: bool = True) -> int:
     _validate_report_writer_isolation(plan.jobs)
+    _validate_implementation_phase_order(plan.jobs)
     if wait:
         pane_backends = sorted(
             {
                 job.backend
                 for job in plan.jobs
-                if job.backend in (BACKEND_TMUX_PANE, BACKEND_CMUX_PANE)
+                if job.backend == BACKEND_CMUX_PANE
             }
         )
         if pane_backends:
@@ -250,6 +254,7 @@ def dispatch_cli_wrapper_plan(plan: DispatchPlan) -> int:
     if any(job.backend != BACKEND_CLI_WRAPPER for job in plan.jobs):
         raise DispatchError("concurrent CLI dispatch requires cli-wrapper jobs only")
     _validate_report_writer_isolation(plan.jobs)
+    _validate_implementation_phase_order(plan.jobs)
     _record_dispatch_facts(plan.team_state_path, _dispatch_mode(plan.jobs))
     final_codes = _dispatch_cli_wrapper_batch(plan, plan.jobs)
     return next((final_codes[job.worker_id] for job in plan.jobs
@@ -267,6 +272,55 @@ def _validate_report_writer_isolation(jobs: Sequence[WorkerJob]) -> None:
         )
 
 
+def _validate_implementation_phase_order(jobs: Sequence[WorkerJob]) -> None:
+    """Keep the executor and the verifiers in two dispatches, never one batch.
+
+    A verifier reads the diff the executor wrote, so `implementation.md` binds
+    its contract to the window "between Executor stage completion and the first
+    verifier dispatch". Nothing enforced that ordering: one
+    `okstra team dispatch --workers claude,codex` started both at once and the
+    verifier observed base HEAD instead of the stage diff, which is what its
+    result then reported on.
+
+    The refusal names the worker IDs on both sides because the second dispatch
+    has to drop the executor's ID: `worker_prompt_policy` re-materializes that
+    ID as the executor every time, so a `--workers` list that keeps it is
+    refused again and a message saying only "split the batch" would loop.
+
+    `build_dispatch_plan` is the only call every production dispatch takes, and
+    the one `--dry-run` stops at, so it is what makes the preview refuse. The
+    two dispatch entry points are public and take a caller-assembled plan, so
+    they check it again there rather than trust their input.
+    """
+    executors = [
+        job.worker_id for job in jobs if job.audience == "implementation-executor"
+    ]
+    verifiers = [
+        job.worker_id for job in jobs if job.audience == "implementation-verifier"
+    ]
+    if executors and verifiers:
+        executor_ids = ", ".join(executors)
+        raise DispatchError(
+            "an implementation batch may not hold the executor and a verifier: "
+            f"{_named_role(executors, 'executor')}, "
+            f"{_named_role(verifiers, 'verifier')}. "
+            "Dispatch the executor alone, settle it with `okstra team await`, "
+            f"then dispatch the verifiers with `--workers` omitting {executor_ids} "
+            "— that worker ID materializes as the executor again, so a second "
+            "batch holding it is refused too. The split is what lets a verifier "
+            "observe the stage diff instead of base HEAD"
+        )
+
+
+def _named_role(worker_ids: Sequence[str], role: str) -> str:
+    """`verifier codex` for one, `verifiers codex, antigravity` for several.
+
+    A roster that adds antigravity puts two verifiers in the same refusal, and
+    a singular label there reads as one worker named "codex, antigravity".
+    """
+    return f"{role}{'s' if len(worker_ids) > 1 else ''} {', '.join(worker_ids)}"
+
+
 def _dispatch_cli_wrapper_batch(
     plan: DispatchPlan,
     jobs: Sequence[WorkerJob],
@@ -317,7 +371,7 @@ def _dispatch_cli_wrapper_batch(
                     "worker-retry-scheduled",
                     _retry_details(job, attempt, outcome),
                 )
-                next_round.append((job, attempt + 1))
+                next_round.append((_job_for_next_attempt(job), attempt + 1))
                 continue
             final_codes[job.worker_id] = outcome.returncode or 1
         pending = next_round
@@ -608,6 +662,7 @@ def _job_from_roster_worker(
         role=fact.role,
         idle_timeout_seconds=options.idle_timeout_seconds,
         dispatch_kind=options.dispatch_kind,
+        session_id=_dispatch_session_id(fact.provider),
         **invocation,
     )
 
@@ -668,7 +723,7 @@ def _materialize_roster_prompts(
                 project_root=project_root,
                 run_manifest_path=manifest_path,
                 runtime_root=workspace_root,
-                delivery_mode=_delivery_mode(options.default_backend),
+                delivery_mode=PromptDeliveryMode.EAGER_INCLUDE,
                 workers=tuple(
                     InitialPromptWorkerRequest(fact.worker_id, fact.model)
                     for fact in worker_facts
@@ -696,12 +751,6 @@ def _roster_worker_facts(
     )
 
 
-def _delivery_mode(default_backend: str) -> PromptDeliveryMode:
-    if default_backend == BACKEND_TMUX_PANE:
-        return PromptDeliveryMode.LAZY_PATH_REFERENCE
-    return PromptDeliveryMode.EAGER_INCLUDE
-
-
 def _jobs_from_file(
     project_root: Path,
     workspace_root: Path,
@@ -772,6 +821,7 @@ def _dispatch_job_with_retry(plan: DispatchPlan, job: WorkerJob) -> int:
             return 0
         if _should_retry(outcome, attempt):
             _append_event(plan, "worker-retry-scheduled", _retry_details(job, attempt, outcome))
+            job = _job_for_next_attempt(job)
             continue
         return outcome.returncode or 1
     return 1
@@ -780,8 +830,6 @@ def _dispatch_job_with_retry(plan: DispatchPlan, job: WorkerJob) -> int:
 def _start_job(plan: DispatchPlan, job: WorkerJob) -> WorkerHandle:
     if job.backend == BACKEND_CLI_WRAPPER:
         return _run_cli_wrapper(plan, job, "")
-    if job.backend == BACKEND_TMUX_PANE:
-        return _start_tmux_or_degrade(plan, job)
     if job.backend == BACKEND_CMUX_PANE:
         return _start_cmux_or_degrade(plan, job)
     raise DispatchError(f"unsupported worker backend: {job.backend}")
@@ -829,23 +877,6 @@ def _opened_cmux_surfaces(team_state_path: Path) -> tuple[str, ...]:
     return tuple(opened)
 
 
-def _start_tmux_or_degrade(plan: DispatchPlan, job: WorkerJob) -> WorkerHandle:
-    lead_pane = tmux.resolve_caller_pane()
-    if not lead_pane:
-        return _run_cli_wrapper(plan, job, BACKEND_TMUX_PANE)
-    try:
-        pane_id = tmux.split_worker_pane(
-            target_pane=lead_pane,
-            cwd=plan.project_root,
-            command=job.command,
-            title=f"{job.worker_id}-worker",
-            run_dir=_run_dir(plan),
-        )
-    except RuntimeError:
-        return _run_cli_wrapper(plan, job, BACKEND_TMUX_PANE)
-    return WorkerHandle(job, pane_id, None, status_path_for_prompt(job.prompt_path), "")
-
-
 def _refuse_when_cmux_is_walled_off() -> None:
     """Stop rather than degrade when a sandbox stands between okstra and cmux.
 
@@ -955,7 +986,9 @@ def _retry_from_record(
         plan, job, attempt, outcome, reason
     )
     _append_event(plan, "worker-retry-scheduled", details)
-    _spawn_job(plan, job, attempt + 1)
+    # The restored job settles attempt 1 above and must keep its session; only
+    # the attempt being opened here gets a new one.
+    _spawn_job(plan, _job_for_next_attempt(job), attempt + 1)
 
 
 def _finish_attempt(plan: DispatchPlan, job: WorkerJob, attempt: int, outcome: WorkerOutcome) -> None:
@@ -1038,7 +1071,7 @@ def _link_result(
         _link_agent_dispatch_result(
             project_root=plan.project_root,
             run_manifest_path=plan.manifest_path,
-            dispatch_id=f"{job.invocation_id}:attempt-{attempt}",
+            dispatch_id=_build_dispatch_id(job.invocation_id, attempt),
             result_path=job.worker_result_path,
         )
     except (DispatchError, OSError) as exc:
@@ -1300,6 +1333,10 @@ def _dispatch_record(
         "provider": job.provider,
         "status": status,
         "paneId": pane_id,
+        # The only handle on a pane worker's transcript: it runs as its own
+        # `claude -p` process and leaves no `agentName` in its session jsonl, so
+        # token collection resolves its usage by this value or not at all.
+        "sessionId": job.session_id,
         "promptPath": str(job.prompt_path),
         "resultPath": str(job.result_path),
         "workerResultPath": str(job.worker_result_path),
@@ -1317,7 +1354,7 @@ def _dispatch_record(
     }
     if job.invocation_id:
         record.update({
-            "dispatchId": f"{job.invocation_id}:attempt-{attempt}",
+            "dispatchId": _build_dispatch_id(job.invocation_id, attempt),
             "invocationId": job.invocation_id,
             "audience": job.audience,
             "assignmentRef": job.assignment_ref,
@@ -1330,7 +1367,7 @@ def _dispatch_record(
 
 
 def _liveness_mode(backend: str) -> str:
-    if backend in (BACKEND_CLI_WRAPPER, BACKEND_TMUX_PANE, BACKEND_CMUX_PANE):
+    if backend in (BACKEND_CLI_WRAPPER, BACKEND_CMUX_PANE):
         return LIVENESS_WRAPPER_STATUS
     return LIVENESS_AUDIT_HEARTBEAT
 
@@ -1585,6 +1622,10 @@ def _job_from_record(project_root: Path, record: Mapping[str, Any]) -> WorkerJob
         role=_require_string(record, "role"),
         idle_timeout_seconds=600,
         dispatch_kind=_require_string(record, "kind"),
+        # Restored, never re-issued: both callers rebuild a job from its record
+        # to settle a dispatch that already ran, and a fresh id would settle it
+        # against a session that never existed.
+        session_id=_string_value(record.get("sessionId")),
         invocation_id=_string_value(record.get("invocationId")),
         audience=_string_value(record.get("audience")),
         assignment_ref=_string_value(record.get("assignmentRef")),
@@ -1613,6 +1654,20 @@ def _should_retry(outcome: WorkerOutcome, attempt: int) -> bool:
     return outcome.returncode == 0 and bool(outcome.missing_completion_paths) and attempt < MAX_WORKER_ATTEMPTS
 
 
+def _job_for_next_attempt(job: WorkerJob) -> WorkerJob:
+    """The same work as a new attempt, which means a new session.
+
+    The first attempt's process is dead; a retry starts another one. Carrying
+    the id over would merge two processes into one attribution unit, and it
+    would hand `claude --session-id` a value that is already taken — behaviour
+    the CLI does not document. Every re-dispatch goes through here so no path
+    can quietly keep the old session.
+
+    A provider with no session flag gets '' back, so this is a no-op for it.
+    """
+    return replace(job, session_id=_dispatch_session_id(job.provider))
+
+
 def _failure_reason(outcome: WorkerOutcome) -> str:
     if outcome.timeout:
         return "worker wrapper timed out"
@@ -1709,11 +1764,6 @@ def _reject_stale_schema_excerpt(
     )
 
 
-def _run_dir(plan: DispatchPlan) -> Path:
-    value = _string_value(plan.manifest.get("runDirectoryPath"))
-    return _resolve_project_path(plan.project_root, value) if value else plan.team_state_path.parent.parent
-
-
 def _load_optional_json(project_root: Path, value: Any) -> dict[str, Any]:
     if not isinstance(value, str) or not value.strip():
         return {}

package/runtime/python/okstra_ctl/dispatch_state.py

@@ -1,8 +1,8 @@
 """Worker dispatch plumbing shared by both lead dispatchers.
 
 `dispatch_core` (claude / external lead) and `codex_dispatch` (codex lead) differ
-in capability — only the former has tmux panes, blocking waits, and retry from a
-persisted record. What they do *not* differ in is the job value object and the
+in capability — only the former has cmux surfaces, blocking waits, and retry from
+a persisted record. What they do *not* differ in is the job value object and the
 run's state files: the same run-manifest keys, the same team-state document, the
 same wrapper argv.
 
@@ -22,6 +22,7 @@ import fcntl
 import json
 import os
 import tempfile
+import uuid
 from dataclasses import dataclass
 from datetime import datetime, timezone
 from pathlib import Path
@@ -46,23 +47,22 @@ from .worker_prompt_contract import (
 from .worker_runner import LIVE, QUIET
 
 BACKEND_CLI_WRAPPER = "cli-wrapper"
-BACKEND_TMUX_PANE = "tmux-pane"
 BACKEND_CMUX_PANE = "cmux-pane"
 BACKEND_MIXED = "mixed"
 
 
 def detect_terminal_backend() -> str:
-    """Which pane backend this run gets. Called once, by prepare.
+    """Which backend this run's workers get. Called once, by prepare.
 
-    cmux wins wherever it is usable: the only thing a tmux session buys a lead
-    is Claude Code's AgentTeam, and the cmux path deliberately does not use it.
-    Everywhere else this answers `tmux-pane`, which is what every run got before
-    cmux existed. The answer is written to the run manifest and read back from
-    there — consumers must not re-detect, or two phases of one run can disagree.
+    cmux is the only backend that gives a worker a surface of its own. Without
+    it a worker runs as a cli-wrapper subprocess, which owns no pane and is read
+    through its status sidecar instead. The answer is written to the run manifest
+    and read back from there — consumers must not re-detect, or two phases of one
+    run can disagree.
     """
     if cmux.cmux_available():
         return BACKEND_CMUX_PANE
-    return BACKEND_TMUX_PANE
+    return BACKEND_CLI_WRAPPER
 
 # `livenessMode` picks which artifact answers "is this worker still alive": the
 # in-process worker's audit sidecar heartbeat, or the CLI wrapper's status
@@ -88,6 +88,18 @@ WORKER_STATUSES = frozenset(
 REASON_REQUIRED_STATUSES = frozenset({"timeout", "error", "not-run"})
 
 
+def generate_claude_session_id() -> str:
+    """A UUIDv4 for `claude --session-id`.
+
+    The lead mints one for its own session (`run`) and dispatch mints one per
+    worker (`dispatch_session_id`); they are the same kind of value, so one
+    generator serves both. It sits here rather than in `session` because
+    `session` imports this module, so a worker-side call the other way would
+    close an import cycle.
+    """
+    return str(uuid.uuid4())
+
+
 class DispatchError(Exception):
     """Raised when a worker dispatch request cannot be executed."""
 
@@ -119,11 +131,17 @@ class WorkerJob:
     prompt_digest: str = ""
     host_model_value: str | None = None
     enforcement_mode: str = ""
+    # The session id dispatch mints and carries through to the provider CLI, so
+    # token collection can find the worker's jsonl by this value rather than by
+    # guessing at `agentName`. A worker started in a cmux pane is a separate CLI
+    # process and leaves no `agentName` behind, so without this its usage cannot
+    # be attributed at all.
+    session_id: str = ""
 
     @property
     def command(self) -> list[str]:
         # The flag trails the positional contract the entrypoint reads by index.
-        return [
+        argv = [
             str(self.wrapper_path),
             str(self.project_root),
             self.model_execution_value,
@@ -134,6 +152,9 @@ class WorkerJob:
             "--presentation",
             self._presentation(),
         ]
+        if self.session_id:
+            argv += ["--session-id", self.session_id]
+        return argv
 
     def _presentation(self) -> str:
         # A pane is a screen a person watches; a cli-wrapper dispatch's stdout is
@@ -298,7 +319,23 @@ def append_worker_dispatch(
     team_state_path: Path,
     record: Mapping[str, Any],
 ) -> None:
-    """Append one worker dispatch without losing another state writer's update."""
+    """Record one worker dispatch without losing another state writer's update.
+
+    A row carrying a dispatch id replaces the row that already holds it rather
+    than stacking beside it: an observed lead re-sent `okstra team dispatch` for
+    a prompt and attempt it had already sent, team-state kept both copies, and
+    `validate-run` failed that run with `agent dispatch ID is duplicated`.
+
+    The replaced row takes its `paneId` with it, and recorded ids are the only
+    reclaim candidates `team._reclaimable_panes` has, so that pane is left on
+    screen for the session. That is the price of the trade: before this, the
+    same re-send cost the whole run its report.
+
+    A job with no invocation carries no dispatch id, so it has no key to
+    collapse on and folding those rows would merge two unrelated dispatches into
+    one. They still stack, and `update_worker_dispatch_status` settles the
+    newest of them.
+    """
     with _team_state_lock(team_state_path):
         payload = load_json_object(team_state_path, "team-state")
         dispatches = payload.setdefault("workerDispatches", [])
@@ -306,7 +343,20 @@ def append_worker_dispatch(
             raise DispatchError(
                 f"team-state workerDispatches must be an array: {team_state_path}"
             )
-        dispatches.append(dict(record))
+        new_record = dict(record)
+        new_id = str(new_record.get("dispatchId") or "")
+        replaced = False
+        if new_id:
+            for index, existing in enumerate(dispatches):
+                if (
+                    isinstance(existing, Mapping)
+                    and existing.get("dispatchId") == new_id
+                ):
+                    dispatches[index] = new_record
+                    replaced = True
+                    break
+        if not replaced:
+            dispatches.append(new_record)
         write_json(team_state_path, payload)
 
 
@@ -428,7 +478,9 @@ def record_verified_agent_dispatch(
     if not isinstance(prompt, Mapping):
         raise DispatchError("agent invocation prompt is missing")
     prompt_path = require_string(prompt, "path")
-    dispatch_id = f"{invocation_id}:attempt-1"
+    # One verified record per invocation: the conflict guard below refuses a
+    # second write under this id, so this path never numbers a retry.
+    dispatch_id = build_dispatch_id(invocation_id, 1)
     record = {
         "dispatchId": dispatch_id,
         "workerId": worker_id,
@@ -712,6 +764,25 @@ def _has_recorded_team_create(team_state: Mapping[str, Any]) -> bool:
 
 # --- job facts ----------------------------------------------------------------
 
+def build_dispatch_id(invocation_id: str, attempt: int) -> str:
+    """The only place Python assembles a dispatch id.
+
+    Two generators drifted: this module pinned the attempt to 1 while
+    `dispatch_core` used the real one, so a re-dispatch took the first attempt's
+    id, team-state kept the same row twice, and `validate-run` failed that run
+    with `agent dispatch ID is duplicated`.
+
+    Prose mirrors of this shape live outside Python, where no guard reaches
+    them: `prompts/lead/convergence.md`, `prompts/lead/report-writer.md`,
+    `prompts/lead/plan-body-verification.md` and the five
+    `adapters/hosts/*/relay.md` each spell an `--dispatch-id` argument out for
+    the lead. They agree with this function only because
+    `record_verified_agent_dispatch` records the first attempt and no other;
+    changing that convention has to change them too.
+    """
+    return f"{invocation_id}:attempt-{attempt}"
+
+
 def dispatch_mode(jobs: Sequence[WorkerJob]) -> str:
     backends = {job.backend for job in jobs}
     if len(backends) == 1:
@@ -723,6 +794,59 @@ def missing_completion_paths(job: WorkerJob) -> tuple[Path, ...]:
     return tuple(path for path in job.completion_paths if not path.is_file())
 
 
+def dispatch_session_id(provider: str) -> str:
+    """The session this dispatch mints for *provider*, or '' for one that has no
+    such flag.
+
+    Only the claude CLI reads `--session-id`; handing the value to another
+    wrapper would start it with an argument it does not know. An empty value is
+    the same as not issuing one — `WorkerJob.command` appends the flag only when
+    it is set.
+
+    This lives beside `worker_jobs_from_file` for the same reason
+    `dispatch_result_path` does: both job constructors apply it, and a rule
+    written twice is a rule that drifts.
+    """
+    return generate_claude_session_id() if provider == "claude" else ""
+
+
+def worker_session_ids(
+    team_state: Mapping[str, Any], worker_id: str | None = None
+) -> list[str]:
+    """The claude sessions this run's dispatches issued, in the order recorded.
+
+    A worker started in a cmux pane is its own `claude -p` process and tags its
+    session jsonl with neither `agentName` nor `teamName`, so nothing in the
+    transcript says which worker wrote it. The id `dispatch_session_id` minted
+    and `_dispatch_record` wrote is the only handle on it.
+
+    Every id, not one: a retry opens a new session, so one worker legitimately
+    owns several rows with different `sessionId` values, and taking only the
+    first or last bills a single attempt of a retried worker.
+
+    Pass ``worker_id`` for one worker's sessions, or omit it for the run's.
+    This reads a `workerDispatches[]` row shape, so it belongs beside the code
+    that writes that shape rather than in each of the two modules that read it.
+
+    A non-list log yields nothing rather than raising: `session.observe_lead_session`
+    calls this for its exclusion set and catches only OSError, so a `TypeError`
+    from iterating a number here would take down `team dispatch` / `team await` /
+    `report-finalize`. Observation not breaking its caller is a contract kept
+    here, the same way `add_observed_session` keeps it for the keys it appends to.
+    """
+    session_ids: list[str] = []
+    dispatches = team_state.get("workerDispatches")
+    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:
+            continue
+        session_id = str(record.get("sessionId") or "").strip()
+        if session_id and session_id not in session_ids:
+            session_ids.append(session_id)
+    return session_ids
+
+
 def dispatch_result_path(
     worker_id: str,
     worker_result_path: Path,
@@ -1006,6 +1130,10 @@ def _worker_job_from_file(
         role=require_string(item, "role"),
         idle_timeout_seconds=idle_timeout_seconds,
         dispatch_kind=dispatch_kind,
+        # Minted here, not read from the file: the lead writes this file by
+        # hand, and a session id it typed would be unfalsifiable — nothing can
+        # tell an id that names no session from one that names the wrong one.
+        session_id=dispatch_session_id(provider),
         invocation_id=string_value(item.get("invocationId")),
         audience=string_value(item.get("audience")),
         assignment_ref=string_value(item.get("assignmentRef")),

package/runtime/python/okstra_ctl/doctor.py

@@ -236,11 +236,11 @@ def _final_verification_checks(workspace: Path) -> list[DoctorCheck]:
         _file_check("validation command", workspace / "validators" / "validate-run.py"),
         _file_check(
             "final report template",
-            workspace / "templates" / "reports" / "final-report.template.md",
+            workspace / "templates" / "reports" / "final-report-v2.template.md",
         ),
         _file_check(
             "final report schema",
-            workspace / "schemas" / "final-report-v1.0.schema.json",
+            workspace / "schemas" / "final-report-v2.0.schema.json",
         ),
     ]
 

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

@@ -53,6 +53,11 @@ class WorkerExecRequest:
     worktree_path: Path | None
     policy: ExecutionPolicy
     idle_timeout_seconds: int
+    # The id the dispatcher chose, empty when it chose none. Only a CLI that
+    # accepts a session id reads it. Handing it over means the CLI does not
+    # issue its own, so the recorded id and the session's own jsonl are
+    # guaranteed to name the same session.
+    session_id: str = ""
 
 
 @dataclass(frozen=True)