okstra 0.159.0 → 0.161.0

package/runtime/python/okstra_ctl/convergence.py

@@ -32,6 +32,7 @@ from .convergence_store import (
     write_final_state_atomic,
     write_json_atomic,
 )
+from .verdict_blocks import FindingVote, VerdictBlockError, parse_finding_votes
 
 
 _EVIDENCE_ARTIFACT = {
@@ -110,6 +111,41 @@ _EXAMPLES: dict[str, dict[str, Any]] = {
             }
         ],
     },
+    "coverage-batch": {
+        "schemaVersion": "1.0",
+        "taskKey": "example/group/task",
+        "mode": "coverage",
+        # The critic's own provider never votes on its gaps, so `provider` here
+        # is deliberately absent from `dispatches[]`.
+        "provider": "antigravity",
+        "modelExecutionValue": "gemini-3.1-pro",
+        "dispatches": [
+            {"worker": "claude-worker", "status": "completed", "durationMs": 1250},
+            {"worker": "codex-worker", "status": "completed", "durationMs": 980},
+        ],
+        "gaps": [
+            {
+                "gapId": "G-001",
+                "summary": "The rollback path has no live-data verification",
+                "category": "missing",
+                "ticketIds": ["TASK-001"],
+                "originEvidence": "No rollback query result is present",
+                "evidenceArtifacts": [_EVIDENCE_ARTIFACT],
+                "votes": {
+                    "claude-worker": {
+                        "verdict": "agree",
+                        "disagreeBasis": None,
+                        "explanation": "The plan cites no rollback verification step",
+                    },
+                    "codex-worker": {
+                        "verdict": "agree",
+                        "disagreeBasis": None,
+                        "explanation": "No rollback assertion appears in the stage map",
+                    },
+                },
+            }
+        ],
+    },
 }
 
 
@@ -131,21 +167,22 @@ def _parser() -> argparse.ArgumentParser:
         help="print a deterministic input artifact example",
         description=(
             "Print one deterministic valid example as JSON.\n\n"
-            "`groups` feeds `seed --groups` and `round-results` feeds "
-            "`apply-round --results`, but `critic-results` is the critic "
-            "worker's own result document — NOT the `apply-critic-gaps "
-            "--results` input. That input is the coverage batch the lead "
-            "assembles from those candidates plus each analyser's vote "
-            '({schemaVersion, taskKey, mode: "coverage", provider, '
-            "modelExecutionValue, dispatches[], gaps[]}); see "
-            'prompts/lead/convergence.md §"Coverage critic". Feeding this '
-            "example straight into `apply-critic-gaps` is rejected, by design."
+            "Each kind feeds one command:\n"
+            "  groups          -> seed --groups\n"
+            "  round-results   -> apply-round --results\n"
+            "  coverage-batch  -> apply-critic-gaps --results\n\n"
+            "`critic-results` feeds nothing: it is the critic worker's own "
+            "result document, NOT the `apply-critic-gaps --results` input. "
+            "Feeding it straight in is rejected, by design — that reducer takes "
+            "the coverage batch the lead assembles from those candidates plus "
+            "each analyser's vote, which is what `--kind coverage-batch` prints. "
+            'See prompts/lead/convergence.md §"Coverage critic".'
         ),
         formatter_class=argparse.RawDescriptionHelpFormatter,
     )
     example.add_argument(
         "--kind",
-        choices=("groups", "round-results", "critic-results"),
+        choices=("groups", "round-results", "critic-results", "coverage-batch"),
         required=True,
     )
 
@@ -160,6 +197,23 @@ def _parser() -> argparse.ArgumentParser:
     plan.add_argument("--work-state", type=Path, required=True)
     plan.add_argument("--plan", type=Path, required=True)
 
+    collect = subparsers.add_parser(
+        "collect-results",
+        help="read one round's worker responses into the apply-round input",
+    )
+    collect.add_argument("--plan", type=Path, required=True)
+    collect.add_argument("--mode", choices=("adversarial", "collaborative"),
+                         required=True,
+                         help="which reverify prompt this round used; the two "
+                              "carry different verdict vocabularies")
+    collect.add_argument("--result", action="append", default=[],
+                         metavar="<worker>=<path>",
+                         help="one worker's reverify result file (repeatable)")
+    collect.add_argument("--dispatch", action="append", default=[], required=True,
+                         metavar="<worker>=<status>:<durationMs>",
+                         help="terminal status per dispatched worker (repeatable)")
+    collect.add_argument("--output", type=Path, required=True)
+
     apply = subparsers.add_parser("apply-round", help="apply structured round results")
     apply.add_argument("--work-state", type=Path, required=True)
     apply.add_argument("--plan", type=Path, required=True)
