okstra 0.163.2 → 0.165.0

package/runtime/python/okstra_ctl/render.py

@@ -30,11 +30,18 @@ from okstra_project.dirs import TASK_MANIFEST_FILENAME, OKSTRA_DIR_NAME, project
 # 이는 silent drift 위험이 있어 SSOT import 로 통합한다.
 from . import fix_cycles
 from .analysis_inputs import ANALYSIS_TASK_TYPES
+from .application.resolve_assignment import (
+    resolve_assignment_runner,
+    resolve_lead_provider,
+)
+from .application.dispatch_assignments import dispatch_assignments
+from .adapters.dispatch import default_worker_dispatch_port, with_worker_dispatch
+from .adapters.dispatch.cmux import dispatch_port_for_terminal_backend
 from .paths import okstra_home
-from .dispatch_state import BACKEND_CMUX_PANE
-from .lead_runtime import lead_runtime_info, with_cmux_dispatch
 from .models import UnknownProviderError, provider_ids, provider_spec
-from .runner_resolution import native_provider_for_host
+from .ports.worker_dispatch import WorkerDispatchRequest
+from .registry.host_registry import default_host_registry
+from .registry.provider_registry import default_provider_registry
 from .path_hints import compact_active_run_context, hydrate_run_context
 from .paths import task_timeline_file
 from .worker_artifacts import artifacts_from_context
@@ -80,27 +87,49 @@ def _lead_runtime(ctx: dict) -> str:
     return ctx.get("LEAD_RUNTIME", "") or "claude-code"
 
 
-def _lead_info(ctx: dict):
-    info = lead_runtime_info(_lead_runtime(ctx))
-    if ctx.get("TERMINAL_BACKEND") == BACKEND_CMUX_PANE:
-        return with_cmux_dispatch(info)
-    return info
+def _lead_descriptor(ctx: dict):
+    return default_host_registry().resolve(_lead_runtime(ctx)).descriptor
+
+
+def _worker_dispatch_plan(ctx: dict):
+    host_adapter = default_host_registry().resolve(_lead_runtime(ctx))
+    fallback_port = default_worker_dispatch_port(host_adapter.descriptor)
+    port = dispatch_port_for_terminal_backend(
+        ctx.get("TERMINAL_BACKEND", ""),
+        fallback_port,
+    )
+    decorated = with_worker_dispatch(host_adapter, port)
+    request = WorkerDispatchRequest(
+        project_root=Path(ctx.get("PROJECT_ROOT", "")),
+        run_manifest=Path(ctx.get("RUN_MANIFEST_PATH", "")),
+    )
+    return dispatch_assignments(request, decorated.worker_dispatch())
 
 
 def _lead_agent(ctx: dict) -> str:
-    return _lead_info(ctx).agent
+    return _lead_descriptor(ctx).agent_id
 
 
 def _lead_agent_label(ctx: dict) -> str:
-    return _lead_info(ctx).agent_label
+    return _lead_descriptor(ctx).agent_label
 
 
 def _lead_role(ctx: dict) -> str:
-    return _lead_info(ctx).role
+    return _lead_descriptor(ctx).role
+
+
+def _lead_adapter(ctx: dict, plan) -> dict:
+    descriptor = default_host_registry().resolve(_lead_runtime(ctx)).descriptor
+    return {
+        "name": plan.adapter_name or descriptor.id,
+        "dispatchMode": plan.dispatch_mode or descriptor.dispatch_mode,
+        "sessionAccounting": descriptor.session_accounting,
+    }
 
 
-def _lead_adapter(ctx: dict) -> dict:
-    return _lead_info(ctx).adapter_payload()
+def _lead_adapter_contract(ctx: dict, plan) -> str:
+    descriptor = default_host_registry().resolve(_lead_runtime(ctx)).descriptor
+    return plan.relay_contract or descriptor.relay_contract
 
 
 def _runtime_resolution(ctx: dict) -> dict:
@@ -257,31 +286,71 @@ def _resolve_workers(ctx: dict) -> list[str]:
     ]
 
 
