okstra 0.158.1 → 0.160.0

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

@@ -0,0 +1,110 @@
+"""What the run cost, per agent — the Phase 7 usage cells as reader-facing text.
+
+`executionStatus` is the only block that holds a duration per agent, so the
+table is built from it rather than from `tokenUsage.workerDetails`, which
+repeats the same token figures without saying how long each agent ran.
+
+The formatting happens here rather than in the template because a null cell has
+to read as "not measured" everywhere it appears, and `usage_cells` is where both
+report views agree on how that looks.
+"""
+from __future__ import annotations
+
+from ..usage_cells import format_duration_ms, format_int, format_usd
+
+
+def _number(value: object) -> int | float | None:
+    if isinstance(value, bool) or not isinstance(value, (int, float)):
+        return None
+    return value
+
+
+def _totals_row(row: object) -> dict[str, str]:
+    values = row if isinstance(row, dict) else {}
+    return {
+        "rawTokens": format_int(values.get("totalTokens")),
+        "billableTokens": format_int(values.get("billableTokens")),
+        "cost": format_usd(values.get("costUsd")),
+    }
+
+
+def _agent_row(row: dict) -> dict[str, str]:
+    """One agent's identity and what it spent.
+
+    The CLI cells stay empty rather than `--` when the agent made no CLI call:
+    they render as a second line inside the token and cost cells, and a `--`
+    there would read as a missing measurement instead of an absent charge.
+    """
+    cli_tokens = _number(row.get("cliTotalTokens")) or 0
+    cli_cost = _number(row.get("cliCostUsd")) or 0
+    return {
+        "agent": str(row.get("agent") or ""),
+        "role": str(row.get("role") or ""),
+        "model": str(row.get("model") or ""),
+        "status": str(row.get("status") or ""),
+        "rawTokens": format_int(row.get("totalTokens")),
+        "billableTokens": format_int(row.get("billableTokens")),
+        "cost": format_usd(row.get("costUsd")),
+        "duration": format_duration_ms(row.get("durationMs")),
+        "cliTokens": format_int(cli_tokens) if cli_tokens else "",
+        "cliCost": format_usd(cli_cost) if cli_cost else "",
+    }
+
+
+def _sum(rows: list[dict], key: str) -> int | float:
+    return sum(_number(row.get(key)) or 0 for row in rows)
+
+
+def _unaccounted(rows: list[dict], grand: dict) -> dict[str, str] | None:
+    """The part of the total that no row above carries, when there is one.
+
+    Two documented paths leave a gap. Sessions that match no worker are summed
+    into `unattributedWorkerUsage`, and where two report rows share one
+    team-state aggregate only the first is attributed, leaving the second's
+    cells null. Both land in the total, so without this row the column adds up
+    to less than the figure beneath it and neither number can be trusted.
+    """
+    grand_tokens = _number(grand.get("totalTokens"))
+    if grand_tokens is None:
+        return None
+    gap = grand_tokens - _sum(rows, "totalTokens")
+    if gap <= 0:
+        return None
+    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),
+        "billableTokens": format_int(max(0, billable_gap)),
+        "cost": format_usd(max(0.0, cost_gap)),
+    }
+
+
+_MEASURED_KEYS = ("totalTokens", "billableTokens", "costUsd", "durationMs")
+
+
+def run_usage(data: dict) -> dict[str, object] | None:
+    """The run-cost table, or nothing when the run has no measured figure.
+
+    Phase 7 fills these cells before the HTML is rendered, so an all-null table
+    means the collector found no session to read. A grid of `--` states nothing
+    the reader can act on, so the section stays out of the document entirely.
+    """
+    rows = [row for row in (data.get("executionStatus") or []) if isinstance(row, dict)]
+    usage = data.get("tokenUsage") or {}
+    totals = {name: _totals_row(usage.get(name)) for name in ("lead", "worker", "grand")}
+    measured = any(
+        _number(row.get(key)) is not None for row in rows for key in _MEASURED_KEYS
+    ) or any(
+        _number((usage.get(name) or {}).get(key)) is not None
+        for name in ("lead", "worker", "grand")
+        for key in _MEASURED_KEYS
+    )
+    if not measured:
+        return None
+    cli_cost = _number((usage.get("cli") or {}).get("costUsd")) or 0
+    return {
+        "rows": [_agent_row(row) for row in rows],
+        "unaccounted": _unaccounted(rows, usage.get("grand") or {}),
+        **totals,
+        "cliCost": format_usd(cli_cost) if cli_cost else "",
+    }

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