@@ -348,10 +402,112 @@ def _validate(args: argparse.Namespace) -> tuple[str, Path]:
     return "valid", args.state
 
 
+def _split_pair(raw: str, label: str) -> tuple[str, str]:
+    key, separator, value = raw.partition("=")
+    if not separator or not key.strip() or not value.strip():
+        raise ConvergenceContractError(f"{label} must be <worker>=<value>, got: {raw}")
+    return key.strip(), value.strip()
+
+
+def _dispatch_rows(raw_dispatches: list[str]) -> list[dict[str, Any]]:
+    """`dispatches[]`, from what only the lead knows.
+
+    Terminal status and duration are not in the worker's response; they belong
+    to the dispatch. Deriving them from the presence of a result file would call
+    a timed-out worker `completed` whenever it managed to write something.
+    """
+    rows: list[dict[str, Any]] = []
+    for raw in raw_dispatches:
+        worker, value = _split_pair(raw, "--dispatch")
+        status, _, duration = value.partition(":")
+        if not duration.isdigit():
+            raise ConvergenceContractError(
+                f"--dispatch for `{worker}` must end in :<durationMs>, got: {value}"
+            )
+        rows.append({
+            "worker": worker, "status": status, "durationMs": int(duration)
+        })
+    return rows
+
+
+def _planned_finding_ids(plan: dict[str, Any]) -> dict[str, list[str]]:
+    dispatches = plan.get("dispatches")
+    if not isinstance(dispatches, list):
+        raise ConvergenceContractError("round plan has no `dispatches` array")
+    planned: dict[str, list[str]] = {}
+    for row in dispatches:
+        worker = row.get("worker") if isinstance(row, dict) else None
+        if not isinstance(worker, str) or not worker:
+            raise ConvergenceContractError("every round plan dispatch needs a `worker`")
+        planned[worker] = list(row.get("findingIds") or [])
+    return planned
+
+
+def _worker_votes(
+    raw_results: list[str], planned: dict[str, list[str]], adversarial: bool
+) -> dict[str, dict[str, FindingVote]]:
+    votes: dict[str, dict[str, FindingVote]] = {}
+    for raw in raw_results:
+        worker, path = _split_pair(raw, "--result")
+        if worker not in planned:
+            raise ConvergenceContractError(
+                f"`{worker}` returned a result but the round plan did not dispatch it"
+            )
+        parsed = parse_finding_votes(
+            Path(path).read_text(encoding="utf-8"), adversarial=adversarial
+        )
+        assigned = set(planned[worker])
+        missing = sorted(assigned - set(parsed))
+        if missing:
+            raise ConvergenceContractError(
+                f"`{worker}` was dispatched {len(assigned)} findings but returned "
+                f"no verdict for {missing} — an unanswered finding cannot be "
+                f"classified, and dropping it silently makes the round look complete"
+            )
+        unknown = sorted(set(parsed) - assigned)
+        if unknown:
+            raise ConvergenceContractError(
+                f"`{worker}` returned verdicts for {unknown}, which this round's "
+                f"plan did not dispatch to it"
+            )
+        votes[worker] = parsed
+    return votes
+
+
+def _collect_results(args: argparse.Namespace) -> tuple[str, Path]:
+    plan = load_json_object(args.plan)
+    planned = _planned_finding_ids(plan)
+    dispatches = _dispatch_rows(args.dispatch)
+    undispatched = sorted(set(planned) - {row["worker"] for row in dispatches})
+    if undispatched:
+        raise ConvergenceContractError(
+            f"the round plan dispatched {undispatched} but no --dispatch status "
+            f"was given for them; a planned worker with no recorded outcome is "
+            f"indistinguishable from one that was never asked"
+        )
+    votes = _worker_votes(args.result, planned, args.mode == "adversarial")
+    by_finding: dict[str, dict[str, Any]] = {}
+    for worker, parsed in votes.items():
+        for finding_id, vote in parsed.items():
+            by_finding.setdefault(finding_id, {})[worker] = {
+                "verdict": vote.verdict,
+                "disagreeBasis": vote.disagree_basis,
+                "explanation": vote.explanation,
+            }
+    write_json_atomic(args.output, {
+        "schemaVersion": "1.0",
+        "round": plan.get("round"),
+        "dispatches": dispatches,
+        "votesByFinding": by_finding,
+    })
+    return "collected", args.output
+
+
 def _execute(args: argparse.Namespace) -> tuple[str, Path]:
     operations: dict[str, Any] = {
         "seed": _seed,
         "plan-round": _plan_round,
+        "collect-results": _collect_results,
         "apply-round": _apply_round,
         "apply-critic-gaps": _apply_critic_gaps,
         "finalize": _finalize,
@@ -374,7 +530,8 @@ def main(argv: list[str] | None = None) -> int:
         return 0
     try:
         action, path = _execute(args)
-    except (ConvergenceContractError, json.JSONDecodeError, ValueError) as exc:
+    except (ConvergenceContractError, VerdictBlockError,
+            json.JSONDecodeError, ValueError) as exc:
         print(f"error: {exc}", file=sys.stderr)
         return 2
     except OSError as exc:

package/runtime/python/okstra_ctl/dispatch_core.py

@@ -10,9 +10,11 @@ from datetime import datetime, timezone
 from pathlib import Path
 from typing import Any, Mapping, Sequence
 
+from . import cmux
 from . import tmux
 from .dispatch_state import (
     BACKEND_CLI_WRAPPER,
+    BACKEND_CMUX_PANE,
     BACKEND_MIXED,
     BACKEND_TMUX_PANE,
     DispatchError,
@@ -185,11 +187,19 @@ def build_dispatch_plan(
 
 def dispatch_plan(plan: DispatchPlan, *, wait: bool = True) -> int:
     if wait:
-        if any(job.backend == BACKEND_TMUX_PANE for job in plan.jobs):
+        pane_backends = sorted(
+            {
+                job.backend
+                for job in plan.jobs
+                if job.backend in (BACKEND_TMUX_PANE, BACKEND_CMUX_PANE)
+            }
+        )
+        if pane_backends:
             raise DispatchError(
-                "wait=True dispatch does not support tmux-pane workers: "
-                "the per-job blocking loop would serialize panes instead of "
-                "running them concurrently; dispatch tmux panes with wait=False"
+                f"wait=True dispatch does not support {'/'.join(pane_backends)} "
+                "workers: the per-job blocking loop would serialize panes "
+                "instead of running them concurrently; dispatch panes with "
+                "wait=False"
             )
         _set_dispatch_mode(plan.team_state_path, _dispatch_mode(plan.jobs))
         for job in plan.jobs:
@@ -259,7 +269,9 @@ def _jobs_from_roster(
             prompt_path,
             options,
         )
-        for fact, prompt_path in zip(worker_facts, prompt_paths, strict=True)
+        for fact, prompt_path in (
+            (fact, prompt_paths[fact.worker_id]) for fact in worker_facts
+        )
     ]
 
 
@@ -327,7 +339,7 @@ def _materialize_roster_prompts(
     team_state: Mapping[str, Any],
     selected: Sequence[str],
     options: _BuildOptions,
-) -> tuple[tuple[_RosterWorkerFacts, ...], tuple[Path, ...]]:
+) -> tuple[tuple[_RosterWorkerFacts, ...], dict[str, Path]]:
     worker_facts = tuple(
         _roster_worker_facts(team_state, worker_id)
         for worker_id in selected
@@ -425,9 +437,29 @@ def _start_job(plan: DispatchPlan, job: WorkerJob) -> WorkerHandle:
         return _run_cli_wrapper(plan, job, "")
     if job.backend == BACKEND_TMUX_PANE:
         return _start_tmux_or_degrade(plan, job)
+    if job.backend == BACKEND_CMUX_PANE:
+        return _start_cmux_or_degrade(plan, job)
     raise DispatchError(f"unsupported worker backend: {job.backend}")
 
 
+def _start_cmux_or_degrade(plan: DispatchPlan, job: WorkerJob) -> WorkerHandle:
+    workspace = cmux.resolve_lead_workspace()
+    if not workspace:
+        return _run_cli_wrapper(plan, job, BACKEND_CMUX_PANE)
+    try:
+        surface_id = cmux.spawn_worker_surface(
+            workspace=workspace,
+            cwd=plan.project_root,
+            command=job.command,
+            title=f"{job.worker_id}-worker",
+        )
+    except (RuntimeError, OSError, subprocess.SubprocessError):
+        return _run_cli_wrapper(plan, job, BACKEND_CMUX_PANE)
+    return WorkerHandle(
+        job, surface_id, None, status_path_for_prompt(job.prompt_path), ""
+    )
+
+
 def _start_tmux_or_degrade(plan: DispatchPlan, job: WorkerJob) -> WorkerHandle:
     lead_pane = tmux.resolve_caller_pane()
     if not lead_pane:
@@ -559,7 +591,7 @@ def _dispatch_record(
 
 
 def _liveness_mode(backend: str) -> str:
-    if backend in (BACKEND_CLI_WRAPPER, BACKEND_TMUX_PANE):
+    if backend in (BACKEND_CLI_WRAPPER, BACKEND_TMUX_PANE, BACKEND_CMUX_PANE):
         return LIVENESS_WRAPPER_STATUS
     return LIVENESS_AUDIT_HEARTBEAT
 
@@ -613,7 +645,44 @@ def _skip_reasons(
     return {w: "skipped by worker dispatch default: worker is not supported by this dispatcher" for w in _string_list(manifest.get("recommendedWorkers")) if w not in set(selected) and w not in supported}
 
 
+_SIDEBAR_LEVELS = {
+    "worker-dispatched": "progress",
+    "worker-result-collected": "success",
+    "worker-retry-scheduled": "warning",
+    "worker-failed": "error",
+}
+
+
+def _relay_to_sidebar(plan: DispatchPlan, event_type: str, details: Mapping[str, Any]) -> None:
+    """Mirror a dispatch event onto the cmux sidebar.
+
+    A long run is mostly silence, and the sidebar is the one surface still
+    visible after the user scrolls away or switches workspaces. A failed worker
+    additionally raises a notification, because that is the event whose cost
+    grows the longer it goes unnoticed.
+    """
+    # The plan's backend, not the manifest field it was resolved from: a job
+    # that degraded to the blocking wrapper is still part of a cmux run, and
+    # that degradation is exactly what the sidebar should keep showing.
+    if plan.default_backend != BACKEND_CMUX_PANE:
+        return
+    workspace = cmux.resolve_lead_workspace()
+    worker_id = str(details.get("workerId", "") or "worker")
+    cmux.sidebar_log(
+        workspace,
+        f"{worker_id}: {event_type.removeprefix('worker-')}",
+        level=_SIDEBAR_LEVELS.get(event_type, "info"),
+    )
+    if event_type == "worker-failed":
+        cmux.sidebar_notify(
+            workspace,
+            title=f"okstra — {_require_string(plan.manifest, 'taskType')}",
+            body=f"{worker_id} failed: {details.get('reason', 'no reason recorded')}",
+        )
+
+
 def _append_event(plan: DispatchPlan, event_type: str, details: Mapping[str, Any]) -> None:
+    _relay_to_sidebar(plan, event_type, details)
     append_lead_event(
         plan.lead_events_path,
         LeadEvent(

package/runtime/python/okstra_ctl/dispatch_state.py

@@ -24,6 +24,7 @@ from datetime import datetime, timezone
 from pathlib import Path
 from typing import Any, Callable, Mapping, Sequence
 
+from . import cmux
 from .worker_prompt_contract import (
     PromptRecord,
     validate_initial_prompt_records,
@@ -32,8 +33,23 @@ from .worker_prompt_contract import (
 
 BACKEND_CLI_WRAPPER = "cli-wrapper"
 BACKEND_TMUX_PANE = "tmux-pane"
+BACKEND_CMUX_PANE = "cmux-pane"
 BACKEND_MIXED = "mixed"
 
+
+def detect_terminal_backend() -> str:
+    """Which pane backend this run gets. Called once, by prepare.
+
+    cmux wins wherever it is usable: the only thing a tmux session buys a lead
+    is Claude Code's AgentTeam, and the cmux path deliberately does not use it.
+    Everywhere else this answers `tmux-pane`, which is what every run got before
+    cmux existed. The answer is written to the run manifest and read back from
+    there — consumers must not re-detect, or two phases of one run can disagree.
+    """
+    if cmux.cmux_available():
+        return BACKEND_CMUX_PANE
+    return BACKEND_TMUX_PANE
+
 # `livenessMode` picks which artifact answers "is this worker still alive": the
 # in-process worker's audit sidecar heartbeat, or the CLI wrapper's status
 # sidecar. Both dispatchers write it and `worker_liveness` reads it, so the