-def _assignment_runner_for_ctx(ctx: dict, provider: str) -> str:
-    native_provider = native_provider_for_host(_lead_runtime(ctx))
-    return "native-session" if provider == native_provider else "cli-wrapper"
+def _assignment_runner_for_ctx(
+    ctx: dict,
+    provider: str,
+    role: str,
+    requested_runner: str = "",
+) -> str:
+    host = default_host_registry().resolve(_lead_runtime(ctx)).descriptor
+    spec = default_provider_registry().resolve(provider)
+    return resolve_assignment_runner(
+        host=host,
+        provider=spec,
+        role=role,
+        requested_runner=requested_runner,
+    ).runner
+
+
+def _resolved_lead_assignment(
+    ctx: dict,
+    requested_provider: str,
+    requested_runner: str = "",
+):
+    host_registry = default_host_registry()
+    provider_registry = default_provider_registry()
+    assignment = resolve_lead_provider(
+        host_id=_lead_runtime(ctx),
+        requested_provider=requested_provider,
+        host_registry=host_registry,
+        provider_registry=provider_registry,
+    )
+    if requested_runner:
+        resolution = resolve_assignment_runner(
+            host=host_registry.resolve(_lead_runtime(ctx)).descriptor,
+            provider=provider_registry.resolve(assignment.provider),
+            role="lead",
+            requested_runner=requested_runner,
+        )
+        return assignment.provider, resolution.runner
+    return assignment.provider, assignment.runner
 
 
 def _lead_assignment(ctx: dict) -> dict:
+    parsed = None
     raw = ctx.get("LEAD_ASSIGNMENT_JSON", "")
     if raw:
         try:
-            parsed = json.loads(raw)
-            if isinstance(parsed, dict):
-                return parsed
+            candidate = json.loads(raw)
+            if isinstance(candidate, dict):
+                parsed = candidate
         except json.JSONDecodeError:
             pass
-    provider = (
-        ctx.get("LEAD_PROVIDER", "")
-        or native_provider_for_host(_lead_runtime(ctx))
-        or "claude"
+    source = parsed or {}
+    provider, runner = _resolved_lead_assignment(
+        ctx,
+        source.get("provider", "") or ctx.get("LEAD_PROVIDER", ""),
+        source.get("runner", ""),
     )
     return {
+        **source,
         "role": "lead",
         "provider": provider,
-        "model": ctx.get("LEAD_MODEL", ""),
-        "modelExecutionValue": ctx.get("LEAD_MODEL_EXECUTION_VALUE", ""),
-        "runner": _assignment_runner_for_ctx(ctx, provider),
+        "model": source.get("model", ctx.get("LEAD_MODEL", "")),
+        "modelExecutionValue": source.get(
+            "modelExecutionValue", ctx.get("LEAD_MODEL_EXECUTION_VALUE", "")
+        ),
+        "runner": runner,
     }
 
 
@@ -291,7 +360,7 @@ def _worker_assignments(ctx: dict) -> list[dict]:
         try:
             parsed = json.loads(raw)
             if isinstance(parsed, list) and all(isinstance(row, dict) for row in parsed):
-                return parsed
+                return [_resolved_worker_assignment(ctx, row) for row in parsed]
         except json.JSONDecodeError:
             pass
     catalog = _worker_catalog(ctx, include_assignments=False)
@@ -302,12 +371,39 @@ def _worker_assignments(ctx: dict) -> list[dict]:
             "provider": catalog[worker_id]["agent"],
             "model": catalog[worker_id]["model"],
             "modelExecutionValue": catalog[worker_id]["modelExecutionValue"],
-            "runner": _assignment_runner_for_ctx(ctx, catalog[worker_id]["agent"]),
+            "runner": _assignment_runner_for_ctx(
+                ctx,
+                catalog[worker_id]["agent"],
+                "report-writer" if worker_id == "report-writer" else "analyser",
+            ),
         }
         for worker_id in _resolve_workers(ctx)
     ]
 
 
