okstra 0.173.0 → 0.174.0

package/runtime/validators/validate-run.py

@@ -43,14 +43,16 @@ from okstra_project.dirs import tasks_root as _okstra_tasks_root  # noqa: E402
 from okstra_project.resolver import resolve_architecture  # noqa: E402
 
 from okstra_ctl.conformance import (  # noqa: E402
-    CAPABILITY_WHITELIST,
     detect_surfaces,
     evaluate_conformance,
     manifest_required_surfaces,
+    normalize_conformance_script as _normalize_conformance_script,
+    parse_conformance_tests as _parse_conformance_tests,
     qa_result_from_dict,
     validate_conformance_manifest,
 )
 from okstra_ctl.paths import RunRef  # noqa: E402
+from okstra_ctl.report_contract import CURRENT_REPORT_SCHEMA_VERSION  # noqa: E402
 from okstra_ctl.domain.host import HostNotRegistered  # noqa: E402
 from okstra_ctl.registry.host_registry import default_host_registry  # noqa: E402
 from okstra_ctl.build_tools import (  # noqa: E402
@@ -141,7 +143,7 @@ from okstra_ctl.convergence_provenance import (  # noqa: E402
 
 TERMINAL_STATUSES = {"completed", "timeout", "error", "not-run"}
 ATTEMPTED_STATUSES = {"completed", "timeout", "error"}
-WORKER_DISPATCH_MODES = {"cli-wrapper", "mixed", "tmux-pane"}
+WORKER_DISPATCH_MODES = {"cli-wrapper", "mixed"}
 _AGENT_DISPATCH_DIGEST_KEYS = (
     "catalogDigest",
     "assignmentDigest",
@@ -1682,35 +1684,6 @@ def _approved_plan_stage_entry(
     }
 
 
-_CONFORMANCE_TESTS_RE = re.compile(
-    r"^(?P<script>\S+)\s+\(requires=\[(?P<requires>[^\]]+)\]\)$"
-)
-
-
-def _normalize_conformance_script(script: str) -> str:
-    prefix = "<task_root>/"
-    return script[len(prefix):] if script.startswith(prefix) else script
-
-
-def _parse_conformance_tests(value: object) -> tuple[str, frozenset[str]] | None:
-    """Parse `<script> (requires=[cap,...])` from a stage declaration."""
-    if not isinstance(value, str):
-        return None
-    match = _CONFORMANCE_TESTS_RE.fullmatch(value.strip())
-    if match is None:
-        return None
-    script = _normalize_conformance_script(match.group("script"))
-    capabilities = [part.strip() for part in match.group("requires").split(",")]
-    if (
-        not script
-        or any(not capability for capability in capabilities)
-        or len(set(capabilities)) != len(capabilities)
-        or any(capability not in CAPABILITY_WHITELIST for capability in capabilities)
-    ):
-        return None
-    return script, frozenset(capabilities)
-
-
 def _approved_plan_conformance_manifest(
     approved_plan_path: Path,
     task_root: Path,
@@ -2355,7 +2328,7 @@ def _validate_selfmock(report_path: Path, failures: list[str]) -> None:
     read the flat `self-mock.json`.
 
     Only the implementation template renders the §5.7.3 diff summary
-    (`templates/reports/final-report.template.md:589`); a final-verification report
+    (`templates/reports/final-report-v2.template.md:589`); a final-verification report
     quotes the diff as a blockquote instead, so this gate is vacuous there by
     design — self-mock is enforced at the implementation stage, and
     final-verification is a read-only re-verify that adds no test files.
@@ -2717,65 +2690,6 @@ def validate_team_state_usage(team_state: dict, failures: list[str]) -> None:
                 )
 
 
-PLANNING_REQUIRED_SECTIONS = (
-    "Option Candidates",
-    "Trade-off",
-    "Recommended Option",
-    "Stage Map",
-    "Stepwise Execution Order",
-    "Dependency",
-    "Validation Checklist",
-    "Rollback",
-    "Requirement Coverage",
-    "Plan Body Verification",
-    "Cross-Project Dependencies",
-    "Decision Drafts",
-)
-
-# §5.7 implementation deliverables — substring scan against report body.
-IMPLEMENTATION_REQUIRED_SECTIONS = (
-    "Approved Plan Reference",
-    "Commit List",
-    "Diff Summary",
-    "Out-of-plan Edits",
-    "Stage Sidecar Evidence",
-    "Validation Evidence",
-    "Verifier Results",
-    "Rollback Verification",
-    "Manual User Test (Draft)",
-    "Routing Recommendation",
-)
-
-# §5.8 final-verification deliverables — substring scan against report body.
-FINAL_VERIFICATION_REQUIRED_SECTIONS = (
-    "Source Implementation Report",
-    "Acceptance Blockers",
-    "Residual Risk",
-    "Validation Evidence",
-    "Read-only Command Log",
-    "Conditional Acceptance Conditions",
-    "Manual User Test Results",
-    "Routing Recommendation",
-    "Could-Not-Verify Roll-up",
-)
-
-# Allowed Verdict Token vocabulary, by task-type. `release-handoff` is
-# author-tagged but reads its entry gate from final-verification's report
-# and renders `not-applicable` itself.
-FINAL_VERIFICATION_VERDICT_TOKENS = (
-    "accepted",
-    "conditional-accept",
-    "blocked",
-)
-
-# `## 7. Final Verdict` Verdict Token cell — captures the value between
-# backticks on the `Verdict Token` row. Tolerant to extra column whitespace
-# and to leading bold/italic markers in the label cell.
-_FINAL_VERDICT_TOKEN_RE = re.compile(
-    r"^\|[ \t]*\*{0,2}Verdict Token\*{0,2}[ \t]*\|[ \t]*`(?P<value>[^`\n]*)`",
-    re.MULTILINE,
-)
-
 # Verdict Card Verdict Token row (top-of-report at-a-glance). Same shape
 # as `_FINAL_VERDICT_TOKEN_RE` but matched against the first occurrence in
 # the Verdict Card block, scoped to the body between `## Verdict Card`
@@ -2786,23 +2700,6 @@ _VERDICT_CARD_BLOCK_RE = re.compile(
     re.DOTALL | re.MULTILINE,
 )
 
-# `## 7. Final Verdict` block scope — used to scope the Verdict Token
-# regex so that we don't accidentally match a Verdict Token row that
-# lives in the Verdict Card or anywhere else.
-_FINAL_VERDICT_BLOCK_RE = re.compile(
-    r"^##[ \t]+7\.[ \t]+Final Verdict" + _HEADING_TAIL
-    + r"\n(?P<body>.*?)(?=^##[ \t]|\Z)",
-    re.DOTALL | re.MULTILINE,
-)
-
-# `## 5.6 Release Handoff Deliverables` and `## 5.6.6 Merge Conflict
-# Probe` are required when task-type == release-handoff. The probe sub-
-# section was retro-added to the template; old runs that predate it ship
-# without it, but new runs must include it.
-_MERGE_CONFLICT_PROBE_HEADING_RE = re.compile(
-    r"^###[ \t]+5\.6\.6[ \t]+Merge Conflict Probe\b", re.MULTILINE
-)
-
 PLAN_VERIFY_GATE_VALUES = (
     "passed",
     "passed-with-dissent",
@@ -2810,207 +2707,10 @@ PLAN_VERIFY_GATE_VALUES = (
     "aborted-non-result",
 )
 
-# `Gate result:` line in §5.5.9 of the final report — captures the value
-# token that follows. Tolerates arbitrary markdown formatting between the
-# label and the value (backticks for inline code, double-asterisks for
-# bold, colons, hyphens, whitespace). The captured value is then
-# validated against `PLAN_VERIFY_GATE_VALUES` below so typo'd or unknown
-# values surface as their own failure rather than silently no-matching.
-_GATE_RESULT_RE = re.compile(
-    r"Gate result[^A-Za-z\n]+(?P<value>[a-z][a-z\-]+)",
-    re.IGNORECASE,
-)
-
-# §5.5.9 Plan Body Verification section body — scopes the gate-result search
-# so an earlier prose mention of "Gate result" elsewhere in the report cannot
-# hijack the authoritative value. Matched from the `Plan Body Verification`
-# heading to the next heading (or end-of-file).
-_PLAN_BODY_VERIFICATION_BLOCK_RE = re.compile(
-    r"^#{2,}[ \t][^\n]*\bPlan Body Verification\b[^\n]*\n"
-    r"(?P<body>.*?)(?=^#{2,}[ \t]|\Z)",
-    re.DOTALL | re.MULTILINE,
-)
-
-# Frontmatter approval flag — `approved: true|false` line inside the
-# leading `---` YAML block. Mirrors `APPROVED_FRONTMATTER_PATTERN` in
-# scripts/okstra_ctl/run.py.
-_APPROVED_FRONTMATTER_RE = re.compile(
-    r"^approved:[ \t]+(true|false)[ \t]*$",
-    re.IGNORECASE | re.MULTILINE,
-)
 # Tolerate a leading UTF-8 BOM and/or blank lines before the opening `---`
 # so a hand-edited or differently-rendered report does not silently bypass
 # the approved-frontmatter gate (the `.match` would otherwise return None).
 _FRONTMATTER_BLOCK_RE = re.compile(r"\A\ufeff?\s*---\n(.*?)\n---\n", re.DOTALL)
-_REQUIREMENT_COVERAGE_HEADING_RE = re.compile(
-    r"^###[ \t]+(?:5\.5\.8[ \t]+)?Requirement Coverage\b",
-    re.IGNORECASE | re.MULTILINE,
-)
-_NEXT_THIRD_LEVEL_HEADING_RE = re.compile(r"^###[ \t]+", re.MULTILINE)
-
-
-def _extract_final_verdict_token(content: str) -> str | None:
-    """Return the `Verdict Token` cell value from the `## 7. Final Verdict`
-    block, or None when the row is absent. Scoped to §7 so the Verdict
-    Card row (which has the same shape) does not shadow the authoritative
-    value.
-    """
-    block = _FINAL_VERDICT_BLOCK_RE.search(content)
-    if block is None:
-        return None
-    match = _FINAL_VERDICT_TOKEN_RE.search(block.group("body"))
-    if match is None:
-        return None
-    return match.group("value")
-
-
-# 렌더러는 ID 정의 셀(`<a id="r-001"></a>R-001`)에도 스크롤 앵커를 넣는다.
-# 셀 정규화 때 그 빈 앵커를 벗겨야 ID 컬럼이 bare 토큰으로 읽힌다
-# (clarification_items._CELL_ANCHOR_RE 와 동형).
-_CELL_ANCHOR_RE = re.compile(r'<a id="[^"]*"></a>')
-
-
-def _split_markdown_row(line: str) -> list[str]:
-    return [
-        _CELL_ANCHOR_RE.sub("", cell).strip().strip("`").strip()
-        for cell in _split_pipe_row(line)
-    ]
-
-
-def _append_requirement_coverage_failures(
-    content: str,
-    gate_value: str,
-    failures: list[str],
-) -> None:
-    """Validate implementation-planning §5.5.8 requirement coverage.
-
-    The table is intentionally lightweight: it cannot prove semantic truth, but
-    it makes requirement-to-plan mapping explicit and blocks publishable plans
-    that admit uncovered requirements.
-    """
-    heading = _REQUIREMENT_COVERAGE_HEADING_RE.search(content)
-    if heading is None:
-        failures.append(
-            "implementation-planning report is missing `Requirement Coverage` "
-            "section — every task-brief requirement must map to option/stage/step."
-        )
-        return
-
-    rest = content[heading.end():]
-    next_heading = _NEXT_THIRD_LEVEL_HEADING_RE.search(rest)
-    section = rest[: next_heading.start()] if next_heading else rest
-    lines = section.splitlines()
-
-    header_idx = -1
-    headers: list[str] = []
-    for idx, line in enumerate(lines):
-        if not line.lstrip().startswith("|"):
-            continue
-        cells = [c.lower() for c in _split_markdown_row(line)]
-        if "id" in cells and "requirement" in cells and "status" in cells:
-            header_idx = idx
-            headers = cells
-            break
-    if header_idx < 0:
-        failures.append(
-            "implementation-planning Requirement Coverage section has no table "
-            "with `ID`, `Requirement`, and `Status` columns."
-        )
-        return
-
-    id_col = headers.index("id")
-    status_col = headers.index("status")
-    rows: list[tuple[str, str]] = []
-    body_started = False
-    for line in lines[header_idx + 1:]:
-        if not line.lstrip().startswith("|"):
-            if body_started:
-                break
-            continue
-        if _is_markdown_separator(line):
-            body_started = True
-            continue
-        if not body_started:
-            continue
-        cells = _split_markdown_row(line)
-        if max(id_col, status_col) >= len(cells):
-            failures.append(
-                "implementation-planning Requirement Coverage table has a "
-                f"malformed row: `{line.strip()}`"
-            )
-            continue
-        rows.append((cells[id_col], cells[status_col].lower()))
-
-    if not rows:
-        failures.append(
-            "implementation-planning Requirement Coverage table has no data rows."
-        )
-        return
-
-    for row_id, status in rows:
-        # `status` is already lower-cased at parse time, so the blocker form
-        # arrives as `blocked c-001`; match lower-case here even though the
-        # canonical authored form (and the remedy message) is `blocked C-NNN`.
-        if not re.fullmatch(
-            r"covered|gap|blocked c-\d{3,}|"
-            r"documented-deviation — refs: (?:c-\d{3,}|d-\d{4,})"
-            r"(?:, (?:c-\d{3,}|d-\d{4,}))*; approval: "
-            r"(?:accepted|blocked c-\d{3,})",
-            status,
-        ):
-            failures.append(
-                "implementation-planning Requirement Coverage row "
-                f"`{row_id}` has invalid Status `{status}`; expected "
-                "`covered`, `gap`, `blocked C-NNN`, or a rendered "
-                "`documented-deviation` disposition."
-            )
-
-    if gate_value in ("passed", "passed-with-dissent"):
-        uncovered = [
-            f"{row_id} ({status})"
-            for row_id, status in rows
-            if status != "covered"
-            and not status.endswith("; approval: accepted")
-        ]
-        if uncovered:
-            failures.append(
-                "implementation-planning Gate result is publishable but "
-                "Requirement Coverage has uncovered row(s): "
-                + ", ".join(uncovered)
-            )
-def _extract_verdict_card_token(content: str) -> str | None:
-    """Return the `Verdict Token` cell from the Verdict Card block."""
-    block = _VERDICT_CARD_BLOCK_RE.search(content)
-    if block is None:
-        return None
-    match = _FINAL_VERDICT_TOKEN_RE.search(block.group("body"))
-    if match is None:
-        return None
-    return match.group("value")
-
-
-def _validate_verdict_card_consistency(content: str, failures: list[str]) -> None:
-    """Verdict Card is a non-authoritative index of §7. If both blocks
-    carry a Verdict Token row, the values MUST byte-match (modulo case
-    and surrounding whitespace) — divergence is a contract violation per
-    `report-writer` SKILL.md "Authoring Contract".
-    """
-    card_value = _extract_verdict_card_token(content)
-    final_value = _extract_final_verdict_token(content)
-    if card_value is None or final_value is None:
-        # Missing-Card and missing-§7 are surfaced by other checks; this
-        # function only enforces the consistency contract between the two.
-        return
-    if card_value.strip().lower() != final_value.strip().lower():
-        failures.append(
-            "Verdict Card `Verdict Token` value "
-            f"`{card_value}` does not match `## 7. Final Verdict` value "
-            f"`{final_value}` — the Card is a non-authoritative index and "
-            "MUST byte-match §7. Either fix the Card or update §7; do not "
-            "ship divergent values."
-        )
-
-
 def _validate_verdict_card_fields(data: dict, failures: list[str]) -> None:
     """`verdictCard.direction` must byte-match its authoritative home in §7.
 
@@ -3337,9 +3037,8 @@ def validate_final_report_data(
     The data.json is the source-of-truth that the renderer reads to
     produce the markdown. If schema validation passes here, the rendered
     markdown is guaranteed to contain every section / row the contract
-    requires (the template loops over the data). The downstream
-    substring checks in ``validate_phase_boundary`` are kept as a safety
-    net but are expected to be redundant.
+    requires (the template loops over the data), so the schema is the
+    only place the deliverable contract is enforced.
 
     Missing data.json is reported as a single failure rather than a
     cascade of substring failures — that points the writer at the right
@@ -7394,7 +7093,7 @@ def _validate_unverified_critic_gaps_recorded(data: dict, failures: list[str]) -
 
 
 # Allowed `fixability` values, mirroring the schema enum
-# (schemas/final-report-v1.0.schema.json planItems[].verdicts[].fixability).
+# (schemas/final-report-v2.0.schema.json planItems[].verdicts[].fixability).
 _FIXABILITY_VALUES = frozenset({"planner-fixable", "needs-user-input"})
 
 
@@ -8015,14 +7714,13 @@ def _load_stage_validator():
 def _append_stage_data_failures(data: Mapping[str, Any], failures: list[str]) -> None:
     """Run the stage relationship checks that schema v2 cannot express.
 
-    `_append_stage_structure_failures` scans rendered Markdown and sits after
-    the v2 early return in `validate_phase_boundary`, so for a v2 report the
-    depends-on DAG, parallel-stage file safety, RED→GREEN ordering, and the
-    TDD-exemption vocabulary had nothing enforcing them. The same validator
-    owns both modes so the rule vocabulary stays defined once.
+    The depends-on DAG, parallel-stage file safety, RED→GREEN ordering, and
+    the TDD-exemption vocabulary are relationships between stages, which a
+    JSON Schema cannot state. They are enforced here, against the data.json,
+    by the same validator that owns the rule vocabulary.
     """
-    if (data or {}).get("schemaVersion") != "2.0":
-        return  # v1 reports are covered by the Markdown scan.
+    if (data or {}).get("schemaVersion") != CURRENT_REPORT_SCHEMA_VERSION:
+        return  # Schema validation already rejected an unknown version.
     planning = (data or {}).get("implementationPlanning")
     if not isinstance(planning, Mapping):
         return  # Schema validation already reported the missing block.
@@ -8037,157 +7735,6 @@ def _append_stage_data_failures(data: Mapping[str, Any], failures: list[str]) ->
         )
 
 
-def _append_stage_structure_failures(content: str, failures: list[str]) -> None:
-    """Enforce the Stage Map structural contract at the implementation-planning
-    boundary. Without this, a plan missing `## 5.5 Stage Map` passes the
-    planning gate, gets approved, and only fails later at the `implementation`
-    entry (validators/validate-implementation-plan-stages.py via
-    prepare_task_bundle). Running the same validator here moves the failure to
-    produce-time."""
-    mod = _load_stage_validator()
-    if mod is None:  # pragma: no cover — repo/runtime always ship the file
-        failures.append(f"cannot load Stage Map validator at {_STAGE_VALIDATOR_PATH}")
-        return
-    for e in mod.collect_validation_errors(content):
-        failures.append(
-            f"implementation-planning Stage Map structure invalid "
-            f"[{e.code} stage={e.stage}]: {e.message}"
-        )
-
-
-def validate_phase_boundary(
-    task_type: str,
-    report_path: Path,
-    failures: list[str],
-    *,
-    report_data: Mapping[str, Any] | None = None,
-) -> None:
-    """Phase-specific contract checks.
-
-    For `implementation-planning` runs, the final report must contain the
-    required deliverable sections; absence indicates a planning run that
-    skipped its core outputs (or an implementation run that ran under the
-    wrong task type).
-
-    Additionally enforces the Plan Body Verification gate (§5.5.9):
-    - gate ∈ {passed, passed-with-dissent} → top-level Approval checkbox
-      MUST be present.
-    - gate ∈ {blocked-by-disagreement, aborted-non-result} → checkbox
-      MUST be absent (lead converted findings into Clarification rows
-      instead of opening the gate).
-    """
-    if (report_data or {}).get("schemaVersion") == "2.0":
-        return
-    if not report_path.exists():
-        return
-    content = report_path.read_text()
-
-    # Verdict Card vs §7. Final Verdict Verdict Token consistency. The Card
-    # is a non-authoritative index; divergence is a contract violation.
-    _validate_verdict_card_consistency(content, failures)
-
-    if task_type == "implementation":
-        for needle in IMPLEMENTATION_REQUIRED_SECTIONS:
-            if needle not in content:
-                failures.append(
-                    "implementation report is missing required §5.7 "
-                    f"deliverable section: `{needle}`"
-                )
-
-    if task_type == "final-verification":
-        for needle in FINAL_VERIFICATION_REQUIRED_SECTIONS:
-            if needle not in content:
-                failures.append(
-                    "final-verification report is missing required §5.8 "
-                    f"deliverable section: `{needle}`"
-                )
-        token_value = _extract_final_verdict_token(content)
-        if token_value is None:
-            failures.append(
-                "final-verification report `## 7. Final Verdict` table is "
-                "missing the `Verdict Token` row — required by the release-"
-                "handoff entry gate."
-            )
-        elif token_value.strip().lower() not in FINAL_VERIFICATION_VERDICT_TOKENS:
-            failures.append(
-                "final-verification report `Verdict Token` value "
-                f"`{token_value}` is not one of "
-                f"{', '.join(FINAL_VERIFICATION_VERDICT_TOKENS)}."
-            )
-
-    if task_type == "release-handoff":
-        if _MERGE_CONFLICT_PROBE_HEADING_RE.search(content) is None:
-            failures.append(
-                "release-handoff report is missing `### 5.6.6 Merge Conflict "
-                "Probe` sub-section — required by the release-handoff profile "
-                "(self-review 6, merge-conflict probe audit). When the run is "
-                "`local checkout` / `skip`, record the single line `- Not run "
-                "(user picked local checkout or skip).` under the heading."
-            )
-
-    if task_type != "implementation-planning":
-        return
-    for needle in PLANNING_REQUIRED_SECTIONS:
-        if needle not in content:
-            failures.append(
-                "implementation-planning report is missing required section: "
-                f"`{needle}`"
-            )
-
-    # Scope the gate-result search to the §5.5.9 Plan Body Verification block
-    # so an earlier prose mention of "Gate result" cannot hijack the value.
-    pbv_block = _PLAN_BODY_VERIFICATION_BLOCK_RE.search(content)
-    gate_match = (
-        _GATE_RESULT_RE.search(pbv_block.group("body")) if pbv_block else None
-    )
-    if gate_match is None:
-        # The `Plan Body Verification` heading check above already covers
-        # the wholly-missing case; a heading present without a `Gate result`
-        # line is its own contract violation.
-        if "Plan Body Verification" in content:
-            failures.append(
-                "implementation-planning report has `Plan Body Verification` "
-                "section but no `Gate result:` line — required by §5.5.9."
-            )
-        return
-    gate_value = gate_match.group("value").strip().lower()
-    if gate_value not in PLAN_VERIFY_GATE_VALUES:
-        failures.append(
-            "implementation-planning report `Gate result` value "
-            f"`{gate_value}` is not one of "
-            f"{', '.join(PLAN_VERIFY_GATE_VALUES)}."
-        )
-        return
-    fm_block = _FRONTMATTER_BLOCK_RE.match(content)
-    fm_match = (
-        _APPROVED_FRONTMATTER_RE.search(fm_block.group(1)) if fm_block else None
-    )
-    if gate_value in ("passed", "passed-with-dissent") and fm_match is None:
-        failures.append(
-            "implementation-planning report Gate result is "
-            f"`{gate_value}` but the frontmatter `approved:` field is missing — "
-            "render `approved: false` so the user (or `--approve`) can flip it."
-        )
-    if (
-        gate_value in ("blocked-by-disagreement", "aborted-non-result")
-        and fm_match is not None
-        and fm_match.group(1).lower() == "true"
-    ):
-        failures.append(
-            "implementation-planning report Gate result is "
-            f"`{gate_value}` but the frontmatter has `approved: true` — gate "
-            "must NOT publish a pre-approved plan when verification did not pass."
-        )
-
-    _append_requirement_coverage_failures(content, gate_value, failures)
-
-    # Only a publishable plan (gate passed) can be flipped to `approved: true`
-    # and reach the `implementation` entry, so the Stage Map structure is
-    # enforced only here — a blocked/aborted plan may legitimately be incomplete.
-    if gate_value in ("passed", "passed-with-dissent"):
-        _append_stage_structure_failures(content, failures)
-
-
 def _brief_path_from_manifest(task_manifest: dict, project_root: Path) -> Path:
     """This run's brief, or a non-existent path when the manifest names none.
 
@@ -9190,12 +8737,6 @@ def main() -> int:
     )
     validate_team_state_usage(team_state, failures)
 
-    validate_phase_boundary(
-        task_type,
-        report_path,
-        failures,
-        report_data=validation_data,
-    )
     _validate_phase_boundary_error_log(
         report_path.parent.parent,
         task_type,

package/runtime/validators/validate_session_conformance.py

@@ -50,7 +50,7 @@ from okstra_ctl.registry.host_registry import default_host_registry  # noqa: E40
 from okstra_ctl.wrapper_status import read_wrapper_status  # noqa: E402
 
 _DISPATCHED_STATUSES = {"completed", "timeout", "error", "in-progress"}
-_WORKER_DISPATCH_MODES = {"cli-wrapper", "mixed", "tmux-pane"}
+_WORKER_DISPATCH_MODES = {"cli-wrapper", "mixed"}
 _ATTEMPTED_STATUSES = {"completed", "timeout", "error"}
 _LIVENESS_AUDIT_HEARTBEAT = "audit-heartbeat"
 _LIVENESS_WRAPPER_STATUS = "wrapper-status"

package/src/cli-registry.mjs

@@ -288,6 +288,13 @@ export const COMMAND_REGISTRY = [
     category: "introspection",
     summary: ["Look up registered worktree for a task-key"],
   },
+  {
+    name: "worktree-status",
+    module: "./commands/execute/worktree-status.mjs",
+    export: "run",
+    category: "introspection",
+    summary: ["Clean-worktree check that ignores okstra's own scaffolding"],
+  },
   {
     name: "plan-validate",
     module: "./commands/execute/plan-validate.mjs",
@@ -351,7 +358,7 @@ export const COMMAND_REGISTRY = [
     module: "./commands/execute/team.mjs",
     export: "run",
     category: "introspection",
-    summary: ["Dispatch and await tmux-pane workers for external leads"],
+    summary: ["Dispatch and await pane-backed workers for external leads"],
   },
   {
     name: "wizard",

package/src/commands/execute/team.mjs

@@ -1,7 +1,7 @@
 import { runPythonModule } from "../../lib/python-helper.mjs";
 import { resolvePaths } from "../../lib/paths.mjs";
 
-const USAGE = `okstra team — dispatch and await tmux-pane workers for external leads
+const USAGE = `okstra team — dispatch and await pane-backed workers for external leads
 
 Usage:
   okstra team dispatch --project-root <dir> --run-manifest <path> \
@@ -14,8 +14,8 @@ Usage:
     [--dry-run] [--json]
 
 This command is for leadRuntime=external bundles. It dispatches okstra-owned
-worker panes through tmux when possible and degrades to CLI wrappers when tmux is
-unavailable to the lead harness.
+worker surfaces through cmux when the lead is inside it, and runs CLI wrapper
+subprocesses everywhere else.
 
   --workspace-root and --okstra-bin are owned by this command.
 `;