okstra 0.167.0 → 0.169.0

package/runtime/python/okstra_ctl/doctor.py

@@ -2,6 +2,7 @@
 from __future__ import annotations
 
 import json
+import os
 import subprocess
 from dataclasses import asdict, dataclass
 from pathlib import Path
@@ -10,6 +11,7 @@ from typing import Iterable
 from okstra_project import ResolverError, project_json_path, resolve_project_root
 
 from . import improvement_lenses, worktree_registry
+from .models import provider_wrappers
 from .workers import resolve_profile_workers
 from .worktree import is_git_work_tree, main_worktree_path
 
@@ -39,6 +41,7 @@ def phase_diagnostics(
     cwd: str | Path,
     workspace_root: str | Path,
     home: str | Path,
+    host_runtime: str,
 ) -> dict[str, object]:
     """Return JSON-serialisable readiness checks for one lifecycle phase."""
     if phase not in SUPPORTED_PHASES:
@@ -56,7 +59,11 @@ def phase_diagnostics(
     checks.append(_profile_check(workspace, phase))
 
     if project_root is not None:
-        checks.extend(_phase_checks(phase, project_root, workspace, home_path))
+        checks.extend(
+            _phase_checks(
+                phase, project_root, workspace, home_path, host_runtime
+            )
+        )
 
     return {
         "ok": all(check.ok for check in checks),
@@ -89,9 +96,68 @@ def _project_checks(cwd: Path) -> tuple[Path | None, list[DoctorCheck]]:
                 f"{project_json} not found — run okstra setup in this project first",
             )
         )
+    architecture = _architecture_declaration_check(project_root)
+    if architecture is not None:
+        checks.append(architecture)
     return project_root, checks
 
 
+_LAYOUT_SCAN_SKIP = frozenset(
+    {".git", ".okstra", "node_modules", "dist", "build", "coverage", "__pycache__"}
+)
+
+
+def _ports_and_adapters_marker(project_root: Path) -> str:
+    """The first ports-and-adapters layout signal found, or "".
+
+    Only the two signals the pack states mechanically (`architectures/hexagonal.md`
+    Stage 3 row): a `ports/` directory beside a `domain/` one, and a `*.port.*`
+    file. The other two — NestJS hex split, abstract classes at a boundary — are
+    worker judgment and are deliberately not guessed at here.
+    """
+    for current, dirnames, filenames in os.walk(project_root):
+        dirnames[:] = [d for d in dirnames if d not in _LAYOUT_SCAN_SKIP]
+        here = set(dirnames)
+        if "ports" in here and "domain" in here:
+            return str(Path(current).relative_to(project_root) / "ports")
+        for name in filenames:
+            if ".port." in name:
+                return str(Path(current).relative_to(project_root) / name)
+    return ""
+
+
+def _architecture_declaration_check(project_root: Path) -> DoctorCheck | None:
+    """Report placement rules running advisory because no style was declared.
+
+    The routed coding-preflight pack promotes its placement rules from advisory to
+    blocking only under `architecture.style` in `project.json`
+    (`architectures/hexagonal.md` Severity). With the key absent they stay advisory,
+    a verifier records `architecture-style: none`, and the run reads as fully gated
+    — the downgrade is invisible to both lead and user. A project that genuinely is
+    not ports-and-adapters silences this by declaring `none`, which is why the raw
+    value is read here: `resolve_architecture()` maps absent and `none` alike.
+    """
+    try:
+        payload = json.loads(project_json_path(project_root).read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return None
+    architecture = payload.get("architecture") if isinstance(payload, dict) else None
+    declared = architecture.get("style") if isinstance(architecture, dict) else None
+    if isinstance(declared, str) and declared.strip():
+        return _ok("architecture style", f"declared: {declared.strip()}")
+    marker = _ports_and_adapters_marker(project_root)
+    if not marker:
+        return None
+    return _ok(
+        "architecture style",
+        f"not declared, but the layout shows a ports-and-adapters signal ({marker}) "
+        "— placement rules run advisory, so a misplaced domain object or a concrete "
+        "adapter injection is recorded rather than blocking. Declare "
+        '`architecture: {"style": "hexagonal"}` in .okstra/project.json to gate '
+        'them, or `"none"` to say the layout is not ports-and-adapters.',
+    )
+
+
 def _profile_check(workspace: Path, phase: str) -> DoctorCheck:
     profile = _profile_path(workspace, phase)
     if profile.is_file():
@@ -104,15 +170,18 @@ def _phase_checks(
     project_root: Path,
     workspace: Path,
     home: Path,
+    host_runtime: str,
 ) -> list[DoctorCheck]:
     if phase == "implementation":
-        return _implementation_checks(project_root, workspace, home)
+        return _implementation_checks(
+            project_root, workspace, home, host_runtime
+        )
     if phase == "final-verification":
         return _final_verification_checks(workspace)
     if phase == "release-handoff":
         return _release_handoff_checks(project_root)
     if phase == "improvement-discovery":
-        return _improvement_discovery_checks(workspace, home)
+        return _improvement_discovery_checks(workspace, home, host_runtime)
     return []
 
 
@@ -120,12 +189,13 @@ def _implementation_checks(
     project_root: Path,
     workspace: Path,
     home: Path,
+    host_runtime: str,
 ) -> list[DoctorCheck]:
     return [
         _git_work_tree_check(project_root),
         _git_worktree_support_check(project_root),
         _approved_plan_validator_check(),
-        _worker_agents_check(home, workspace, "implementation"),
+        *_worker_dispatch_checks(home, workspace, "implementation", host_runtime),
     ]
 
 
@@ -153,10 +223,15 @@ def _release_handoff_checks(project_root: Path) -> list[DoctorCheck]:
     ]
 
 