+def _resolved_worker_assignment(ctx: dict, source: dict) -> dict:
+    worker_id = source.get("workerId", "")
+    role = source.get("role", "") or (
+        "report-writer" if worker_id == "report-writer" else "analyser"
+    )
+    provider = source.get("provider", "") or _fallback_worker_provider(
+        ctx, worker_id
+    )
+    runner = _assignment_runner_for_ctx(
+        ctx,
+        provider,
+        role,
+        source.get("runner", ""),
+    )
+    return {
+        **source,
+        "workerId": worker_id,
+        "role": role,
+        "provider": provider,
+        "runner": runner,
+    }
+
+
 def _worker_catalog(ctx: dict, *, include_assignments: bool = True) -> dict:
     assignments = {} if not include_assignments else {
         row.get("workerId"): row for row in _worker_assignments(ctx)
@@ -329,7 +425,11 @@ def _worker_catalog(ctx: dict, *, include_assignments: bool = True) -> dict:
             "agentLabel": provider_info.display_label,
             "provider": provider,
             "runner": assignment.get(
-                "runner", _assignment_runner_for_ctx(ctx, provider),
+                "runner", _assignment_runner_for_ctx(
+                    ctx,
+                    provider,
+                    "report-writer" if worker_id == "report-writer" else "analyser",
+                ),
             ),
             "model": assignment.get("model", model),
             "modelExecutionValue": assignment.get("modelExecutionValue", execution),
@@ -551,6 +651,7 @@ def render_active_run_context(active_context_path: str, ctx: dict) -> None:
 def render_team_state(team_state_path: str, ctx: dict) -> None:
     selected = _resolve_workers(ctx)
     catalog = _worker_catalog(ctx)
+    worker_dispatch_plan = _worker_dispatch_plan(ctx)
     workers = []
     for w in selected:
         m = catalog[w]
@@ -577,7 +678,7 @@ def render_team_state(team_state_path: str, ctx: dict) -> None:
         "leadRuntime": _lead_runtime(ctx),
         "leadAssignment": _lead_assignment(ctx),
         "workerAssignments": _worker_assignments(ctx),
-        "leadAdapter": _lead_adapter(ctx),
+        "leadAdapter": _lead_adapter(ctx, worker_dispatch_plan),
         "leadEventsPath": ctx.get("LEAD_EVENTS_RELATIVE_PATH", ""),
         "runDirectoryPath": ctx.get("RUN_DIR_RELATIVE_PATH", ""),
         "workflowState": ctx.get("CURRENT_RUN_STATUS", ""),
@@ -1112,6 +1213,7 @@ def render_task_manifest(manifest_path: str, ctx: dict) -> None:
         except Exception:
             existing = {}
     reviewers = _resolve_workers(ctx)
+    worker_dispatch_plan = _worker_dispatch_plan(ctx)
     catalog = _worker_catalog(ctx)
     required_worker_roles = _required_worker_roles(ctx, reviewers)
     worker_prompt_paths = {item: catalog[item]["promptPath"] for item in reviewers}
@@ -1170,7 +1272,7 @@ def render_task_manifest(manifest_path: str, ctx: dict) -> None:
         "leadRuntime": _lead_runtime(ctx),
         "leadAssignment": _lead_assignment(ctx),
         "workerAssignments": _worker_assignments(ctx),
-        "leadAdapter": _lead_adapter(ctx),
+        "leadAdapter": _lead_adapter(ctx, worker_dispatch_plan),
         "workCategory": work_category,
         # user-managed status (set-work-status CLI) — carried across re-renders
         "workStatus": existing.get("workStatus", ""),
@@ -1308,7 +1410,7 @@ def render_task_manifest(manifest_path: str, ctx: dict) -> None:
         "leadSession": {
             "sessionId": ctx.get("CLAUDE_SESSION_ID", ""),
             "resumeCommandPath": ctx.get("CLAUDE_RESUME_COMMAND_RELATIVE_PATH", ""),
-            "accounting": _lead_info(ctx).session_accounting,
+            "accounting": _lead_descriptor(ctx).session_accounting,
         },
         "convergence": convergence_block,
         "createdAt": existing.get("createdAt") or ctx.get("RUN_TIMESTAMP_ISO", ""),
@@ -1418,6 +1520,7 @@ def render_run_manifest(run_manifest_path: str, ctx: dict) -> None:
         except Exception:
             task_manifest = {}
     reviewers = _resolve_workers(ctx)
+    worker_dispatch_plan = _worker_dispatch_plan(ctx)
     catalog = _worker_catalog(ctx)
     required_worker_roles = _required_worker_roles(ctx, reviewers)
     worker_prompt_paths = {item: catalog[item]["promptPath"] for item in reviewers}
@@ -1452,7 +1555,7 @@ def render_run_manifest(run_manifest_path: str, ctx: dict) -> None:
         "runtimeResolution": _runtime_resolution(ctx),
         "leadAssignment": _lead_assignment(ctx),
         "workerAssignments": _worker_assignments(ctx),
-        "leadAdapter": _lead_adapter(ctx),
+        "leadAdapter": _lead_adapter(ctx, worker_dispatch_plan),
         "workCategory": task_manifest.get(
             "workCategory", ctx.get("WORKFLOW_WORK_CATEGORY", "unknown")
         ),
@@ -1957,6 +2060,7 @@ def inject_lead_prompt_computed_tokens(ctx: dict) -> None:
     selected = _resolve_workers(ctx)
     catalog = _worker_catalog(ctx)
     lead_runtime = _lead_runtime(ctx)
+    worker_dispatch_plan = _worker_dispatch_plan(ctx)
     lead_role = _lead_role(ctx)
     lead_agent_label = _lead_agent_label(ctx)
     lead_model = ctx.get("LEAD_MODEL", "")
@@ -1966,7 +2070,7 @@ def inject_lead_prompt_computed_tokens(ctx: dict) -> None:
         home_prompts / "lead" / "okstra-lead-contract.md"
     )
     adapter_contract_path = ctx.get("OKSTRA_LEAD_ADAPTER_CONTRACT_PATH") or str(
-        home_prompts / _lead_info(ctx).adapter_contract_relative_path
+        home_prompts / _lead_adapter_contract(ctx, worker_dispatch_plan)
     )
     context_loader_path = ctx.get("OKSTRA_CONTEXT_LOADER_PATH") or str(
         home_prompts / "lead" / "context-loader.md"
@@ -2163,27 +2267,21 @@ def inject_lead_prompt_computed_tokens(ctx: dict) -> None:
         "schema and write rules. Do not re-inline either contract."
     )
 
-    if lead_runtime == "external":
+    lead_descriptor = _lead_descriptor(ctx)
+    if lead_descriptor.has_claude_session:
         lead_session_block = (
             "## Session\n"
             "\n"
-            "- Lead runtime: `external`\n"
-            "- Lead session accounting: artifact-only; this harness does not expose Claude Code jsonl session IDs."
-        )
-    elif lead_runtime == "codex":
-        lead_session_block = (
-            "## Session\n"
-            "\n"
-            "- Lead runtime: `codex`\n"
-            "- Codex run resume is artifact/checkpoint based; `okstra codex-run` "
-            "does not create a Claude session id."
+            f"- Session ID: `{ctx.get('CLAUDE_SESSION_ID', '')}`\n"
+            f"- Resume: `{ctx.get('CLAUDE_RESUME_COMMAND_RELATIVE_PATH', '')}`"
         )
     else:
         lead_session_block = (
             "## Session\n"
             "\n"
-            f"- Session ID: `{ctx.get('CLAUDE_SESSION_ID', '')}`\n"
-            f"- Resume: `{ctx.get('CLAUDE_RESUME_COMMAND_RELATIVE_PATH', '')}`"
+            f"- Lead runtime: `{lead_descriptor.id}`\n"
+            f"- Lead session accounting: {lead_descriptor.session_accounting}\n"
+            "- Resume behavior is provided by the selected host lead-session port."
         )
 
     # Compute results (deterministic from ctx, 덮어쓰기)

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

@@ -5,21 +5,36 @@ import re
 
 
 # Every block whose rows prose cites but no section of its own renders, with
-# the keys each one names its content and its provenance by. A key hunt across
-# all of them would misread `crossVerification.consensus`, whose `evidence` key
-# holds provenance while `evidence.primary` uses the same word for content —
-# so the block a row came from is named here rather than guessed.
+# the keys each one names its content, its provenance, and its confidence by. A
+# key hunt across all of them would misread `crossVerification.consensus`, whose
+# `evidence` key holds provenance while `evidence.primary` uses the same word
+# for content — so the block a row came from is named here rather than guessed.
+#
+# Source and confidence are separate columns because most blocks carry only one
+# of the two: `evidence.primary` cites a file and never rates itself, while
+# `evidence.secondary` rates itself and cites nothing. Folding them into one
+# field is what made the ledger label every row "source · confidence" and then
+# print a single value under it.
+#
+# `endStateCoverage` is deliberately absent. Its rows hold an id pair
+# (`EB-001` covered by `R-001`) rather than a statement, so the ledger rendered
+# them as an id with no body, and the requirement-coverage table already names
+# every one of them in its Source column.
+#
+# The kind each row carries is a vocabulary key, not the words the reader sees:
+# the labels live in the i18n `ledgerKind` table so they arrive in the reader's
+# language. `evidence.primary` was previously stamped "unclassified", which
+# named the renderer's own indecision rather than anything about the row.
 _LEDGER_BLOCKS = (
-    (("evidence", "primary"), "evidence", "source", "unclassified"),
-    (("evidence", "secondary"), "hypothesis", "confidence", "hypothesis"),
-    (("analysisCommon", "confirmedFacts"), "statement", "", "confirmed fact"),
-    (("analysisCommon", "inferences"), "statement", "confidence", "inference"),
-    (("analysisCommon", "unknowns"), "question", "reason", "unknown"),
-    (("crossVerification", "consensus"), "statement", "evidence", "cross-check consensus"),
-    (("crossVerification", "differences"), "disagreement", "workersPosition", "cross-check dissent"),
-    (("missingInformation",), "item", "risk", "missing information"),
-    (("endStateCoverage",), "coveredBy", "evidence", "exit contract"),
-    (("followUpTasks",), "title", "reason", "follow-up"),
+    (("evidence", "primary"), "evidence", "source", "", "code-evidence"),
+    (("evidence", "secondary"), "hypothesis", "", "confidence", "hypothesis"),
+    (("analysisCommon", "confirmedFacts"), "statement", "", "", "confirmed-fact"),
+    (("analysisCommon", "inferences"), "statement", "", "confidence", "inference"),
+    (("analysisCommon", "unknowns"), "question", "reason", "", "unknown"),
+    (("crossVerification", "consensus"), "statement", "evidence", "", "cross-check-consensus"),
+    (("crossVerification", "differences"), "disagreement", "workersPosition", "", "cross-check-dissent"),
+    (("missingInformation",), "item", "risk", "", "missing-information"),
+    (("followUpTasks",), "title", "reason", "", "follow-up"),
 )
 
 
@@ -32,23 +47,39 @@ def _dig(data: dict, path: tuple[str, ...]) -> list:
     return node if isinstance(node, list) else []
 
 
-def _ledger_row(row: dict, text_key: str, source_key: str, kind: str) -> dict[str, object]:
+def _joined(value: object) -> str:
+    """One reader-facing string for a cell a block may fill with either a
+    sentence or a list of citations. `str()` on a list prints Python's own
+    repr — quotes, brackets and all — straight into the report.
+    """
+    if isinstance(value, (list, tuple)):
+        return " · ".join(str(item) for item in value if item)
+    return str(value or "")
+
+
+def _ledger_row(
+    row: dict, text_key: str, source_key: str, confidence_key: str, kind: str
+) -> dict[str, object]:
     return {
         "id": row.get("id", ""),
         "kind": kind,
-        "text": str(row.get(text_key) or ""),
+        "text": _joined(row.get(text_key)),
         "codeEvidence": row.get("currentCodeEvidence") or [],
-        "source": str(row.get(source_key) or "") if source_key else "",
+        "source": _joined(row.get(source_key)) if source_key else "",
+        "confidence": _joined(row.get(confidence_key)) if confidence_key else "",
     }
 
 
-def _own_section_ids(data: dict) -> set[str]:
+def _own_section_ids(data: dict, omitted_fields: tuple[str, ...] = ()) -> set[str]:
     """Ids a section of the report already renders and anchors.
 
     The ledger is the fallback home for a cited row, so it must not claim an id
     that has one — two elements with the same anchor send half the links to the
     wrong place. `crossVerification.consensus` numbers its rows `C-001` in some
     runs, exactly where a clarification lives.
+
+    `omitted_fields` names task-block fields the HTML template does not render,
+    so their ids do not count as anchored.
     """
     from ..report_contract import TASK_TYPE_DATA_PROPERTY
 
@@ -56,20 +87,34 @@ def _own_section_ids(data: dict) -> set[str]:
     _collect_ids(data.get("clarificationItems", []), found)
     property_name = TASK_TYPE_DATA_PROPERTY.get(data.get("header", {}).get("taskType", ""))
     if property_name:
-        _collect_ids(data.get(property_name, {}), found)
+        block = data.get(property_name, {})
+        if omitted_fields and isinstance(block, dict):
+            block = {
+                key: value for key, value in block.items() if key not in omitted_fields
+            }
+        _collect_ids(block, found)
     return found
 
 
 def evidence_index(data: dict) -> dict[str, object]:
+    """The rows the ledger carries, keyed by id.
+
+    A row whose statement came out empty is dropped rather than listed: the
+    ledger exists so a cited id resolves to something the reader can read, and
+    an id above a blank line resolves to nothing.
+    """
     owned = _own_section_ids(data)
     rows: dict[str, object] = {}
-    for path, text_key, source_key, kind in _LEDGER_BLOCKS:
+    for path, text_key, source_key, confidence_key, kind in _LEDGER_BLOCKS:
         for row in _dig(data, path):
             if not isinstance(row, dict):
                 continue
             row_id = row.get("id")
-            if row_id and row_id not in owned and row_id not in rows:
-                rows[row_id] = _ledger_row(row, text_key, source_key, kind)
+            if not row_id or row_id in owned or row_id in rows:
+                continue
+            entry = _ledger_row(row, text_key, source_key, confidence_key, kind)
+            if entry["text"]:
+                rows[row_id] = entry
     return rows
 
 
@@ -88,7 +133,7 @@ def _collect_ids(value: object, found: set[str]) -> None:
 _ROW_ID = re.compile(r"[A-Z]{1,3}-\d+")
 
 
-def anchor_index(data: dict) -> dict[str, str]:
+def anchor_index(data: dict, omitted_fields: tuple[str, ...] = ()) -> dict[str, str]:
     """Map every row a reader can reach to the anchor name that lands on it.
 
     Prose cites ids across section boundaries — a hotspot names a
@@ -98,9 +143,10 @@ def anchor_index(data: dict) -> dict[str, str]:
 
     It stops there. `summary` is the AI-facing digest and
     `analysisCommon.scope` describes the analysis target rather than listing
-    rows; neither renders, so a link to one would land nowhere.
+    rows; neither renders, so a link to one would land nowhere. Same for the
+    blocks a template declares in `omitted_fields`.
     """
-    found = _own_section_ids(data) | set(evidence_index(data))
+    found = _own_section_ids(data, omitted_fields) | set(evidence_index(data))
     return {row_id: f"id-{row_id}" for row_id in sorted(found) if _ROW_ID.fullmatch(row_id)}
 
 

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

@@ -66,6 +66,11 @@ class HumanReportView:
     template_name: str
     context: dict[str, object]
     figures: tuple[FigureModel, ...]
+    # Task-block fields this template leaves out of the HTML. Their rows still
+    # exist in the data and the markdown, so prose keeps citing their ids — but
+    # an anchor to a row this document never renders scrolls nowhere, which
+    # reads as a broken report rather than as a deliberate omission.
+    omitted_fields: tuple[str, ...] = ()
 
 
 @dataclass(frozen=True)

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

