okstra 0.173.0 → 0.175.1

package/runtime/python/okstra_ctl/render.py

@@ -84,6 +84,16 @@ def _write_json(path: Path, payload: dict) -> None:
     _write_text(path, json.dumps(payload, indent=2, ensure_ascii=False) + "\n")
 
 
+def _execution_identity(ctx: Mapping[str, object]) -> dict:
+    raw = ctx.get("EXECUTION_IDENTITY_JSON")
+    if not isinstance(raw, str) or not raw.strip():
+        return {}
+    payload = json.loads(raw)
+    if not isinstance(payload, dict):
+        raise TokenRenderError("EXECUTION_IDENTITY_JSON must contain an object")
+    return payload
+
+
 def _lead_runtime(ctx: dict) -> str:
     return ctx.get("LEAD_RUNTIME", "") or "claude-code"
 
@@ -377,10 +387,14 @@ def _agent_contract(ctx: dict) -> dict:
     return parsed
 
 
-def _executor_contract(ctx: dict) -> dict:
+def _executor_contract(ctx: dict) -> dict | None:
     runner = ctx.get("EXECUTOR_RUNNER", "")
     dispatch_mode = ctx.get("EXECUTOR_DISPATCH_MODE", "")
     host_model_value = ctx.get("EXECUTOR_HOST_MODEL_VALUE") or None
+    if not runner and not ctx.get("EXECUTOR_PROVIDER"):
+        if ctx.get("TASK_TYPE") == "implementation":
+            raise ValueError("implementation executor assignment is required")
+        return None
     expected_mode = {
         "native-session": "host-native",
         "cli-wrapper": "worker-dispatch",
@@ -1326,8 +1340,14 @@ def render_task_manifest(manifest_path: str, ctx: dict) -> None:
     latest_team_state_relative = pointers["latestTeamStatePath"]
     latest_resume_command_relative = pointers["latestResumeCommandPath"]
     convergence_block = _build_convergence_block(ctx)
+    execution_identity = _execution_identity(ctx)
+    existing_v2 = (
+        existing.get("schemaVersion") == "2.0"
+        and existing.get("executionIdentityVersion") == 2
+    )
+    writes_v2 = execution_identity.get("executionIdentityVersion") == 2
     payload = {
-        "schemaVersion": "1.0",
+        "schemaVersion": "2.0" if existing_v2 or writes_v2 else "1.0",
         "projectId": ctx.get("PROJECT_ID", ""),
         "taskGroup": ctx.get("TASK_GROUP", ""),
         "taskId": ctx.get("TASK_ID", ""),
@@ -1487,6 +1507,12 @@ def render_task_manifest(manifest_path: str, ctx: dict) -> None:
             "sessionId": ctx.get("CLAUDE_SESSION_ID", ""),
             "resumeCommandPath": ctx.get("CLAUDE_RESUME_COMMAND_RELATIVE_PATH", ""),
         }
+    if existing_v2 or writes_v2:
+        existing_index = existing.get("roleExecutionIndex")
+        payload["executionIdentityVersion"] = 2
+        payload["roleExecutionIndex"] = (
+            list(existing_index) if isinstance(existing_index, list) else []
+        )
     _write_json(path, payload)
 
 
@@ -1608,8 +1634,9 @@ def render_run_manifest(run_manifest_path: str, ctx: dict) -> None:
         for s in str(ctx.get("CONCURRENT_RUN_STAGES", "") or "").split(",")
         if s.strip().isdigit()
     ]
+    execution_identity = _execution_identity(ctx)
     payload = {
-        "schemaVersion": "1.0",
+        "schemaVersion": execution_identity.get("schemaVersion", "1.0"),
         "okstraVersion": ctx.get("OKSTRA_VERSION", ""),
         "projectId": ctx.get("PROJECT_ID", ""),
         "taskGroup": ctx.get("TASK_GROUP", ""),
@@ -1783,6 +1810,7 @@ def render_run_manifest(run_manifest_path: str, ctx: dict) -> None:
     )
     if _lead_runtime(ctx) == "claude-code":
         payload["claudeSessionId"] = ctx.get("CLAUDE_SESSION_ID", "")
+    payload.update(execution_identity)
     _guard_invocation_manifest_rewrite(existing_run_manifest, payload)
     _write_json(Path(run_manifest_path), payload)
 
@@ -1795,6 +1823,11 @@ _MODEL_ASSIGNMENT_KEYS = {
     "hostRuntime",
     "hostModelValue",
 }
+_V2_INVOCATION_IDENTITY_KEYS = {
+    "participantRef",
+    "roleExecutionRef",
+    "dutyId",
+}
 _AGENT_CONTRACT_KEYS = {
     "schemaVersion",
     "dutyRootPath",
@@ -1860,11 +1893,8 @@ def _validate_invocation_manifest(payload: Mapping[str, object]) -> None:
         or not assignments
     ):
         raise ValueError("incomplete invocation manifest")
-    if any(
-        not isinstance(item, Mapping) or set(item) != _MODEL_ASSIGNMENT_KEYS
-        for item in assignments.values()
-    ):
-        raise ValueError("incomplete invocation manifest assignments")
+    _invocation_manifest_identity_version(payload)
+    _validate_invocation_assignment_shapes(assignments)
     _validate_compatibility_projections(payload, assignments)
     for key in (
         item
@@ -1901,13 +1931,17 @@ def _validate_compatibility_projections(
     workers = payload.get("workerAssignments")
     if not isinstance(lead, Mapping) or not isinstance(workers, list):
         raise ValueError("incomplete invocation manifest compatibility projection")
-    if _model_projection(lead) != assignments.get("lead"):
+    if _model_projection(lead) != _model_projection_from_assignment(
+        assignments.get("lead")
+    ):
         raise ValueError("immutable invocation manifest lead projection drift")
     for worker in workers:
         if not isinstance(worker, Mapping):
             raise ValueError("incomplete invocation manifest worker projection")
         reference = f"initial/{worker.get('workerId', '')}"
-        if _model_projection(worker) != assignments.get(reference):
+        if _model_projection(worker) != _model_projection_from_assignment(
+            assignments.get(reference)
+        ):
             raise ValueError("immutable invocation manifest worker projection drift")
 
 
@@ -1915,6 +1949,40 @@ def _model_projection(value: Mapping[str, object]) -> dict[str, object]:
     return {key: value.get(key) for key in _MODEL_ASSIGNMENT_KEYS}
 
 
+def _model_projection_from_assignment(value: object) -> dict[str, object] | None:
+    if not isinstance(value, Mapping) or not _MODEL_ASSIGNMENT_KEYS.issubset(value):
+        return None
+    return _model_projection(value)
+
+
+def _invocation_manifest_identity_version(payload: Mapping[str, object]) -> int:
+    schema = payload.get("schemaVersion")
+    identity = payload.get("executionIdentityVersion")
+    if schema == "2.0" and identity == 2:
+        return 2
+    if schema == "2.0" or identity is not None:
+        raise ValueError("invocation manifest mixes v1 and v2 execution identity")
+    if schema not in (None, 1, "1", "1.0"):
+        raise ValueError("unsupported invocation manifest execution identity version")
+    return 1
+
+
+def _validate_invocation_assignment_shapes(
+    assignments: Mapping[str, object],
+) -> None:
+    allowed = {frozenset(_MODEL_ASSIGNMENT_KEYS)}
+    for item in assignments.values():
+        if not isinstance(item, Mapping):
+            raise ValueError("incomplete invocation manifest assignments")
+        keys = set(item)
+        if keys & _V2_INVOCATION_IDENTITY_KEYS:
+            raise ValueError(
+                "invocation assignment duplicates v2 execution identity"
+            )
+        if frozenset(keys) not in allowed:
+            raise ValueError("incomplete invocation manifest assignments")
+
+
 def render_timeline(timeline_path: str, ctx: dict) -> None:
     task_manifest_path = Path(ctx.get("TASK_MANIFEST_PATH", ""))
     task_manifest = {}

package/runtime/python/okstra_ctl/render_final_report.py

@@ -12,10 +12,10 @@ columns in the Execution Status table, omitted §4 phase-continuation
 rows, ad-hoc ``## Index`` sections. Routing everything through one
 template + schema cuts those failure modes to zero.
 
-For schema-v1 compatibility, the top-of-report ``## Index`` remains a
-deterministic post-render section built by ``_inject_index_and_anchors``.
-Schema v2 keeps its compact fixed AI-handoff order and does not inject the
-legacy reader index; the task-specific HTML provides the human navigation.
+Rendering never injects a reader index: the AI-handoff markdown keeps its
+compact fixed order and the task-specific HTML provides human navigation.
+``_inject_index_and_anchors`` survives as a standalone pass over an already
+written markdown file, driven by ``scripts/okstra-inject-report-index.py``.
 
 Phase 7 mutation flow: ``okstra-token-usage.py --substitute-data`` fills
 the ``tokenUsage`` and ``executionStatus[].totalTokens`` etc. cells in
@@ -53,7 +53,11 @@ from okstra_ctl.i18n import I18nError, SUPPORTED_LANGS, load_dictionary, make_ji
 from okstra_ctl.md_table import UNESCAPED_PIPE_RE, to_cell_text
 from okstra_ctl.models import UnknownModelError, resolve_model_metadata
 from okstra_ctl.paths import find_asset_root
-from okstra_ctl.report_contract import TASK_TYPE_DATA_PROPERTY, markdown_template_for
+from okstra_ctl.report_contract import (
+    CURRENT_REPORT_SCHEMA_VERSION,
+    TASK_TYPE_DATA_PROPERTY,
+    markdown_template_for,
+)
 from okstra_ctl.report_markdown import ReportSections
 from okstra_ctl.schema_excerpt import excerpt_cut_from_version
 from okstra_ctl.seeding import installed_version
@@ -61,10 +65,9 @@ from okstra_ctl.usage_cells import format_duration_ms, format_int, format_usd
 
 
 TEMPLATE_BY_SCHEMA_VERSION = {
-    "1.0": ("templates", "reports", "final-report.template.md"),
     "2.0": ("templates", "reports", "final-report-v2.template.md"),
 }
-DEFAULT_TEMPLATE_REL = TEMPLATE_BY_SCHEMA_VERSION["1.0"]
+DEFAULT_TEMPLATE_REL = TEMPLATE_BY_SCHEMA_VERSION[CURRENT_REPORT_SCHEMA_VERSION]
 
 TASK_DELIVERABLE_TITLES = {
     "requirements-discovery": "Requirements Discovery",
@@ -563,6 +566,8 @@ def _ai_markdown_context(data: dict, schema: dict | None) -> dict:
     context["md_rest"] = sections.rest
     context["md_has"] = sections.has
     context["md_claim"] = sections.mark_rendered
+    context["executionRolesTable"] = render_execution_roles_markdown(data)
+    context["executionIdentityVersion"] = data.get("executionIdentityVersion")
     return context
 
 
@@ -620,6 +625,23 @@ _OPTIONAL_ANALYSIS_DEFAULTS = (
 )
 
 
+def render_execution_roles_markdown(data: dict) -> str:
+    roles = data.get("executionRoles") or []
+    if data.get("executionIdentityVersion") != 2:
+        return "legacy execution roles"
+    lines = ["| Role | Label | Status |", "|---|---|---|"]
+    for row in roles:
+        lines.append(
+            f"| {row.get('role', '')} | {row.get('executionLabel', '')} | "
+            f"{row.get('status', '')} |"
+        )
+    return "\n".join(lines)
+
+
+def render_execution_roles_html(data: dict) -> str:
+    return render_execution_roles_markdown(data)
+
+
 def _with_optional_defaults(data: dict) -> dict:
     """Render context with schema-optional fields filled in.
 
@@ -666,14 +688,7 @@ def render(
 
     try:
         template = env.get_template(template_path.name)
-        context = (
-            _ai_markdown_context(data, schema)
-            if data.get("schemaVersion") == "2.0"
-            else _with_optional_defaults(data)
-        )
-        rendered = template.render(**context)
-        if data.get("schemaVersion") == "1.0":
-            rendered = _inject_index_and_anchors(rendered, dictionary)
+        rendered = template.render(**_ai_markdown_context(data, schema))
         return _ventilate_prose(rendered)
     except I18nError as exc:
         raise FinalReportRenderError(
@@ -689,10 +704,10 @@ def find_default_template(start: Path | None = None) -> Path:
     """Locate the bundled final-report template.
 
     Resolution order:
-      1. ``$OKSTRA_HOME/templates/reports/final-report.template.md`` (installed runtime).
-      2. ``<repo>/templates/reports/final-report.template.md`` (in-repo dev runs).
+      1. ``$OKSTRA_HOME/templates/reports/final-report-v2.template.md`` (installed runtime).
+      2. ``<repo>/templates/reports/final-report-v2.template.md`` (in-repo dev runs).
          Repo root is detected by walking up from this file until a
-         ``templates/reports/final-report.template.md`` exists.
+         ``templates/reports/final-report-v2.template.md`` exists.
 
     Raises ``FinalReportRenderError`` if neither path is present.
     """
@@ -701,7 +716,7 @@ def find_default_template(start: Path | None = None) -> Path:
         return root.joinpath(*DEFAULT_TEMPLATE_REL)
 
     raise FinalReportRenderError(
-        "could not locate final-report.template.md. Set OKSTRA_HOME or "
+        "could not locate final-report-v2.template.md. Set OKSTRA_HOME or "
         "run from a checkout that contains templates/reports/."
     )
 

package/runtime/python/okstra_ctl/report_contract.py

@@ -3,7 +3,6 @@ from __future__ import annotations
 
 
 CURRENT_REPORT_SCHEMA_VERSION = "2.0"
-LEGACY_REPORT_SCHEMA_VERSION = "1.0"
 
 PUBLIC_REPORT_TASK_TYPES = (
     "requirements-discovery",
@@ -171,6 +170,45 @@ def html_template_for(task_type: str) -> str:
         raise ValueError(f"no task-specific html template for: {task_type}") from exc
 
 
+def execution_roles_from_manifest(manifest: dict) -> list[dict]:
+    """Copy the exact RoleExecution set. Do not invent rows."""
+    if int(manifest.get("executionIdentityVersion") or 0) != 2:
+        return []
+    roles = []
+    for row in manifest.get("roleExecutions") or []:
+        if not isinstance(row, dict):
+            continue
+        roles.append({
+            "roleExecutionRef": row.get("roleExecutionRef"),
+            "role": row.get("role"),
+            "provider": row.get("provider"),
+            "modelRef": row.get("modelRef"),
+            "ordinal": row.get("ordinal"),
+            "executionLabel": row.get("executionLabel"),
+            "status": row.get("status"),
+        })
+    return roles
+
+
+def apply_execution_roles(data: dict, manifest: dict) -> dict:
+    """Copy the manifest RoleExecution set onto a final-report payload."""
+    updated = dict(data)
+    if int(manifest.get("executionIdentityVersion") or 0) != 2:
+        return updated
+    updated["executionIdentityVersion"] = 2
+    updated["executionRoles"] = execution_roles_from_manifest(manifest)
+    return updated
+
+
+def assert_execution_roles_match_manifest(report: dict, manifest: dict) -> None:
+    report_refs = {row.get("roleExecutionRef") for row in report.get("executionRoles") or []}
+    manifest_refs = {
+        row.get("roleExecutionRef") for row in manifest.get("roleExecutions") or []
+    }
+    if report_refs != manifest_refs:
+        raise ValueError("report executionRoles must equal manifest roleExecutions")
+
+
 def markdown_template_for(task_type: str) -> str:
     try:
         return TASK_TYPE_MARKDOWN_TEMPLATE[task_type]

package/runtime/python/okstra_ctl/report_finalize.py

@@ -6,6 +6,18 @@ substitution, html view rendering, follow-up task spawning, and run validation.
 The order is load-bearing — rendering before substitution ships `--` token
 cells, and validating before rendering trips the report-views contract.
 
+`token-usage` is the one step whose failure does not stop the sequence, which
+deliberately accepts that first state: its input is the lead session log, so a
+refusal there would otherwise delete every artifact the later steps produce.
+The run does not pass in that state. `validators/validate-run.py` re-collects
+when the recorded usage is all zeros against an `unavailable` session source
+(`_needs_token_autofix`) and refuses the run rather than ship zeroed counts
+(`accuracy-failed`); a legacy v1 report is caught earlier still, by its
+unsubstituted `{{...}}` placeholders, which a v2 report never carries because
+its numeric cells are `null` until this step fills them. Substituting the
+tokens on a later retry then leaves the already-rendered html stale for
+`validators/validate-report-views.py`.
+
 The translation sidecar is NOT one of these steps. `render-views` overlays it,
 so a non-English run dispatches the translator before this sequence starts —
 after verifying the data.json is English, which is why `check-source` is also
@@ -26,9 +38,11 @@ from pathlib import Path
 from typing import Any, Callable, Mapping, Sequence
 
 from .agent_activity import ActivityProjectionError, project_agent_activity
+from .report_contract import apply_execution_roles
 from .dispatch_state import DispatchError, link_agent_dispatch_result
 from .final_report_paths import final_report_data_path, final_report_markdown_path
 from .paths import task_dir, task_manifest_file
+from .session import observe_lead_session
 
 
 STEP_PROJECT_ACTIVITY = "project-activity"
@@ -354,7 +368,14 @@ def run_finalize(
     before_step: Callable[[str], None] | None = None,
     only: Sequence[str] | None = None,
 ) -> dict[str, Any]:
-    """Run the Phase 7 steps in order, stopping at the first non-zero exit.
+    """Run the Phase 7 steps in contractual order.
+
+    A non-zero exit stops the sequence, with one exception: ``token-usage``
+    defers. Its input is the lead session log — state outside this run — so a
+    refusal there is not evidence that the artifacts after it are unwritable.
+    The deferred failure becomes the result's ``reason`` when nothing later
+    fails, and yields to any later failure, which is the step that actually
+    blocked the run.
 
     ``before_step`` fires immediately before each step is spawned, letting an
     adapter settle state the step will read (the Codex adapter marks the report
@@ -366,7 +387,9 @@ def run_finalize(
     step at full token and wall-clock cost.
     """
     steps: list[dict[str, Any]] = []
+    deferred = ""
     try:
+        write_execution_roles(ctx)
         commands = build_commands(ctx)
     except FinalizeError as exc:
         return {"ok": False, "reason": str(exc), "steps": steps}
@@ -426,14 +449,38 @@ def run_finalize(
             )
         steps.append(step_payload(name, command, result))
         if result.returncode != 0:
-            return {
-                "ok": False,
-                "reason": f"{name} failed with exit code {result.returncode}",
-                "steps": steps,
-            }
+            failure = f"{name} failed with exit code {result.returncode}"
+            # Token collection reads the lead session log, which lives outside
+            # this run. One refusal there (`grandTotalTokens=0`) took the whole
+            # run's output with it: html never rendered, follow-ups never
+            # spawned, and `validate-run` then blocked on `report-views:
+            # missing html artifact`. So this step alone defers instead of
+            # stopping the sequence. It hides nothing — the non-zero exit stays
+            # in `steps`, `ok` stays False, and the closing `validate-run`
+            # still refuses the run.
+            if name == STEP_TOKEN_USAGE:
+                deferred = failure
+                continue
+            return {"ok": False, "reason": failure, "steps": steps}
+    if deferred:
+        return {"ok": False, "reason": deferred, "steps": steps}
     return {"ok": True, "reason": "", "steps": steps}
 
 
+def write_execution_roles(ctx: FinalizeContext) -> None:
+    """Write the exact manifest role set onto the final-report data.json."""
+    if not ctx.data_path.is_file() or not ctx.manifest_path.is_file():
+        return
+    manifest = _load_manifest(ctx.manifest_path)
+    data = _load_manifest(ctx.data_path)
+    updated = apply_execution_roles(dict(data), dict(manifest))
+    if updated == data:
+        return
+    tmp = ctx.data_path.with_suffix(ctx.data_path.suffix + ".tmp")
+    tmp.write_text(json.dumps(updated, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
+    tmp.replace(ctx.data_path)
+
+
 def _link_lead_result_for_validation(ctx: FinalizeContext) -> None:
     """Link the lead-authored synthesis artifact before Phase 7 validation."""
     manifest = _load_manifest(ctx.manifest_path)
@@ -546,6 +593,29 @@ def _step_summary_lines(result: Mapping[str, Any]) -> list[str]:
     return lines
 
 
+def _recovery_step_names(result: Mapping[str, Any]) -> list[str]:
+    """The steps a retry has to re-run: every step from the earliest failure on.
+
+    Naming only the failed steps would prescribe half a recovery. `token-usage`
+    defers, so `render-views` already wrote an html view from unsubstituted
+    data; substituting the tokens on a retry leaves that view stale
+    (`validators/validate-report-views.py` checks `source-sha256` against the
+    md body). And a sequence that stopped early never reached `validate-run`,
+    which is the step that decides whether the run is shippable. Resuming from
+    the earliest failure redoes both while still skipping the prefix that
+    succeeded — the saving `--only` exists for.
+    """
+    failed = {
+        string_value(step.get("name"))
+        for step in (result.get("steps") or [])
+        if step.get("exitCode") != 0
+    }
+    for index, name in enumerate(STEP_ORDER):
+        if name in failed:
+            return list(STEP_ORDER[index:])
+    return []
+
+
 def main(argv: Sequence[str] | None = None) -> int:
     args = _parser().parse_args(argv)
     try:
@@ -553,6 +623,10 @@ def main(argv: Sequence[str] | None = None) -> int:
     except FinalizeError as exc:
         print(f"error: {exc}", file=sys.stderr)
         return 2
+    # Phase 7 is the last boundary the lead crosses, and the last chance to add
+    # the generations resume and compaction split it into. It runs ahead of the
+    # sequence because the token-usage step below reads `leadSessionIds`.
+    observe_lead_session(ctx.project_root, ctx.team_state_path)
     result = run_finalize(ctx, only=args.only or None)
     print(json.dumps(result, indent=2, ensure_ascii=False))
     print("finalize steps:", file=sys.stderr)
@@ -560,10 +634,11 @@ def main(argv: Sequence[str] | None = None) -> int:
         print(line, file=sys.stderr)
     if not result["ok"]:
         print(f"error: {result['reason']}", file=sys.stderr)
-        if result.get("steps"):
+        recovery = _recovery_step_names(result)
+        if recovery:
+            flags = " ".join(f"--only {name}" for name in recovery)
             print(
-                "retry just the failing step with "
-                f"`--only {result['steps'][-1].get('name')}`",
+                f"resume the sequence from the earliest failure with `{flags}`",
                 file=sys.stderr,
             )
         return 1

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

@@ -155,6 +155,7 @@ def render_v2_html_view(
         # 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.
         "runUsage": run_usage(data),
+        "executionRoles": data.get("executionRoles") or [],
         "css": (root / "html/assets/base.css").read_text(encoding="utf-8"),
         "js": response_js + "\n" + base_js,
     }