@@ -1,32 +1,85 @@
 """Human-first error-analysis view model."""
 from __future__ import annotations
 
+import re
+
 from ..common import evidence_index
 from ..models import HumanReportView, VisualEdge, VisualNode
 from ..visualizations import cause_graph_figure
 
 
-def _cause_figure(error: dict):
-    symptom = VisualNode(
-        "symptom", "Observed failure", "effect", "risk", error["observableFailure"], note="Observed failure"
+_LEAD_CLAUSE = re.compile(r"\s[—–-]\s|(?<=[.。!?])\s")
+_MAX_LABEL_CHARS = 44
+
+
+def _short_label(statement: str) -> str:
+    """The candidate's name, taken from the opening clause of its statement.
+
+    `causeCandidates` carries no title field: `statement` is the full claim,
+    routinely several sentences long. Passed through whole it filled the
+    figure's name cell with prose and ran the node text out of the drawing, so
+    the figure takes the lead clause and leaves the claim to the cards below.
+    """
+    head = _LEAD_CLAUSE.split(statement.strip(), maxsplit=1)[0].strip()
+    if len(head) <= _MAX_LABEL_CHARS:
+        return head
+    return head[:_MAX_LABEL_CHARS].rstrip() + "…"
+
+
+def _cause_node(row: dict, leading_cause_id: str) -> VisualNode:
+    # The figure names its nodes and nothing more. Both the failure sentence
+    # and each candidate's disproof already have a section of their own, and
+    # repeating them here printed every one of them twice.
+    leading = row["id"] == leading_cause_id
+    return VisualNode(
+        row["id"],
+        _short_label(row["statement"]),
+        "candidate",
+        "leading" if leading else row["confidence"],
+        "",
+        note="Leading cause" if leading else f'Confidence {row["confidence"]}',
     )
-    causes = tuple(
-        VisualNode(
-            row["id"],
-            row["statement"],
-            "candidate",
-            row["confidence"],
-            row["disproveWith"],
-            note=f'Confidence {row["confidence"]}',
-        )
-        for row in error.get("causeCandidates", [])
+
+
+def _cause_edges(rows: list[dict], symptom_id: str) -> tuple[VisualEdge, ...]:
+    """The chain between candidates, then the symptom each chain ends at.
+
+    Candidates are not always competing guesses for one spot. A propagation
+    chain — the extraction breaks, the error is swallowed, the empty result is
+    stamped a success — needs every link to hold for the symptom to appear, and
+    `downstreamOf` is where the diagnosis says so. Drawing every candidate
+    straight at the symptom instead claimed they were alternatives.
+
+    Only a candidate nothing else is downstream of reaches the symptom: an
+    upstream link would otherwise be drawn as its own explanation of the
+    symptom as well as a step on the way there.
+    """
+    known = {row["id"] for row in rows}
+    upstream = {
+        row["id"]: [step for step in row.get("downstreamOf", []) if step in known]
+        for row in rows
+    }
+    has_downstream = {step for steps in upstream.values() for step in steps}
+    chain = tuple(
+        VisualEdge(step, row["id"], "then", "chain")
+        for row in rows
+        for step in upstream[row["id"]]
     )
-    edges = tuple(
-        VisualEdge(row.id, symptom.id, "may cause", "hypothesis") for row in causes
+    return chain + tuple(
+        VisualEdge(row["id"], symptom_id, "may cause", "hypothesis")
+        for row in rows
+        if row["id"] not in has_downstream
     )
+
+
+def _cause_figure(error: dict):
+    symptom = VisualNode("symptom", "Observed failure", "effect", "risk", "", note="Symptom")
+    rows = error.get("causeCandidates", [])
+    leading_cause_id = (error.get("routing") or {}).get("leadingCauseId") or ""
+    causes = tuple(_cause_node(row, leading_cause_id) for row in rows)
     return cause_graph_figure(
         nodes=(symptom, *causes),
-        edges=edges,
+        edges=_cause_edges(rows, symptom.id),
         title="Cause hypotheses and observed symptom",
     )
 

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

@@ -2,6 +2,7 @@
 from __future__ import annotations
 
 import html
+import unicodedata
 from dataclasses import replace
 from typing import Iterable, Sequence
 
@@ -11,6 +12,11 @@ from .models import FigureModel, VisualEdge, VisualNode
 _ROWS_PER_COLUMN = 8
 _COLUMN_WIDTH = 260
 _ROW_HEIGHT = 100
+_NODE_WIDTH = 180
+_NODE_MIN_HEIGHT = 50
+_LABEL_PADDING = 12
+_LINE_HEIGHT = 16
+_MAX_LABEL_LINES = 3
 
 
 def _group_columns(nodes: Sequence[VisualNode]) -> list[list[str]]:
@@ -141,10 +147,103 @@ _ARROW_MARKER = (
 )
 
 
+def _drawable_text(value: str) -> str:
+    """Strip the markdown code fences a drawing cannot render.
+
+    Labels carry backticks around identifiers because every other text surface
+    turns them into `<code>`. Drawn literally they are stray characters inside
+    the box, and they consume width the label needs.
+    """
+    return value.replace("`", "")
+
+
+def _text_width(text: str) -> float:
+    """Approximate the advance width of the 13px label font.
+
+    An SVG carries no font metrics, so wrapping has to estimate. East-Asian
+    characters occupy a full em; the rest average a little over half of one.
+    """
+    return sum(13.0 if unicodedata.east_asian_width(c) in ("W", "F") else 6.8 for c in text)
+
+
+def _split_oversized_word(word: str, limit: float) -> list[str]:
+    """Cut a word wider than the box into box-width pieces.
+
+    Korean and Japanese labels arrive as long unbroken runs, and a path or an
+    identifier can be wider than the box on its own.
+    """
+    pieces: list[str] = []
+    current = ""
+    for char in word:
+        if current and _text_width(current + char) > limit:
+            pieces.append(current)
+            current = char
+        else:
+            current += char
+    return pieces + [current] if current else pieces
+
+
+def _ellipsize(line: str, limit: float) -> str:
+    while line and _text_width(line + "…") > limit:
+        line = line[:-1]
+    return line + "…"
+
+
+def _wrap_label(label: str) -> list[str]:
+    """Break a label into the lines that fit inside one node box.
+
+    The label used to be drawn as a single line whatever its length, so a node
+    carrying a sentence painted it straight out of the box and off the canvas.
+    Text past the last line is cut here rather than drawn, because the
+    figure's fallback table prints the label in full.
+    """
+    limit = _NODE_WIDTH - 2 * _LABEL_PADDING
+    lines: list[str] = []
+    current = ""
+    for word in label.split():
+        pieces = _split_oversized_word(word, limit) if _text_width(word) > limit else [word]
+        for piece in pieces:
+            candidate = f"{current} {piece}".strip()
+            if current and _text_width(candidate) > limit:
+                lines.append(current)
+                current = piece
+            else:
+                current = candidate
+    if current:
+        lines.append(current)
+    if len(lines) > _MAX_LABEL_LINES:
+        lines = lines[:_MAX_LABEL_LINES]
+        lines[-1] = _ellipsize(lines[-1], limit)
+    return lines or [""]
+
+
+def _node_group(node: VisualNode, x: int, y: int, lines: Sequence[str], box_height: int) -> str:
+    baseline = y + (box_height - len(lines) * _LINE_HEIGHT) // 2 + _LINE_HEIGHT - 4
+    spans = "".join(
+        f'<tspan x="{x + _LABEL_PADDING}" y="{baseline + index * _LINE_HEIGHT}">'
+        f"{html.escape(line)}</tspan>"
+        for index, line in enumerate(lines)
+    )
+    status = html.escape(node.status)
+    detail = _drawable_text(node.detail)
+    tooltip = f"{_drawable_text(node.label)}: {node.status}." + (f" {detail}" if detail else "")
+    return (
+        f'<g data-node-id="{html.escape(node.id)}" class="node node-{status}">'
+        f"<title>{html.escape(tooltip)}</title>"
+        f'<rect x="{x}" y="{y}" width="{_NODE_WIDTH}" height="{box_height}" rx="8"/>'
+        f"<text>{spans}</text></g>"
+    )
+
+
 def _svg_document(nodes: Sequence[VisualNode], edges: Sequence[VisualEdge]) -> str:
     positions = _node_positions(nodes, edges)
-    width = max((x for x, _ in positions.values()), default=50) + 230
-    height = max((y for _, y in positions.values()), default=55) + 90
+    wrapped = {node.id: _wrap_label(_drawable_text(node.label)) for node in nodes}
+    line_count = max((len(lines) for lines in wrapped.values()), default=1)
+    # One height for every box: a figure whose rows are all the same depth
+    # keeps the arrow between two columns horizontal.
+    box_height = max(_NODE_MIN_HEIGHT, line_count * _LINE_HEIGHT + 2 * _LABEL_PADDING)
+    width = max((x for x, _ in positions.values()), default=50) + _NODE_WIDTH + 50
+    height = max((y for _, y in positions.values()), default=55) + box_height + 40
     parts = [f'<svg viewBox="0 0 {width} {height}" role="img" xmlns="http://www.w3.org/2000/svg">']
     parts.append(_ARROW_MARKER)
     for edge in edges:
@@ -154,8 +253,11 @@ def _svg_document(nodes: Sequence[VisualNode], edges: Sequence[VisualEdge]) -> s
         x2, y2 = positions[edge.target]
         # Leave the source box on its right edge and arrive on the target's
         # left, so a left-to-right layering reads as one direction of travel.
-        start_x, end_x = (x1 + 180, x2) if x2 > x1 else ((x1, x2 + 180) if x2 < x1 else (x1 + 90, x2 + 90))
-        start_y, end_y = y1 + 25, y2 + 25
+        forward = (x1 + _NODE_WIDTH, x2)
+        backward = (x1, x2 + _NODE_WIDTH)
+        same_column = (x1 + _NODE_WIDTH // 2, x2 + _NODE_WIDTH // 2)
+        start_x, end_x = forward if x2 > x1 else (backward if x2 < x1 else same_column)
+        start_y, end_y = y1 + box_height // 2, y2 + box_height // 2
         span = abs(x2 - x1) // _COLUMN_WIDTH
         if span > 1:
             # An edge that skips a column would otherwise be drawn straight
@@ -177,16 +279,7 @@ def _svg_document(nodes: Sequence[VisualNode], edges: Sequence[VisualEdge]) -> s
         )
     for node in nodes:
         x, y = positions[node.id]
-        node_id = html.escape(node.id)
-        label = html.escape(node.label)
-        status = html.escape(node.status)
-        detail = html.escape(node.detail)
-        parts.append(
-            f'<g data-node-id="{node_id}" class="node node-{status}">'
-            f"<title>{label}: {status}. {detail}</title>"
-            f'<rect x="{x}" y="{y}" width="180" height="50" rx="8"/>'
-            f'<text x="{x + 12}" y="{y + 30}">{label}</text></g>'
-        )
+        parts.append(_node_group(node, x, y, wrapped[node.id], box_height))
     parts.append("</svg>")
     return "".join(parts)
 

package/runtime/python/okstra_ctl/report_translation.py

@@ -24,7 +24,9 @@ from typing import Any, Iterator, Mapping, NamedTuple
 # Values the renderer reads as text and nothing else.
 PROSE_KEYS = frozenset({
     "acceptance",
+    "addedWork",
     "alternativesConsidered",
+    "answer",
     "approach",
     "approvalDisposition",
     "approvalEvidence",
@@ -50,6 +52,7 @@ PROSE_KEYS = frozenset({
     "declinedFixRecommendations",
     "description",
     "details",
+    "directionChange",
     "disagreement",
     "discrepancy",
     "disproveWith",
@@ -236,6 +239,7 @@ STRUCTURAL_KEYS = frozenset({
     "runManifest",
     "runSeq",
     "scope",              # 'PF-001' alongside prose
+    "scopeImpact",        # clarification reach tokens the gate matches on
     "sections",
     "shortSha",
     "signature",

package/runtime/python/okstra_ctl/report_views.py

@@ -693,12 +693,16 @@ def _strip_leading_letter_label(text: str) -> str:
     return re.sub(r"^\([a-z]\)\s*", "", text)
 
 
-def _parse_expected_form_options(expected_form: str) -> list[tuple[str, str]]:
+def parse_expected_form_options(expected_form: str) -> list[tuple[str, str]]:
     """Parse the ``Expected form`` contract format
     (``Recommended: <answer> — <rationale>; Alternatives: <options>``,
     `_common-contract.md` §Clarification request policy) into select
     ``(value, label)`` options. Returns ``[]`` when the cell carries no
-    ``Recommended:`` cue — the caller falls back to the statement enum."""
+    ``Recommended:`` cue — the caller falls back to the statement enum.
+
+    The single parser for this cell. Both the HTML view and
+    ``user_response.show_open_rows`` call it; a second implementation is
+    exactly how the two option boards drifted apart once already."""
     if not expected_form:
         return []
     expected_form = _PICK_ONE_ANNOTATION.sub("", expected_form)
@@ -791,7 +795,7 @@ def _form_control(
     # 계약(_common-contract.md §Clarification request policy)이 1순위,
     # statement 안 (a)(b)(c) 열거가 fallback. 후보가 있으면 select+기타 input.
     if kind_lc == "decision":
-        opts = _parse_expected_form_options(expected_form)
+        opts = parse_expected_form_options(expected_form)
         if not opts:
             opts = [
                 (letter, f"({letter}) {text}")

package/runtime/python/okstra_ctl/run.py

@@ -45,6 +45,7 @@ from .clarification_items import (
     clarification_response_with_sidecars,
     scan_approval_gate,
 )
+from .error_report import prior_run_error_digest
 from .qa_commands import format_errors as _format_qa_errors, validate_qa_commands
 from .material import (
     build_analysis_material,
@@ -857,6 +858,10 @@ class _ResolvedAssets:
     lead_contract: Path
     run_validator: Path
     brief_validator: Path
+    # None when this task-type's host orchestration carries no gates; see
+    # prompts/host-orchestration/README.md. Absence is a normal state, not a
+    # broken install, so it is exempt from the _INSTALL_HINT contract above.
+    host_rules_file: Path | None
 
 
 def _resolve_runtime_assets(workspace_root: Path, inp: PrepareInputs) -> _ResolvedAssets:
@@ -892,6 +897,9 @@ def _resolve_runtime_assets(workspace_root: Path, inp: PrepareInputs) -> _Resolv
             raise PrepareError(
                 f"required okstra template or lead contract missing: {required}.{_INSTALL_HINT}"
             )
+    host_rules_file = (
+        workspace_root / "prompts" / "host-orchestration" / f"{inp.task_type}.md"
+    )
     return _ResolvedAssets(
         profile_file=profile_file,
         prompt_template=prompt_template,
@@ -900,6 +908,7 @@ def _resolve_runtime_assets(workspace_root: Path, inp: PrepareInputs) -> _Resolv
         lead_contract=lead_contract,
         run_validator=run_validator,
         brief_validator=brief_validator,
+        host_rules_file=host_rules_file if host_rules_file.is_file() else None,
     )
 
 
@@ -1766,8 +1775,24 @@ def _write_verification_target_artifact(
     ctx["VERIFICATION_TARGET"] = target_path.read_text(encoding="utf-8")
 
 
+def _write_prior_run_error_digest(ctx: dict, instruction_set: Path) -> None:
+    """Stage the earlier runs' actionable errors — only when there are any.
+
+    No file at all when the task recorded none, rather than one saying "none":
+    a staged file the lead must open to learn it is empty costs a read every
+    run and teaches the lead to stop opening that path.
+    """
+    digest = prior_run_error_digest(Path(ctx["TASK_ROOT"]))
+    if digest:
+        (instruction_set / "prior-run-errors.md").write_text(digest, encoding="utf-8")
+
+
 def _write_instruction_set_sources(
-    inp: PrepareInputs, ctx: dict, profile_content: str, review_material: str
+    inp: PrepareInputs,
+    ctx: dict,
+    profile_content: str,
+    review_material: str,
+    host_rules_file: Path | None,
 ) -> Path:
     """instruction-set 디렉터리에 profile/material/brief/clarification/directive 와
     reference-expectations 를 기록하고 디렉터리 경로를 돌려준다."""
@@ -1775,6 +1800,7 @@ def _write_instruction_set_sources(
     instruction_set.mkdir(parents=True, exist_ok=True)
     _write_analysis_evidence_artifact(ctx, instruction_set)
     _write_verification_target_artifact(inp, ctx, instruction_set)
+    _write_prior_run_error_digest(ctx, instruction_set)
     profile_rendered = profile_content
     if inp.task_type == "implementation":
         profile_rendered += "\n\n{{DESIGN_PREP_CONTEXT}}\n\n{{FIX_RUN_CONTEXT}}"
@@ -1814,6 +1840,19 @@ def _write_instruction_set_sources(
         )
     (instruction_set / "analysis-material.md").write_text(review_material, encoding="utf-8")
     shutil.copyfile(inp.brief_path, instruction_set / "task-brief.md")
+    # A rule that lives only in the conversation is one compaction away from
+    # gone, with no signal that it went. On disk it survives, and the session
+    # conformance check can ask afterwards whether it was read. The token is
+    # set unconditionally because render_template_with_ctx fail-fasts on a
+    # token the launch template references but ctx lacks.
+    host_rules_relative = ""
+    if host_rules_file is not None:
+        staged_host_rules = instruction_set / "host-orchestration-rules.md"
+        shutil.copyfile(host_rules_file, staged_host_rules)
+        host_rules_relative = relative_to_project_root(
+            staged_host_rules, Path(ctx["PROJECT_ROOT"])
+        )
+    ctx["HOST_ORCHESTRATION_RULES_RELATIVE_PATH"] = host_rules_relative
     if inp.clarification_response_path:
         (instruction_set / "clarification-response.md").write_text(
             clarification_response_with_sidecars(Path(inp.clarification_response_path)),
@@ -2556,7 +2595,7 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
 
     # ---- write instruction-set scaffolding + lead prompt ----
     instruction_set = _write_instruction_set_sources(
-        inp, ctx, profile_content, review_material
+        inp, ctx, profile_content, review_material, assets.host_rules_file
     )
     prompt_text = _render_lead_prompt_and_snapshot(
         inp, ctx, instruction_set, final_report_template, prompt_template