-def _improvement_discovery_checks(workspace: Path, home: Path) -> list[DoctorCheck]:
+def _improvement_discovery_checks(
+    workspace: Path,
+    home: Path,
+    host_runtime: str,
+) -> list[DoctorCheck]:
     return [
-        _worker_agents_check(home, workspace, "improvement-discovery"),
-        _file_check("antigravity worker agent", _agent_path(home, "antigravity")),
+        *_worker_dispatch_checks(
+            home, workspace, "improvement-discovery", host_runtime
+        ),
         _lens_whitelist_check(),
     ]
 
@@ -182,18 +257,77 @@ def _approved_plan_validator_check() -> DoctorCheck:
     return _ok("approved-plan validator", "okstra plan-validate is available")
 
 
-def _worker_agents_check(home: Path, workspace: Path, phase: str) -> DoctorCheck:
+def _worker_dispatch_checks(
+    home: Path,
+    workspace: Path,
+    phase: str,
+    host_runtime: str,
+) -> list[DoctorCheck]:
     workers = resolve_profile_workers(_profile_path(workspace, phase))
     if not workers:
-        return _ok("worker agents", "no worker agents required")
-    missing = [worker for worker in workers if not _agent_path(home, worker).is_file()]
-    roster = ",".join(workers)
-    if missing:
-        return _fail(
-            "worker agents",
-            f"missing {','.join(missing)}; profile requires {roster}",
+        return [_ok("worker dispatch", "no workers required")]
+    if not host_runtime:
+        return [_fail("worker dispatch", "resolved host runtime is required")]
+
+    native_provider = {
+        "claude-code": "claude",
+        "codex": "codex",
+        "antigravity": "antigravity",
+        "grok": "grok",
+        "kimi": "kimi",
+    }.get(host_runtime)
+    providers = ["claude" if worker == "report-writer" else worker for worker in workers]
+    checks: list[DoctorCheck] = []
+
+    if host_runtime == "claude-code":
+        native_agents = []
+        if "claude" in workers:
+            native_agents.append("claude")
+        if "report-writer" in workers:
+            native_agents.append("report-writer")
+        for agent in native_agents:
+            checks.append(
+                _file_check(
+                    f"host-native agent: {agent}", _agent_path(home, agent)
+                )
+            )
+
+    cli_providers = sorted({
+        provider for provider in providers if provider != native_provider
+    })
+    if cli_providers:
+        dispatch_module = _first_file(
+            workspace / "scripts" / "okstra_ctl" / "worker_dispatch.py",
+            workspace / "python" / "okstra_ctl" / "worker_dispatch.py",
         )
-    return _ok("worker agents", f"installed: {roster}")
+        checks.append(
+            _file_check("worker-dispatch entrypoint", dispatch_module)
+        )
+        wrappers = provider_wrappers("analyser")
+        for provider in cli_providers:
+            wrapper = wrappers.get(provider, "")
+            if not wrapper:
+                checks.append(
+                    _fail(
+                        f"CLI provider strategy: {provider}",
+                        "provider registry has no analyser wrapper",
+                    )
+                )
+                continue
+            path = _first_file(
+                workspace / "scripts" / wrapper,
+                workspace / "bin" / wrapper,
+            )
+            checks.append(_file_check(f"CLI provider strategy: {provider}", path))
+    if not checks:
+        checks.append(
+            _ok("worker dispatch", f"native host owns roster on {host_runtime}")
+        )
+    return checks
+
+
+def _first_file(*paths: Path) -> Path:
+    return next((path for path in paths if path.is_file()), paths[0])
 
 
 def _worktree_registry_check() -> DoctorCheck:

package/runtime/python/okstra_ctl/entrypoints/hosts.py

@@ -9,6 +9,14 @@ from contextlib import contextmanager
 from dataclasses import asdict
 from pathlib import Path
 
+from ..agent_invocation import (
+    AgentInvocationError,
+    AgentModelAssignment,
+    agent_model_assignment_from_payload,
+    verify_agent_invocation,
+)
+from ..dispatch_state import DispatchError, record_verified_agent_dispatch
+
 from ..application.start_run import start_run
 from ..application.resume_run import resume_run
 from ..domain.host import (
@@ -24,6 +32,7 @@ from ..domain.host import (
     ProviderUnavailable,
 )
 from ..registry.host_registry import HostAdapterRegistry, default_host_registry
+from ..models import lead_launch_argv, lead_launch_spec
 
 
 _ENTRYPOINT_ERRORS = (
@@ -33,6 +42,7 @@ _ENTRYPOINT_ERRORS = (
     HostUnavailable,
     ProviderNotRegistered,
     ProviderUnavailable,
+    DispatchError,
     ValueError,
 )
 
@@ -252,9 +262,24 @@ def _launch_plan_payload(
         available_functions=frozenset(),
         interaction_surface="terminal",
     )
-    project_root, request_argv = _launch_request(args, adapter.descriptor.id)
+    project_root, request_argv, dispatch_authority = _launch_request(
+        args, adapter.descriptor.id
+    )
     request = LeadStartRequest(project_root, "", request_argv)
     plan = start_run(request, context, adapter)
+    if dispatch_authority is not None:
+        run_manifest_path, metadata_path, _assignment = dispatch_authority
+        record_verified_agent_dispatch(
+            project_root=project_root,
+            run_manifest_path=run_manifest_path,
+            metadata_path=metadata_path,
+            enforcement_mode=(
+                "core-pre-dispatch"
+                if plan.mode == "spawn-process"
+                else "host-native-spec-link-gate"
+            ),
+            allow_native_core=plan.mode == "spawn-process",
+        )
     return {"ok": True, "_project_root": str(project_root), **asdict(plan)}
 
 
@@ -283,9 +308,13 @@ def _resume_plan_payload(
 def _launch_request(
     args: argparse.Namespace,
     canonical_host_id: str,
-) -> tuple[Path, tuple[str, ...]]:
+) -> tuple[
+    Path,
+    tuple[str, ...],
+    tuple[Path, Path, AgentModelAssignment] | None,
+]:
     if not args.prepared_launch_json:
-        return Path(args.project_root), ()
+        return Path(args.project_root), (), None
     try:
         prepared = json.loads(args.prepared_launch_json)
     except json.JSONDecodeError as exc:
@@ -295,14 +324,63 @@ def _launch_request(
     if prepared.get("leadRuntime") != canonical_host_id:
         raise ValueError("prepared launch runtime does not match selected host")
     project_root = prepared.get("projectRoot")
-    request_argv = prepared.get("launchRequestArgv")
     if not isinstance(project_root, str) or not project_root:
         raise ValueError("prepared launch is missing projectRoot")
-    if not isinstance(request_argv, list) or not all(
-        isinstance(arg, str) for arg in request_argv
-    ):
-        raise ValueError("prepared launch is missing launchRequestArgv")
-    return Path(project_root), tuple(request_argv)
+    root = Path(project_root)
+    run_manifest_value = prepared.get("runManifestPath")
+    metadata_value = prepared.get("leadPromptMetadataPath")
+    if not isinstance(run_manifest_value, str) or not run_manifest_value:
+        raise ValueError("prepared launch is missing runManifestPath")
+    if not isinstance(metadata_value, str) or not metadata_value:
+        raise ValueError("prepared launch is missing leadPromptMetadataPath")
+    run_manifest_path = Path(run_manifest_value)
+    metadata_path = Path(metadata_value)
+    try:
+        manifest = json.loads(run_manifest_path.read_text(encoding="utf-8"))
+        resources = manifest["resources"]
+        assignment = agent_model_assignment_from_payload(
+            manifest["invocationAssignments"]["lead"]
+        )
+        prompt_path = root / resources["leadExecutionPromptPath"]
+        canonical_metadata = root / resources["leadPromptMetadataPath"]
+        metadata = json.loads(canonical_metadata.read_text(encoding="utf-8"))
+        if metadata["prompt"]["path"] != resources["leadExecutionPromptPath"]:
+            raise KeyError("lead prompt resource does not match metadata")
+    except (OSError, json.JSONDecodeError, KeyError, TypeError, AgentInvocationError) as exc:
+        raise ValueError("lead invocation authority is incomplete") from exc
+    if metadata_path.resolve(strict=False) != canonical_metadata.resolve(strict=False):
+        raise ValueError("prepared lead metadata does not match run manifest")
+    if prepared.get("leadProvider") != assignment.provider:
+        raise ValueError("prepared lead provider does not match run manifest")
+    if prepared.get("leadModelExecutionValue") != assignment.model_execution_value:
+        raise ValueError("prepared lead model does not match run manifest")
+    errors = verify_agent_invocation(
+        metadata_path,
+        project_root=root,
+        expected_run_manifest_path=run_manifest_path,
+        expected_assignment=assignment,
+        expected_worker_id="lead",
+        expected_assignment_ref="lead",
+        expected_audience="lead",
+    )
+    if errors:
+        raise ValueError("lead invocation verification failed: " + "; ".join(errors))
+    session_id = prepared.get("leadSessionId")
+    if not isinstance(session_id, str):
+        raise ValueError("prepared launch is missing leadSessionId")
+    argv = lead_launch_argv(
+        assignment.provider,
+        model=assignment.model_execution_value,
+        session_id=session_id,
+        prompt=prompt_path.read_text(encoding="utf-8"),
+    )
+    launch = lead_launch_spec(assignment.provider)
+    prefix_size = 1 + len(launch.sandbox_waiver)
+    return (
+        root,
+        tuple(argv[prefix_size:]),
+        (run_manifest_path, canonical_metadata, assignment),
+    )
 
 
 def _write_null_launch_plan(payload: dict[str, object]) -> None: