okstra 0.154.2 → 0.156.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_finalize.py

@@ -110,11 +110,30 @@ def task_id(manifest: Mapping[str, Any]) -> str:
     raise FinalizeError(f"cannot infer task id from taskKey: {task_key}")
 
 
-def run_seq(manifest: Mapping[str, Any]) -> str:
+def _category_seq(manifest: Mapping[str, Any], category: str) -> str:
     seqs = manifest.get("runSequencesByCategory")
     if not isinstance(seqs, Mapping):
         raise FinalizeError("run manifest has no runSequencesByCategory object")
-    return require_string(seqs, "manifests")
+    return require_string(seqs, category)
+
+
+def run_seq(manifest: Mapping[str, Any]) -> str:
+    """How many times this task type has run — what a lead event records."""
+    return _category_seq(manifest, "manifests")
+
+
+def report_seq(manifest: Mapping[str, Any]) -> str:
+    """The `reports` sequence — the one the final-report filename carries.
+
+    Categories advance independently (`paths.compute_run_paths`), so a run whose
+    predecessor produced no report reuses the free report slot and `run_seq`
+    outruns this one. This value reaches `render-report-views --seq`, which
+    stamps it into the HTML `runMeta` naming the exported
+    `user-response-<task-type>-<seq>.md`; `user_response.write_sidecar` derives
+    that same name from the report path, so anything but `reports` makes the two
+    answer paths write different files for one report.
+    """
+    return _category_seq(manifest, "reports")
 
 
 def task_manifest_path(project_root: Path, manifest: Mapping[str, Any]) -> Path:
@@ -204,7 +223,7 @@ class FinalizeContext:
             task_key=require_string(manifest, "taskKey"),
             task_type=require_string(manifest, "taskType"),
             task_group=task_group(manifest),
-            seq=run_seq(manifest),
+            seq=report_seq(manifest),
             final_status_path=resolve_optional_path(
                 project_root, manifest.get("finalStatusPath")
             ),

package/runtime/python/okstra_ctl/stage_map.py

@@ -218,6 +218,103 @@ def parse_stage_map_file(path: Path) -> list[StageMapStage]:
     return parse_stage_map_text(text, source_plan_path=str(resolved))
 
 
+def _require_data_positive_int(
+    value: Any, field: str, row_number: int, source_plan_path: str,
+) -> int:
+    if not isinstance(value, int) or isinstance(value, bool) or value < 1:
+        raise StageMapError(
+            "stage_map",
+            f"structured Stage Map row {row_number} has invalid {field} {value!r}",
+            source_plan_path,
+        )
+    return value
+
+
+def _require_data_text(
+    value: Any, field: str, row_number: int, source_plan_path: str,
+) -> str:
+    if not isinstance(value, str) or not value.strip():
+        raise StageMapError(
+            "stage_map",
+            f"structured Stage Map row {row_number} has invalid {field} {value!r}",
+            source_plan_path,
+        )
+    return value
+
+
+def _parse_data_stage_map_row(
+    value: Any, row_number: int, source_plan_path: str,
+) -> StageMapStage:
+    if not isinstance(value, dict):
+        raise StageMapError(
+            "stage_map",
+            f"structured Stage Map row {row_number} must be an object",
+            source_plan_path,
+        )
+    stage_number = _require_data_positive_int(
+        value.get("stage"), "stage", row_number, source_plan_path
+    )
+    step_count = _require_data_positive_int(
+        value.get("stepCount"), "stepCount", row_number, source_plan_path
+    )
+    title = _require_data_text(
+        value.get("title"), "title", row_number, source_plan_path
+    )
+    depends_on = _require_data_text(
+        value.get("dependsOn"), "dependsOn", row_number, source_plan_path
+    )
+    exit_summary = _require_data_text(
+        value.get("exitContractSummary"),
+        "exitContractSummary",
+        row_number,
+        source_plan_path,
+    )
+    return StageMapStage(
+        stage_number,
+        title,
+        _parse_depends_on(depends_on.strip(), row_number, source_plan_path),
+        step_count,
+        exit_summary,
+    )
+
+
+def _parse_schema_v2_stage_map(
+    data: dict[str, Any], source_plan_path: str,
+) -> list[StageMapStage]:
+    planning = data.get("implementationPlanning")
+    stage_map = planning.get("stageMap") if isinstance(planning, dict) else None
+    if not isinstance(stage_map, list) or not stage_map:
+        raise StageMapError(
+            "stage_map",
+            "structured report requires a non-empty implementationPlanning.stageMap",
+            source_plan_path,
+        )
+    stages = [
+        _parse_data_stage_map_row(value, row_number, source_plan_path)
+        for row_number, value in enumerate(stage_map, start=1)
+    ]
+    _validate_stage_numbers(stages, source_plan_path)
+    return stages
+
+
+def _parse_stage_map_source(markdown_path: Path) -> list[StageMapStage]:
+    resolved = markdown_path.resolve()
+    data_path = resolved.with_suffix(".data.json")
+    if not data_path.exists():
+        return parse_stage_map_file(resolved)
+    try:
+        data = json.loads(data_path.read_text(encoding="utf-8"))
+    except (OSError, UnicodeError, json.JSONDecodeError) as exc:
+        raise StageMapError("stage_map", str(exc), str(data_path)) from exc
+    if not isinstance(data, dict):
+        raise StageMapError(
+            "stage_map", "structured report must be an object", str(data_path)
+        )
+    if data.get("schemaVersion") != "2.0":
+        return parse_stage_map_file(resolved)
+    return _parse_schema_v2_stage_map(data, str(data_path))
+
+
 def stage_map_records(stages: Iterable[StageMapStage]) -> list[dict[str, Any]]:
     return [
         {
@@ -256,7 +353,7 @@ def load_task_stage_map(
     return StageMapSnapshot(
         "ready",
         str(resolved),
-        stage_map_records(parse_stage_map_file(resolved)),
+        stage_map_records(_parse_stage_map_source(resolved)),
     )
 
 

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/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",