okstra 0.177.0 → 0.178.0

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

@@ -44,12 +44,34 @@ ANTIGRAVITY = {
 }
 
 
+def _catalog_model_id(observed: str) -> str:
+    """Undo the dispatch-time tier suffix so the id is catalog-comparable.
+
+    Dispatch sends `gemini-3.1-pro-low`; agy serves that identity back
+    verbatim. The catalog holds the bare `gemini-3.1-pro`, so reading the
+    observation as-is made the served-model gate reject a model okstra itself
+    had asked for. Only suffixes dispatch can append are stripped, and only
+    when what remains is a catalog entry — anything else passes through for
+    the gate to judge.
+    """
+    if observed in ANTIGRAVITY:
+        return observed  # identity already carries its tier (agy's Claude models)
+    for suffix in model_discovery.dispatch_tier_suffixes():
+        bare = observed.removesuffix(f"-{suffix}")
+        if bare != observed and bare in ANTIGRAVITY:
+            return bare
+    return observed
+
+
 def normalise_served_model(raw_model: str | None) -> ServedModelAttestation:
     if not raw_model or not raw_model.strip():
         return ServedModelAttestation.unknown()
     model_id = raw_model.strip().lower().removeprefix("antigravity/")
     return ServedModelAttestation(
-        raw_model, f"antigravity/{model_id}", "exact", "provider-output"
+        raw_model,
+        f"antigravity/{_catalog_model_id(model_id)}",
+        "exact",
+        "provider-output",
     )
 
 

package/runtime/python/okstra_ctl/agent_invocation.py

@@ -1209,6 +1209,23 @@ def _render_prompt(
         f"**Runner:** {assignment.runner}",
         f"**Host runtime:** {assignment.host_runtime}",
     ]
+    # The dispatch prompt contract requires exactly one of these on every prompt
+    # it checks, and a critic pass is checked under the same contract as the
+    # initial analysis it audits — but only the initial-prompt path emitted one,
+    # so a dynamically materialized critic was refused. A dynamic prompt carries
+    # its instruction inline, which is what `eager-include` states; the initial
+    # path states the host's `initialPromptDeliveryMode` instead and puts it in
+    # `anchor_lines`, so defer to it when it is already there.
+    delivery_mode = "**Prompt Delivery Mode:**"
+    already_declared = any(
+        line.strip().startswith(delivery_mode)
+        for line in (
+            *request.instruction.anchor_lines,
+            *request.instruction.body.splitlines(),
+        )
+    )
+    if not already_declared:
+        header.append(f"{delivery_mode} eager-include")
     if assignment.host_model_value is not None:
         header.append(f"**Host model value:** {assignment.host_model_value}")
     duty_body = f"{common.body.rstrip()}\n\n{duty.body.rstrip()}"

package/runtime/python/okstra_ctl/agent_prompt_cli.py

@@ -304,6 +304,19 @@ def _materialize_run(
         "result",
         must_exist=False,
     )