@@ -130,7 +130,7 @@ def render_v2_html_view(
     env.policies["json.dumps_kwargs"] = {"sort_keys": True, "ensure_ascii": False}
     # Binding the index here is what lets a template cite an id without
     # threading the index through every macro and call site.
-    anchors = anchor_index(data)
+    anchors = anchor_index(data, view.omitted_fields)
     chrome = load_dictionary(lang, HTML_DICTIONARY_REL)
     translate = make_jinja_global(chrome)
     env.globals["t"] = translate

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

@@ -23,6 +23,7 @@ def _totals_row(row: object) -> dict[str, str]:
     values = row if isinstance(row, dict) else {}
     return {
         "rawTokens": format_int(values.get("totalTokens")),
+        "cacheReadTokens": format_int(values.get("cacheReadTokens")),
         "billableTokens": format_int(values.get("billableTokens")),
         "cost": format_usd(values.get("costUsd")),
     }
@@ -43,6 +44,7 @@ def _agent_row(row: dict) -> dict[str, str]:
         "model": str(row.get("model") or ""),
         "status": str(row.get("status") or ""),
         "rawTokens": format_int(row.get("totalTokens")),
+        "cacheReadTokens": format_int(row.get("cacheReadTokens")),
         "billableTokens": format_int(row.get("billableTokens")),
         "cost": format_usd(row.get("costUsd")),
         "duration": format_duration_ms(row.get("durationMs")),
@@ -70,15 +72,31 @@ def _unaccounted(rows: list[dict], grand: dict) -> dict[str, str] | None:
     gap = grand_tokens - _sum(rows, "totalTokens")
     if gap <= 0:
         return None
+    cache_gap = (_number(grand.get("cacheReadTokens")) or 0) - _sum(rows, "cacheReadTokens")
     billable_gap = (_number(grand.get("billableTokens")) or 0) - _sum(rows, "billableTokens")
     cost_gap = (_number(grand.get("costUsd")) or 0) - _sum(rows, "costUsd")
     return {
         "rawTokens": format_int(gap),
+        "cacheReadTokens": format_int(max(0, cache_gap)),
         "billableTokens": format_int(max(0, billable_gap)),
         "cost": format_usd(max(0.0, cost_gap)),
     }
 
 
+def _task_cumulative(row: object) -> dict[str, str] | None:
+    """What the task has spent over every run, when more than this one exists.
+
+    A single-run task would repeat the grand total word for word, and a reader
+    seeing the same figure twice reads it as a second charge.
+    """
+    if not isinstance(row, dict):
+        return None
+    run_count = _number(row.get("runCount")) or 0
+    if run_count < 2:
+        return None
+    return {**_totals_row(row), "runCount": format_int(run_count)}
+
+
 _MEASURED_KEYS = ("totalTokens", "billableTokens", "costUsd", "durationMs")
 
 
@@ -106,5 +124,6 @@ def run_usage(data: dict) -> dict[str, object] | None:
         "rows": [_agent_row(row) for row in rows],
         "unaccounted": _unaccounted(rows, usage.get("grand") or {}),
         **totals,
+        "taskCumulative": _task_cumulative(usage.get("taskCumulative")),
         "cliCost": format_usd(cli_cost) if cli_cost else "",
     }

package/runtime/python/okstra_ctl/report_html/view_models/implementation_planning.py

@@ -74,6 +74,19 @@ def _stage_figure(planning: dict):
     return stage_map_figure(nodes=nodes, edges=edges, title="Implementation stage dependencies")
 
 
+# Blocks the approver's view leaves to the markdown report: the checklist the
+# implementer works from, the dependency and rollback tables an incident reader
+# needs, and the verification rounds the audit trail keeps. Declared here so the
+# ids they carry stop being anchor targets in this document.
+_OMITTED_FIELDS = (
+    "validationChecklist",
+    "crossProjectDependencies",
+    "dependencyMigrationRisk",
+    "rollbackStrategy",
+    "planBodyVerification",
+)
+
+
 def build_implementation_planning_view(data: dict) -> HumanReportView:
     planning = data["implementationPlanning"]
     figure = _stage_figure(planning)
@@ -97,4 +110,5 @@ def build_implementation_planning_view(data: dict) -> HumanReportView:
         "html/tasks/implementation-planning.template.html",
         context,
         (figure,),
+        _OMITTED_FIELDS,
     )