okstra 0.154.1 → 0.155.0

package/runtime/python/okstra_ctl/render_final_report.py

@@ -870,3 +870,32 @@ def render_to_file(
     tmp.write_text(rendered, encoding="utf-8")
     tmp.replace(output_path)
     return len(rendered.encode("utf-8"))
+
+
+def snapshot_last_valid(data_path: Path) -> Path | None:
+    """Keep the data.json that just rendered, as `<name>.last-valid`.
+
+    The gate blocks in this file are hand-edited between self-fix rounds, and a
+    write in the wrong shape destroys the previous round's verdicts. `.okstra`
+    is conventionally gitignored, so there is no version history to fall back
+    on — recovery has meant scraping the JSON back out of the last rendered
+    markdown. This snapshot is that fallback, replaced only after a render that
+    passed schema enforcement, so it is always a document that renders.
+
+    Called by the CLI entry point rather than `render_to_file`, so rendering a
+    data.json in place (a fixture, a dry run) never writes beside its input.
+    Failing to write it must never fail the render: the report is the
+    deliverable, the snapshot is a convenience.
+    """
+    snapshot = data_path.with_name(data_path.name + ".last-valid")
+    try:
+        tmp = snapshot.with_suffix(snapshot.suffix + f".tmp.{os.getpid()}")
+        tmp.write_bytes(data_path.read_bytes())
+        tmp.replace(snapshot)
+    except OSError as exc:
+        print(
+            f"render-final-report: could not write {snapshot.name} ({exc})",
+            file=sys.stderr,
+        )
+        return None
+    return snapshot

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

@@ -24,6 +24,7 @@ from .filters import (
     paragraphs,
 )
 from .models import HtmlRunMeta
+from .report_index import inject_report_index
 from .router import HtmlRenderError, resolve_html_route
 
 
@@ -133,7 +134,8 @@ def render_v2_html_view(
     # threading the index through every macro and call site.
     anchors = anchor_index(data)
     chrome = load_dictionary(lang, HTML_DICTIONARY_REL)
-    env.globals["t"] = make_jinja_global(chrome)
+    translate = make_jinja_global(chrome)
+    env.globals["t"] = translate
     env.filters["code_evidence"] = code_evidence
     env.filters["enum_label"] = lambda value, vocabulary: enum_label(value, vocabulary, chrome)
     env.filters["enum_legend"] = lambda vocabulary: enum_legend(vocabulary, chrome)
@@ -154,7 +156,10 @@ def render_v2_html_view(
         "js": response_js + "\n" + base_js,
     }
     output_path = _html_path(data_path)
-    output_path.write_text(env.get_template(route.template_name).render(**context), encoding="utf-8")
+    document = env.get_template(route.template_name).render(**context)
+    output_path.write_text(
+        inject_report_index(document, label=translate("base.contents")), encoding="utf-8"
+    )
     if context["clarificationItems"]:
         # The footer tells the reader to drop the exported file here, so the
         # directory has to exist before they go looking for it.

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

@@ -0,0 +1,75 @@
+"""Build the reader's index that heads the rendered report.
+
+The index is derived from the rendered document instead of being declared in
+each task template. A template that gains a section gets an index entry with
+it, and there is no second list to keep in step.
+
+Anchors come from the id a section already carries or from its
+``data-report-section`` slug — never from the heading text, which changes with
+the report language and would move every link with it.
+"""
+from __future__ import annotations
+
+import re
+
+# Every section of the human view opens with its own h2. A block that does not
+# is not a place the reader navigates to, so it stays out of the index.
+_SECTION_HEAD_RE = re.compile(
+    r'<section\b(?P<attrs>[^>]*)>(?P<heading_open>\s*<h2[^>]*>)(?P<title>.*?)</h2>',
+    re.DOTALL,
+)
+_MAIN_OPEN_RE = re.compile(r"<main\b[^>]*>")
+_ID_RE = re.compile(r'\bid="([^"]+)"')
+_SLUG_RE = re.compile(r'\bdata-report-section="([^"]+)"')
+_TAG_RE = re.compile(r"<[^>]+>")
+
+INDEX_TITLE_ID = "report-index-title"
+
+
+def _heading_text(title_markup: str) -> str:
+    """The heading's words without the markup a link cannot carry."""
+    return " ".join(_TAG_RE.sub("", title_markup).split())
+
+
+def inject_report_index(document: str, *, label: str) -> str:
+    """Return ``document`` with a section index at the top of ``<main>``.
+
+    Sections that lack both an id and a slug are skipped rather than given a
+    generated anchor: a link whose target moves between renders is worse than
+    an entry the reader never had.
+    """
+    opening = _MAIN_OPEN_RE.search(document)
+    if opening is None:
+        return document
+    head, body = document[: opening.end()], document[opening.end() :]
+    entries: list[tuple[str, str]] = []
+
+    def _anchor_section(match: re.Match[str]) -> str:
+        attrs = match.group("attrs")
+        existing = _ID_RE.search(attrs)
+        if existing:
+            anchor = existing.group(1)
+        else:
+            slug = _SLUG_RE.search(attrs)
+            if slug is None:
+                return match.group(0)
+            anchor = f"section-{slug.group(1)}"
+            # Last, not first: templates lead a section with the attribute the
+            # tests and the validator select it by.
+            attrs = f'{attrs} id="{anchor}"'
+        entries.append((anchor, _heading_text(match.group("title"))))
+        return f'<section{attrs}>{match.group("heading_open")}{match.group("title")}</h2>'
+
+    body = _SECTION_HEAD_RE.sub(_anchor_section, body)
+    if not entries:
+        return document
+    items = "".join(
+        f'<li><a href="#{anchor}">{text}</a></li>' for anchor, text in entries
+    )
+    index = (
+        f'<nav class="report-index" aria-labelledby="{INDEX_TITLE_ID}">'
+        f'<h2 id="{INDEX_TITLE_ID}">{label}</h2>'
+        f"<ol>{items}</ol>"
+        "</nav>"
+    )
+    return f"{head}\n{index}{body}"

package/runtime/python/okstra_ctl/worker_liveness.py

@@ -31,6 +31,8 @@ from __future__ import annotations
 import argparse
 import json
 import sys
+import time
+from collections.abc import Callable
 from dataclasses import dataclass
 from datetime import datetime, timezone
 from pathlib import Path
@@ -49,6 +51,12 @@ from okstra_ctl.worker_heartbeat import (
 )
 
 DEFAULT_LAUNCH_GRACE_SECONDS = 60
+DEFAULT_POLL_INTERVAL_SECONDS = 20.0
+DEFAULT_WAIT_TIMEOUT_SECONDS = 2400.0
+
+
+def _utc_now() -> datetime:
+    return datetime.now(timezone.utc)
 
 
 def _log_path(prompt: Path) -> Path:
@@ -167,10 +175,12 @@ def probe_launch(
 @dataclass(frozen=True)
 class ProbeTarget:
     """One pending worker resolved from team-state: which artifact answers for
-    it, where that artifact is, and when this dispatch started."""
+    it, where that artifact is, when this dispatch started, and the result file
+    whose arrival means this worker is done."""
     liveness_mode: str
     artifact: Path
     dispatched_at: datetime
+    result_path: Path | None = None
 
 
 def probe_one(target: ProbeTarget, *, now: datetime, max_idle: float,
@@ -198,6 +208,61 @@ def probe_all(
             "unhealthy": unhealthy}
 
 
+def result_ready(target: ProbeTarget) -> bool:
+    """Whether this worker's result file has landed with content in it."""
+    path = target.result_path
+    return bool(path and path.is_file() and path.stat().st_size > 0)
+
+
+def wait_for_results(
+    targets: list[ProbeTarget],
+    *,
+    max_idle: float,
+    launch_grace: float,
+    interval: float,
+    timeout: float,
+    clock: Callable[[], datetime] = _utc_now,
+    sleep: Callable[[float], None] = time.sleep,
+) -> dict:
+    """Poll until every result file lands, a worker dies, or the deadline passes.
+
+    This is the loop a lead would otherwise hand-write in Bash at each dispatch,
+    and every hand-written one has to re-derive the same two facts: what "done"
+    means (the persisted ``resultPath``, not a guessed filename) and what
+    "dead" means (`probe_all`, whose graces run from ``startedAt`` — never from
+    an artifact's mtime, which a re-dispatched worker inherits from its previous
+    attempt and reads as instantly stale).
+
+    ``outcome`` is ``completed`` / ``unhealthy`` / ``timeout``.
+    """
+    started = clock()
+    while True:
+        now = clock()
+        result = probe_all(
+            targets, now=now, max_idle=max_idle, launch_grace=launch_grace
+        )
+        pending = [
+            str(t.result_path) for t in targets if not result_ready(t)
+        ]
+        waited = (now - started).total_seconds()
+        if not pending:
+            outcome = "completed"
+        elif result["unhealthy"]:
+            outcome = "unhealthy"
+        elif waited >= timeout:
+            outcome = "timeout"
+        else:
+            sleep(interval)
+            continue
+        return {
+            **result,
+            "ok": outcome == "completed",
+            "outcome": outcome,
+            "pending": pending,
+            "waitedSeconds": int(waited),
+        }
+
+
 def _parse_utc(value: object, label: str) -> datetime:
     if not isinstance(value, str) or not value:
         raise DispatchError(f"{label} must be a UTC ISO timestamp")
@@ -262,11 +327,18 @@ def probe_target(team_state_value: str, worker_id: str) -> ProbeTarget:
     artifact_value = worker.get(field)
     if not isinstance(artifact_value, str) or not artifact_value.strip():
         raise DispatchError(f"worker {worker_id} has no {field}")
+    project_root = _project_root_for_team_state(team_state_path)
     artifact = Path(artifact_value)
     if not artifact.is_absolute():
-        artifact = _project_root_for_team_state(team_state_path) / artifact
+        artifact = project_root / artifact
     dispatched_at = _parse_utc(worker.get("startedAt"), f"worker {worker_id} startedAt")
-    return ProbeTarget(mode, artifact, dispatched_at)
+    result_value = worker.get("resultPath")
+    result_path = None
+    if isinstance(result_value, str) and result_value.strip():
+        result_path = Path(result_value)
+        if not result_path.is_absolute():
+            result_path = project_root / result_path
+    return ProbeTarget(mode, artifact, dispatched_at, result_path)
 
 
 def main(argv: list[str] | None = None) -> int:
@@ -283,6 +355,18 @@ def main(argv: list[str] | None = None) -> int:
     parser.add_argument("--launch-grace", type=float, default=DEFAULT_LAUNCH_GRACE_SECONDS,
                         help="seconds a worker may take to write its first artifact")
     parser.add_argument("--json", action="store_true", help="emit JSON (always on)")
+    parser.add_argument(
+        "--wait", action="store_true",
+        help=(
+            "poll until every worker's persisted resultPath lands (exit 0), one "
+            "worker probes unhealthy (exit 1), or --timeout passes (exit 2). "
+            "Use this instead of hand-writing a Bash poll loop."
+        ),
+    )
+    parser.add_argument("--interval", type=float, default=DEFAULT_POLL_INTERVAL_SECONDS,
+                        help="--wait poll interval in seconds")
+    parser.add_argument("--timeout", type=float, default=DEFAULT_WAIT_TIMEOUT_SECONDS,
+                        help="--wait deadline in seconds")
     args = parser.parse_args(argv)
 
     if len(args.team_state) != len(args.worker):
@@ -298,16 +382,37 @@ def main(argv: list[str] | None = None) -> int:
     except DispatchError as exc:
         parser.error(str(exc))
 
-    result = probe_all(
+    if not args.wait:
+        result = probe_all(
+            targets,
+            now=_utc_now(),
+            max_idle=args.max_idle,
+            launch_grace=args.launch_grace,
+        )
+        print(json.dumps(result, ensure_ascii=False, indent=2))
+        # Non-zero on an unhealthy worker so a poll loop can branch on the exit
+        # code without parsing the JSON.
+        return 0 if result["ok"] else 1
+
+    unwaitable = [
+        worker for target, worker in zip(targets, args.worker, strict=True)
+        if target.result_path is None
+    ]
+    if unwaitable:
+        parser.error(
+            f"--wait needs a resultPath in team-state for: {', '.join(unwaitable)}. "
+            "Waiting on a guessed filename is what --wait exists to prevent."
+        )
+
+    result = wait_for_results(
         targets,
-        now=datetime.now(timezone.utc),
         max_idle=args.max_idle,
         launch_grace=args.launch_grace,
+        interval=args.interval,
+        timeout=args.timeout,
     )
     print(json.dumps(result, ensure_ascii=False, indent=2))
-    # Non-zero on an unhealthy worker so a poll loop can branch on the exit code
-    # without parsing the JSON.
-    return 0 if result["ok"] else 1
+    return {"completed": 0, "unhealthy": 1}.get(result["outcome"], 2)
 
 
 if __name__ == "__main__":

package/runtime/python/okstra_ctl/worker_prompt_contract.py

@@ -187,10 +187,18 @@ def validate_reverify_prompt(
     *,
     task_type: str,
     forbidden_actions: str,
+    expected_model: str | None = None,
 ) -> list[str]:
-    """Require the active phase boundary in a lightweight reverify prompt."""
+    """Require the active phase boundary in a lightweight reverify prompt.
+
+    ``expected_model`` is the value this dispatch will actually run. A reverify
+    prompt's `**Model:**` header is hand-written per round, and a header naming
+    a model the runtime does not serve does not fail here — it fails as a
+    provider 400 once the worker launches, where it reads as a worker fault.
+    Pass the dispatch's model so the mismatch is caught before launch.
+    """
     normalized = text.replace("\r\n", "\n").replace("\r", "\n")
-    errors: list[str] = []
+    errors: list[str] = _validate_model_header(normalized, expected_model)
     task_values = _header_values(normalized, TASK_TYPE_HEADER)
     if task_values != [task_type]:
         errors.append(
@@ -287,23 +295,30 @@ def validate_initial_prompt_records(
     return errors
 
 
-def _validate_record_metadata(text: str, record: PromptRecord) -> list[str]:
-    errors = _validate_delivery_mode(
-        _header_values(text, PROMPT_DELIVERY_MODE_HEADER),
-        record.expected_delivery_mode,
-    )
-    if record.expected_model is None:
-        return errors
+def _validate_model_header(text: str, expected_model: str | None) -> list[str]:
+    """The `**Model:** <label>, <model>` header must name the requested model.
+
+    A caller with no resolved model passes ``None`` and the header is not
+    judged — there is nothing to compare it against.
+    """
+    if expected_model is None:
+        return []
     model = _model_value(_header_values(text, MODEL_HEADER))
     if model is None:
-        errors.append(
-            "exactly one non-empty **Model:** <label>, <model> header is required"
-        )
-    elif model != record.expected_model:
-        errors.append(
-            f"prompt model does not match requested model: {record.expected_model}"
-        )
-    return errors
+        return ["exactly one non-empty **Model:** <label>, <model> header is required"]
+    if model != expected_model:
+        return [f"prompt model does not match requested model: {expected_model}"]
+    return []
+
+
+def _validate_record_metadata(text: str, record: PromptRecord) -> list[str]:
+    return [
+        *_validate_delivery_mode(
+            _header_values(text, PROMPT_DELIVERY_MODE_HEADER),
+            record.expected_delivery_mode,
+        ),
+        *_validate_model_header(text, record.expected_model),
+    ]
 
 
 def _validate_evidence_ledger_header(

package/runtime/skills/okstra-run/SKILL.md

@@ -193,6 +193,8 @@ If an action has an unknown `command`, `key`, or `scope`, stop and report the wi
 
 Before rendering the next phase's bundle — and between worker rounds within a phase (reverify/critic/gapverify batches), after you have collected that round's results and token usage and before you dispatch the next round — reclaim the prior round's completed teammate panes so they do not accumulate, in two passes and adding `--keep report-writer-worker` to **both** whenever the report writer is still in flight. First source the count: `$HOME/.okstra/bin/okstra-trace-cleanup.sh --list --run-dir "<RUN_DIR>" [--keep report-writer-worker]` never kills and prints one `<pane_id>\t<pane_title>` line per pane it would reclaim — count those lines as `<n>`. Then run the same command **without** `--list` to perform the reclaim, and emit `PROGRESS: phase-batch-cleanup panes=<n>` with that count at the batch boundary. Call both passes after collecting results and before the next dispatch so no in-flight worker pane is caught. This `tmux kill-pane`s the harness teammate panes; `shutdown_request` alone only idles the agent and never frees the pane, so it stays part of the run-end sequence for roster/token hygiene. `<RUN_DIR>` is the current (or just-finished) run's directory; its recorded `state/lead-pane.id` scopes the lead's session and the lead pane is never killed. In a non-tmux session there are no panes and the script is a silent no-op.
 
+Before you ask the user for any approval, clarification, or decision after workers have been dispatched, run the same reclaim first: `$HOME/.okstra/bin/okstra-trace-cleanup.sh --list --run-dir "<RUN_DIR>" [--keep report-writer-worker]` to count the panes, then the same command without `--list` to close them, emit `PROGRESS: phase-gate-cleanup panes=<n>`, and `TaskStop` each completed worker. A `TaskStop` by itself idles the task but leaves the pane open — the `trace-cleanup` call is what actually closes it. This keeps a user gate from being shown while finished worker panes remain; in-flight workers and an in-flight report writer are preserved.
+
 Build the `okstra render-bundle` invocation from `outcome.renderArgs`, passing each key as `--<key>` and the value verbatim (including empty strings — they are intentional `use phase default` markers).
 
 Analysis sidetracks therefore forward wizard-owned entries such as `--analysis-target "<args.analysis-target>"` and `--evidence-inputs "<args.evidence-inputs>"` when those keys are present. These are examples of the generic mapping rule, not a separate hard-coded argument list.

package/runtime/templates/reports/html/assets/base.css

@@ -16,6 +16,13 @@ main { display: grid; gap: 1rem; padding-bottom: 3rem; }
 section { padding: 1.4rem; border: 1px solid color-mix(in srgb, CanvasText 14%, transparent); border-radius: 16px; background: color-mix(in srgb, Canvas 94%, CanvasText 6%); }
 h2 { margin-top: 0; font-size: 1.45rem; }
 h3 { margin-bottom: .35rem; }
+/* The report opens with what it holds. It scrolls away with the rest rather
+   than sticking: on a phone a pinned index of a dozen sections is the page. */
+nav.report-index { padding: 1.2rem 1.4rem; border: 1px solid color-mix(in srgb, CanvasText 14%, transparent); border-radius: 16px; background: color-mix(in srgb, Canvas 94%, CanvasText 6%); }
+nav.report-index h2 { font-size: .82rem; text-transform: uppercase; letter-spacing: .08em; color: GrayText; margin-bottom: .6rem; }
+nav.report-index ol { margin: 0; padding-left: 1.4rem; columns: 2; column-gap: 2.5rem; }
+nav.report-index li { margin: .2em 0; break-inside: avoid; }
+nav.report-index a { color: inherit; }
 /* One card per row. Fitting three across left each body about sixteen
    characters wide — a third of what reads comfortably — and turned every card
    into a narrow vertical strip. These carry paragraphs, not labels. */
@@ -92,6 +99,6 @@ button:focus-visible { outline: 2px solid Highlight; outline-offset: 2px; }
 button[data-action="export-user-response"] { background: Highlight; border-color: Highlight; color: HighlightText; font-weight: 600; }
 button[data-action="export-user-response"]:hover { background: color-mix(in srgb, Highlight 82%, CanvasText); }
 /* A seven-column table needs 42em of floor, more than a phone can give. */
-@media (max-width: 640px) { section { padding: 1rem; } .visualization { display: none; } th, td { min-width: 4.5em; } }
+@media (max-width: 640px) { section { padding: 1rem; } .visualization { display: none; } th, td { min-width: 4.5em; } nav.report-index ol { columns: 1; } }
 @media print { .skip-link, script { display: none !important; } body { color: #000; background: #fff; } section { break-inside: avoid; border-color: #bbb; } .visualization-fallback { display: table; } }
 code { font-family: ui-monospace, SFMono-Regular, Menlo, monospace; font-size: .9em; padding: .1em .3em; border-radius: 4px; background: color-mix(in srgb, CanvasText 8%, Canvas); }

package/runtime/templates/reports/html/i18n/en.json

@@ -72,6 +72,7 @@
   },
   "base": {
     "skip-to-report-content": "Skip to report content",
+    "contents": "Contents",
     "task": "Task",
     "task-key": "Task key",
     "written": "Written",

package/runtime/templates/reports/html/i18n/ko.json

@@ -72,6 +72,7 @@
   },
   "base": {
     "skip-to-report-content": "리포트 본문으로 건너뛰기",
+    "contents": "목차",
     "task": "태스크",
     "task-key": "태스크 키",
     "written": "작성",

package/runtime/templates/reports/html/macros/forms.html

@@ -32,7 +32,7 @@
 
 {% macro clarification_responses(items) -%}
 {% if items %}
-<section class="clarification-responses" aria-label="{{ t('macros.forms.questions-waiting-on-you') }}">
+<section class="clarification-responses" data-report-section="clarification-responses" aria-label="{{ t('macros.forms.questions-waiting-on-you') }}">
   <h2>{{ t('macros.forms.count-questions-waiting-on-you') | replace('{count}', items | length) }}</h2>
   <p class="clarification-lede">{{ t('macros.forms.the-code-alone-could-not-settle-these-fill-i') }} <strong>{{ t('macros.forms.export-my-answers') }}</strong> {{ t('macros.forms.at-the-foot-of-the-page') }}</p>
   {% for row in items %}

package/runtime/templates/reports/settings.template.json

@@ -38,6 +38,17 @@
     "filesystem": { "allowWrite": ["~/.gemini", "~/.codex"] }
   },
   "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "compact",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "$HOME/.okstra/bin/okstra-compact-reminder.sh"
+          }
+        ]
+      }
+    ],
     "PreToolUse": [
       {
         "matcher": "Write|Edit|MultiEdit|NotebookEdit",