+    if args.audience == "report-writer" and not args.audit_source:
+        # The report writer is the one audience whose result path is not its own
+        # worker result: it writes the report `data.json`, while the audit
+        # sidecar is derived from its `.md`. With both collapsed into one value
+        # the prompt loses its `**Worker Result Path:**` anchor and the writer
+        # puts the report where the audit file belongs — silently, because every
+        # header is still present and well-formed. The roster path derives both
+        # from the manifest; a dynamic call has to name them.
+        raise AgentPromptCliError(
+            "report-writer materialization requires --audit-source: --result is "
+            "the report data.json, --audit-source the worker-result .md the "
+            "audit sidecar is derived from"
+        )
     audit_source_path = (
         _authorized_path(
             project_root,

package/runtime/python/okstra_ctl/dispatch_core.py

@@ -65,6 +65,7 @@ from .domain.worker_runtime import (
 from .ports.worker_runtime import WorkerRuntimePort
 from .execution_identity import Attempt, Invocation, RoleExecution, model_spec_digest
 from .execution_manifest import (
+    ExecutionManifestError,
     finish_attempt_mutation,
     read_execution_manifest,
     record_invocation_attempt,
@@ -208,11 +209,23 @@ def verify_served_model(
         return attestation
     if role_execution.model_ref is None or not attestation.normalized_model_ref:
         raise DispatchError("served model differs from selected model")
+    # An unregistered ref and a genuine substitution are different failures.
+    # Folding both into "differs from selected" hid which one happened, and a
+    # catalog gap reads as a provider swapping the model out from under us.
     try:
         selected = pool.resolve(role_execution.model_ref)
+    except ValueError as exc:
+        raise DispatchError(
+            f"selected model is not in the catalog: {role_execution.model_ref}"
+        ) from exc
+    try:
         observed = pool.resolve(attestation.normalized_model_ref)
     except ValueError as exc:
-        raise DispatchError("served model differs from selected model") from exc
+        raise DispatchError(
+            "served model is not in the catalog: "
+            f"{attestation.normalized_model_ref} "
+            f"(provider reported {attestation.observed_model!r})"
+        ) from exc
     expected_level = "channel" if observed.version_kind == "channel" else "exact"
     if attestation.level != expected_level:
         raise DispatchError("served model attestation level is inconsistent")
@@ -1302,22 +1315,32 @@ def _spawn_job(
     batch_artifact_paths: Sequence[Path] = (),
 ) -> WorkerHandle:
     job = _prepare_job_attempt(plan, job, attempt)
-    contract = _persisted_write_contract(plan, job)
-    policies = (contract[0],) if contract else ()
-    snapshot = None
-    if contract is not None and contract[1].mutation_audit == "batch":
-        snapshot_path = _mutation_snapshot_path(job)
-        if snapshot_path.is_file():
-            snapshot = MutationSnapshot.from_payload(
-                _load_json_object(snapshot_path, "mutation audit snapshot")
-            )
-        else:
-            snapshot = _mutation_snapshot(
-                plan,
-                policies,
-                (job,),
-                round_artifact_paths=batch_artifact_paths,
-            )
+    # Everything between recording the attempt and starting the worker runs
+    # before any worker process exists. A failure here used to leave the attempt
+    # `started` forever: the manifest then refused attempt 1 again ("next
+    # attempt must be 2") and refused attempt 2 as well, because the prompt
+    # metadata still said attempt 1. The invocation had no way forward and the
+    # lead had to mint a new invocation id and prompt path to escape.
+    try:
+        contract = _persisted_write_contract(plan, job)
+        policies = (contract[0],) if contract else ()
+        snapshot = None
+        if contract is not None and contract[1].mutation_audit == "batch":
+            snapshot_path = _mutation_snapshot_path(job)
+            if snapshot_path.is_file():
+                snapshot = MutationSnapshot.from_payload(
+                    _load_json_object(snapshot_path, "mutation audit snapshot")
+                )
+            else:
+                snapshot = _mutation_snapshot(
+                    plan,
+                    policies,
+                    (job,),
+                    round_artifact_paths=batch_artifact_paths,
+                )
+    except Exception:
+        _abandon_unstarted_attempt(plan, job, attempt)
+        raise
     handle = replace(
         _start_job(plan, job),
         mutation_snapshot=snapshot,
@@ -1422,6 +1445,7 @@ def _mutation_snapshot(
         policies,
         orchestrator_paths=(
             *round_artifact_paths,
+            *_run_errors_log_path(plan),
             plan.manifest_path,
             plan.team_state_path,
             Path(f"{plan.team_state_path}.lock"),
@@ -1523,6 +1547,12 @@ def _worker_artifact_paths(plan: DispatchPlan, job: WorkerJob) -> tuple[Path, ..
         Path(audit_sidecar_rel(str(job.worker_result_path))),
         status_path_for_prompt(job.prompt_path),
         log_path_for_prompt(job.prompt_path),
+        # The prompt's three derived files are written together and belong in
+        # one list. The audit snapshot used to be listed only for the job whose
+        # snapshot it was, so a sibling's snapshot — written by okstra as that
+        # sibling started — landed inside this worker's window as an
+        # unauthorized artifact-root change.
+        _mutation_snapshot_path(job),
     }
     error_logs = active_context.get("errorLogs")
     if isinstance(error_logs, Mapping):
@@ -1534,6 +1564,26 @@ def _worker_artifact_paths(plan: DispatchPlan, job: WorkerJob) -> tuple[Path, ..
     return tuple(sorted(paths, key=str))
 
 
+def _run_errors_log_path(plan: DispatchPlan) -> tuple[Path, ...]:
+    """The run-level errors log, which the lead appends to while workers run.
+
+    The lead contract requires it to record an observed worker failure as soon
+    as it happens, so a worker still running at that moment sees the write. It
+    is a lead-owned run artifact like the manifest and the lead events log, and
+    is listed for the same reason.
+    """
+    active_context = _load_optional_json(
+        plan.project_root, plan.manifest.get("activeRunContextPath")
+    )
+    error_logs = active_context.get("errorLogs")
+    if not isinstance(error_logs, Mapping):
+        return ()
+    value = _string_value(error_logs.get("runErrorsLogPath"))
+    if not value:
+        return ()
+    return (_resolve_project_path(plan.project_root, value),)
+
+
 
 
 def _job_for_attempt(job: WorkerJob, attempt: int) -> WorkerJob:
@@ -1884,6 +1934,35 @@ def _out_of_plan_edit_paths(result_path: Path) -> tuple[str, ...]:
     )
 
 
+def _abandon_unstarted_attempt(
+    plan: DispatchPlan, job: WorkerJob, attempt: int
+) -> None:
+    """Close an attempt whose worker never started, so a retry can follow it.
+
+    `failed-no-mutation` is the truthful status: the dispatch died before the
+    worker process existed, so nothing wrote anything. It is also the only
+    terminal status the manifest lets another attempt follow.
+    """
+    if not job.has_execution_identity:
+        return
+    try:
+        finish_attempt_mutation(
+            plan.manifest_path,
+            invocation_ref=job.invocation_ref,
+            attempt=attempt,
+            finished_at=_utc_now(),
+            status="failed-no-mutation",
+            result_path=None,
+            error_path=None,
+            change_summary={},
+            task_key=_require_string(plan.manifest, "taskKey"),
+        )
+    except (ExecutionManifestError, DispatchError, OSError):
+        # The original dispatch failure is what the caller needs to see; a
+        # manifest that cannot be closed here is reported by the next read.
+        return
+
+
 def _finish_manifest_attempt(
     plan: DispatchPlan,
     job: WorkerJob,

package/runtime/python/okstra_ctl/dispatch_state.py

@@ -31,6 +31,8 @@ from typing import Any, Callable, Mapping, Sequence
 from . import cmux
 from .agent_invocation import (
     AgentInvocationError,
+    AgentModelAssignment,
+    InvocationMetadataIdentity,
     agent_model_assignment_from_payload,
     invocation_metadata_identity,
     v2_role_assignment_authority_errors,
@@ -104,6 +106,14 @@ WORKTREE_TASK_TYPES = frozenset({"implementation", "final-verification"})
 WORKER_STATUSES = frozenset(
     {"in-progress", "completed", "timeout", "error", "not-run"}
 )
+# Which of those mean the dispatch is still expected to produce something. Two
+# readers key off this split — `team reclaim` closes a finished dispatch's pane
+# and must never touch a live one, and the compact-reminder hook calls a run
+# in-flight when any dispatch is still here. Both restated the terminal four
+# locally before, so a sixth status would have read as finished in one place and
+# as live in the other.
+NON_TERMINAL_WORKER_STATUSES = frozenset({"in-progress"})
+TERMINAL_WORKER_STATUSES = WORKER_STATUSES - NON_TERMINAL_WORKER_STATUSES
 REASON_REQUIRED_STATUSES = frozenset({"timeout", "error", "not-run"})
 
 
@@ -564,6 +574,9 @@ def record_verified_agent_dispatch(
     if (
         enforcement_mode == "host-native-spec-link-gate"
         and assignment.runner != "native-session"
+        and not _is_current_session_lead(
+            run_manifest_path, execution_identity, assignment
+        )
     ):
         raise DispatchError(
             "host-native enforcement requires a native-session assignment"
@@ -718,6 +731,50 @@ def record_verified_agent_dispatch(
     return record
 
 
+def _is_current_session_lead(
+    manifest_path: Path,
+    execution_identity: InvocationMetadataIdentity | None,
+    assignment: AgentModelAssignment,
+) -> bool:
+    """Report whether this dispatch is the lead attesting its own session.
+
+    A current-session lead has no model binding, so the run manifest projects
+    its assignment as ``cli-wrapper`` while the execution manifest records the
+    participant as ``current-session``. It runs through no dispatch boundary at
+    all: the spec link is the lead associating the already-running session with
+    its verified invocation specification, which is what the host-native gate
+    records. Keyed on the execution manifest's own participant row rather than
+    on the projected runner string, so a genuine cli-wrapper worker never
+    reaches the native gate.
+    """
+    if execution_identity is None or assignment.runner == "native-session":
+        return False
+    manifest = read_execution_manifest(manifest_path)
+    if manifest.legacy:
+        return False
+    participant = next(
+        (
+            row for row in manifest.participant_assignments
+            if row.participant_ref == execution_identity.participant_ref
+        ),
+        None,
+    )
+    execution = next(
+        (
+            row for row in manifest.role_executions
+            if row.role_execution_ref == execution_identity.role_execution_ref
+        ),
+        None,
+    )
+    return (
+        participant is not None
+        and execution is not None
+        and execution.role == "leader"
+        and participant.runner == "current-session"
+        and participant.entry_mode == "current-session"
+    )
+
+
 def _agent_write_contract(
     project_root: Path,
     manifest_path: Path,

package/runtime/python/okstra_ctl/model_cli.py

@@ -158,8 +158,17 @@ def _catalog_row(model, adapter, role: str | None) -> dict[str, Any]:
             )
         )
     except HostModelBindingError as exc:
-        row["selectable"] = False
-        row["reason"] = str(exc)
+        # Not "unusable as a lead": the host cannot bind this model to a native
+        # session, so the lead runs through the provider CLI instead. Reporting
+        # it as unselectable made the listing disagree with what assignment
+        # resolution actually does — it accepts the model and falls back to
+        # `cli-wrapper` — leaving no way to find out why a lead was not native.
+        row["leaderRunner"] = "cli-wrapper"
+        row["reason"] = (
+            f"native-session unavailable ({exc}); the lead runs via cli-wrapper"
+        )
+    else:
+        row["leaderRunner"] = "native-session"
     return row
 
 

package/runtime/python/okstra_ctl/model_discovery.py

@@ -51,6 +51,18 @@ def _dispatch_effort(execution: str, role: str) -> str:
     return effort
 
 
+def dispatch_tier_suffixes() -> frozenset[str]:
+    """Every tier suffix dispatch can append to an agy execution value.
+
+    The provider serves back the suffixed identity it was given, so reading
+    that identity means undoing exactly this set — not guessing at whatever
+    trails the last hyphen. `low` is here because `_dispatch_effort` demotes
+    the untrusted high tier to it.
+    """
+    efforts = {value.lower() for value in (*ROLE_EFFORT.values(), _DEFAULT_EFFORT)}
+    return frozenset(efforts | {"low"})
+
+
 @lru_cache(maxsize=1)
 def agy_models(agy_bin: str = "agy") -> tuple[str, ...]:
     """Live `agy models` ids, or () when agy is unavailable (non-blocking).

package/runtime/python/okstra_ctl/pane_reclaim.py

@@ -1,12 +1,15 @@
-"""활성 run 스코프 조회 — pane 정리 의무를 어느 run 에 걸지 고르는 데 쓴다.
+"""진행 중 run 조회 — pane 회수 의무를 어느 run 에 걸지 고르는 데 쓴다.
 
 호출자는 `SessionStart(compact)` 훅(`okstra-compact-reminder.sh`) 하나다. 압축
-직후 리드에게 "이 run 의 완료 teammate pane 을 라운드 경계마다 회수하라"는 의무를
+직후 리드에게 "이 run 의 끝난 워커 pane 을 라운드 경계마다 회수하라"는 의무를
 재주입할 때, 그 대상이 되는 이 프로젝트의 진행 중 run 을 여기서 찾는다.
 
-완료 판정(`is_completed_status`)과 프로젝트 무관 전체 조회(`active_run_dirs`)도
-여기 있었으나, 그것을 쓰던 `okstra-trace-cleanup.sh --reclaim-completed` 와
-`okstra-subagent-reclaim.sh` 가 제거되면서 함께 사라졌다.
+정본은 run 디렉터리다(ADR-0011). 신호는 그 run 의 가장 최근 team-state 에
+비종결 배치가 남아 있는지다. 이전 구현은 `~/.okstra/active.jsonl` 을 읽었는데,
+그 원장은 `initial_status="running"` 으로 기록된 run 만 담고 in-session 경로는
+`--render-only` 강제로 항상 `prepared` 가 되어 종결로 라우팅된다 — 실측에서 그
+파일은 0행이었고 이 훅은 한 번도 발화하지 않았다. `state/lead-pane.id` 도 신호가
+못 된다: 한 번 기록된 뒤 지워지지 않아 끝난 run 을 영구히 진행 중으로 읽는다.
 """
 from __future__ import annotations
 
@@ -14,54 +17,57 @@ import json
 import sys
 from pathlib import Path
 
-from .paths import resolve_under_root
-from .reconcile import NON_TERMINAL_RECENT_STATUSES
+from .dispatch_state import NON_TERMINAL_WORKER_STATUSES
 
 
-def _iter_active_run_dirs(home: Path):
-    """active.jsonl 의 진행 중 run 마다 (projectRoot_str, 절대 run_dir) 를 yield.
-    runDirRel 의 base 는 projectRoot(paths.compute_run_paths 의 _rel 기준)."""
-    path = home / "active.jsonl"
-    if not path.is_file():
-        return
-    for line in path.read_text(encoding="utf-8").splitlines():
-        line = line.strip()
-        if not line:
-            continue
-        try:
-            row = json.loads(line)
-        except json.JSONDecodeError:
-            continue
-        # 대상(진행 중) 집합은 reconcile 의 NON_TERMINAL_RECENT_STATUSES 가
-        # SSOT. reserving 은 아직 run-dir 산출물이 없어 이 집합에 들어있지
-        # 않으므로 자연히 제외된다(allowlist).
-        if row.get("status") not in NON_TERMINAL_RECENT_STATUSES:
-            continue
-        run_dir = resolve_under_root(row.get("projectRoot"), row.get("runDirRel"))
-        if run_dir is not None:
-            yield row.get("projectRoot"), run_dir
+def _newest_team_state(state_dir: Path) -> Path | None:
+    """한 run 디렉터리의 최신 team-state.
+
+    seq 는 3자리 zero-pad 라 이름 정렬이 곧 순서다. run 하나에 seq 가 누적되고
+    이전 라운드의 `in-progress` 행이 그 파일에 남으므로, 최신이 아닌 파일을 읽으면
+    몇 시간 전에 끝난 run 을 진행 중으로 보고한다.
+    """
+    files = sorted(state_dir.glob("team-state-*.json"))
+    return files[-1] if files else None
 
 
-def active_run_dirs_for_project(home: Path, cwd: Path) -> list[Path]:
-    """진행 중 run 중 projectRoot 이 cwd(또는 그 상위)인 것의 절대 run-dir 목록.
-    SessionStart(compact) 훅이 이 프로젝트의 run 에만 리마인더를 걸도록 스코프한다."""
-    cwd_r = Path(cwd).resolve()
+def _has_live_dispatch(team_state_path: Path) -> bool:
+    try:
+        payload = json.loads(team_state_path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return False
+    if not isinstance(payload, dict):
+        return False
+    return any(
+        isinstance(record, dict)
+        and record.get("status") in NON_TERMINAL_WORKER_STATUSES
+        for record in payload.get("workerDispatches", [])
+    )
+
+
+def in_flight_run_dirs(project_root: Path) -> list[Path]:
+    """비종결 배치를 아직 들고 있는 이 프로젝트의 run 디렉터리 목록.
+
+    `runs/<task-type>/` 와 stage 격리 run 의 `runs/<task-type>/stage-<N>/` 을 모두
+    훑는다. 후자를 빼면 `implementation` 과 단일 stage `final-verification` 이
+    통째로 누락된다.
+    """
+    tasks_root = Path(project_root) / ".okstra" / "tasks"
+    if not tasks_root.is_dir():
+        return []
     out: list[Path] = []
-    for project_root, run_dir in _iter_active_run_dirs(home):
-        if not project_root:
-            continue
-        try:
-            project_root_r = Path(project_root).resolve()
-        except OSError:
+    for state_dir in sorted(tasks_root.glob("*/*/runs/**/state")):
+        if not state_dir.is_dir():
             continue
-        if cwd_r == project_root_r or cwd_r.is_relative_to(project_root_r):
-            out.append(run_dir)
+        newest = _newest_team_state(state_dir)
+        if newest is not None and _has_live_dispatch(newest):
+            out.append(state_dir.parent)
     return out
 
 
 def main(argv: list[str]) -> int:
-    if len(argv) == 3 and argv[0] == "--active-dirs-for":
-        for run_dir in active_run_dirs_for_project(Path(argv[1]), Path(argv[2])):
+    if len(argv) == 2 and argv[0] == "--in-flight-run-dirs-for":
+        for run_dir in in_flight_run_dirs(Path(argv[1])):
             print(run_dir)
         return 0
     return 1

package/runtime/python/okstra_ctl/render.py

@@ -735,6 +735,15 @@ def render_team_state(team_state_path: str, ctx: dict) -> None:
     catalog = _worker_catalog(ctx)
     worker_dispatch_plan = _worker_dispatch_plan(ctx)
     workers = []
+    for row in _optional_worker_roles(ctx):
+        workers.append({
+            **{key: row[key] for key in (
+                "workerId", "role", "agent", "provider", "runner",
+                "model", "modelExecutionValue", "resultPath", "promptPath",
+            )},
+            "status": "not-run",
+            "reason": "",
+        })
     for w in selected:
         m = catalog[w]
         workers.append(
@@ -1133,6 +1142,44 @@ def _required_worker_roles(ctx: dict, reviewers: list[str]) -> list[dict]:
     ]
 
 
+def _optional_worker_roles(ctx: dict) -> list[dict]:
+    """Roles this run may dispatch but does not require — today, the critics.
+
+    A critic is opt-in, so it never belonged in `requiredWorkerRoles`. But it
+    was absent from the roster entirely, and both `okstra team dispatch` and
+    the liveness reader locate a worker by its team-state row: dispatching a
+    critic failed with `team-state has no workerId=acceptance`, while adding
+    the row by hand failed validation as an `unexpected worker role`. Declaring
+    it here makes the roster say what the run may run, so both sides agree.
+
+    Keyed off `invocationAssignments`, which is where the run records the
+    critic it actually resolved — an absent `critic/*` entry means no critic.
+    """
+    assignments = _invocation_assignments(ctx)
+    roles: list[dict] = []
+    for assignment_ref, assignment in sorted(assignments.items()):
+        if not assignment_ref.startswith("critic/"):
+            continue
+        provider = str(assignment.get("provider", ""))
+        roles.append({
+            # `okstra team dispatch` projects a v2 worker's state key off the
+            # assignment ref's last segment; the row it looks up must use it.
+            "workerId": assignment_ref.rsplit("/", 1)[-1],
+            "role": f"{provider_spec(provider).display_label} critic",
+            "agent": provider,
+            "provider": provider,
+            "runner": str(assignment.get("runner", "")),
+            "model": str(assignment.get("model", "")),
+            "modelExecutionValue": str(assignment.get("modelExecutionValue", "")),
+            # The lead names these when it materializes the invocation; a
+            # critic has no prompt or result until it is dispatched.
+            "resultPath": "",
+            "promptPath": "",
+            "attemptRequired": False,
+        })
+    return roles
+
+
 def _reporter_confirmation_status(brief_bytes: bytes) -> str:
     try:
         lines = brief_bytes.decode("utf-8").splitlines()
@@ -1448,6 +1495,7 @@ def render_task_manifest(manifest_path: str, ctx: dict) -> None:
             "minimumPreferredWorkerResults": len(reviewers),
             "requiredWorkerAttempts": reviewers,
             "requiredWorkerRoles": required_worker_roles,
+            "optionalWorkerRoles": _optional_worker_roles(ctx),
             "requiredAgentStatusEntries": required_agent_status_entries,
             "requireDistinctLeadFromWorkerSession": True,
             "requireAllRequiredWorkerAttempts": True,
@@ -1644,6 +1692,10 @@ def render_run_manifest(run_manifest_path: str, ctx: dict) -> None:
         "taskId": ctx.get("TASK_ID", ""),
         "taskKey": ctx.get("TASK_KEY", ""),
         "taskType": ctx.get("TASK_TYPE", ""),
+        # Every other path in this manifest is project-relative; this is the
+        # anchor they resolve against. Convergence reads it to place run
+        # artifacts, so a manifest without it cannot seed a round.
+        "projectRoot": ctx.get("PROJECT_ROOT", ""),
         "hostRuntime": ctx.get("HOST_RUNTIME", "") or _lead_runtime(ctx),
         "leadRuntime": _lead_runtime(ctx),
         "leadRuntimeRequest": ctx.get("LEAD_RUNTIME_REQUEST", "") or _lead_runtime(ctx),
@@ -1765,6 +1817,7 @@ def render_run_manifest(run_manifest_path: str, ctx: dict) -> None:
             "finalSynthesisOwner": lead_role,
             "requiredWorkerAttempts": reviewers,
             "requiredWorkerRoles": required_worker_roles,
+            "optionalWorkerRoles": _optional_worker_roles(ctx),
             "requiredAgentStatusEntries": [lead_role]
             + [catalog[item]["role"] for item in reviewers],
             "requireDistinctLeadFromWorkerSession": True,

package/runtime/python/okstra_ctl/report_html/render.py

@@ -109,17 +109,21 @@ def _html_path(data_path: Path) -> Path:
 
 def render_v2_html_view(
     data_path: Path,
-    markdown_path: Path,
     *,
     run_meta: HtmlRunMeta,
     templates_root: Path | None = None,
 ) -> Path:
+    """Render the human HTML from the data.json alone.
+
+    The AI-handoff markdown sibling is a second rendering of this same record,
+    never an input here: it used to be read for a `source-md-sha256` stamp that
+    no reader ever compared, which made a derived artifact a precondition for
+    another derived artifact.
+    """
     data = json.loads(data_path.read_text(encoding="utf-8"))
     errors = validate(data, load_schema_for_data(data))
     if errors:
         raise HtmlRenderError("invalid v2 final-report data: " + "; ".join(errors[:5]))
-    if not markdown_path.is_file():
-        raise HtmlRenderError(f"v2 markdown sibling not found: {markdown_path}")
     # Validate the SSOT, then localize — the sidecar carries presentation and
     # has no say in whether the report is well-formed.
     data, lang = _localize(data, data_path)
@@ -150,7 +154,6 @@ def render_v2_html_view(
         "taskType": view.task_type,
         "sourceData": source_data,
         "dataSha256": _sha256(data_path),
-        "markdownSha256": _sha256(markdown_path),
         "clarificationItems": data.get("clarificationItems", []),
         # Every task type ends with the same run-cost section, so it is bound
         # here rather than in ten view models that would each rebuild it.