okstra 0.173.0 → 0.175.1

package/runtime/python/okstra_ctl/doctor.py

@@ -36,6 +36,20 @@ class DoctorCheck:
         return asdict(self)
 
 
+def model_pool_diagnostics(
+    *,
+    host_runtime: str = "claude-code",
+    cwd: str | Path | None = None,
+) -> dict[str, object]:
+    """Diagnose the model pool without making an inference call."""
+    from .model_cli import model_diagnostics
+
+    return model_diagnostics(
+        host_runtime=host_runtime,
+        cwd=None if cwd is None else Path(cwd),
+    )
+
+
 def phase_diagnostics(
     phase: str,
     *,
@@ -236,11 +250,11 @@ def _final_verification_checks(workspace: Path) -> list[DoctorCheck]:
         _file_check("validation command", workspace / "validators" / "validate-run.py"),
         _file_check(
             "final report template",
-            workspace / "templates" / "reports" / "final-report.template.md",
+            workspace / "templates" / "reports" / "final-report-v2.template.md",
         ),
         _file_check(
             "final report schema",
-            workspace / "schemas" / "final-report-v1.0.schema.json",
+            workspace / "schemas" / "final-report-v2.0.schema.json",
         ),
     ]
 

package/runtime/python/okstra_ctl/domain/host.py

@@ -1,11 +1,39 @@
 """Host selection and session value objects."""
 from __future__ import annotations
 
-from dataclasses import dataclass
+from dataclasses import dataclass, field
 from pathlib import Path
 from typing import Literal, Mapping
 
 
+@dataclass(frozen=True)
+class CurrentSessionModelAttestation:
+    """Host-observed identity of the already running lead session."""
+
+    provider_id: str
+    observed_model: str | None
+    normalized_model_ref: str | None
+    level: Literal["exact", "channel", "unknown"]
+    source: Literal[
+        "host-session-metadata",
+        "native-api",
+        "cli-handoff",
+        "unavailable",
+    ]
+
+    @classmethod
+    def unknown(
+        cls,
+        provider_id: str,
+        source: Literal["unavailable"] = "unavailable",
+    ) -> CurrentSessionModelAttestation:
+        return cls(provider_id, None, None, "unknown", source)
+
+
+def _unavailable_current_model() -> CurrentSessionModelAttestation:
+    return CurrentSessionModelAttestation.unknown("")
+
+
 @dataclass(frozen=True)
 class HostDescriptor:
     id: str
@@ -29,6 +57,9 @@ class HostSessionContext:
     entry_mode: Literal["spawn-process", "current-session"]
     available_functions: frozenset[str]
     interaction_surface: str
+    current_model: CurrentSessionModelAttestation = field(
+        default_factory=_unavailable_current_model
+    )
 
 
 @dataclass(frozen=True)

package/runtime/python/okstra_ctl/domain/provider.py

@@ -1,19 +1,168 @@
 """Provider and model value objects shared by the registry and adapters."""
 from __future__ import annotations
 
-from dataclasses import dataclass
-from typing import TYPE_CHECKING, Mapping, Optional
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Literal, Mapping, Optional, Protocol
+
+from .role import RoleCatalogError, normalize_role, ROLE_CATALOG
+from .worker_exec import WorkerWriteCapability
 
 if TYPE_CHECKING:
     from okstra_ctl.domain.worker_exec import ExecutionStrategy
 
 
+_MISSING = object()
+
+
+@dataclass(frozen=True)
+class ServedModelAttestation:
+    """Provider-observed model identity after one execution attempt."""
+
+    observed_model: str | None
+    normalized_model_ref: str | None
+    level: Literal["exact", "channel", "unknown"]
+    source: Literal[
+        "provider-output",
+        "native-api",
+        "cli-handoff",
+        "unavailable",
+    ]
+
+    @classmethod
+    def unknown(cls) -> ServedModelAttestation:
+        return cls(None, None, "unknown", "unavailable")
+
+
+ServedModelNormalizer = Callable[[str | None], ServedModelAttestation]
+
+
+def unavailable_served_model(_raw_model: str | None) -> ServedModelAttestation:
+    return ServedModelAttestation.unknown()
+
+
 @dataclass(frozen=True)
+class HostModelBinding:
+    """Final provider value and host-native value for one selected model."""
+
+    runner: str
+    catalog_execution_value: str
+    resolved_execution_value: str
+    host_model_value: str | None
+    binding_fidelity: Literal["exact", "channel", "unsupported"]
+    worker_write_capability: WorkerWriteCapability | None
+
+
+@dataclass(frozen=True, init=False)
 class ModelSpec:
-    display: str
-    execution: str
-    pricing: Optional[tuple[float, float, float]] = None
-    in_picker: bool = False
+    """One canonical model plus provider-owned aliases and execution value."""
+
+    model_id: str
+    display_name: str
+    execution_value: str
+    aliases: tuple[str, ...]
+    version_kind: Literal["pinned", "channel"]
+    channel_family: str | None
+    supported_roles: frozenset[str] | None
+    selectable: bool
+    pricing: Optional[tuple[float, float, float]]
+
+    def __init__(
+        self,
+        model_id: str,
+        display_name: str,
+        execution_value: str | tuple[float, float, float] | None | object = _MISSING,
+        aliases: tuple[str, ...] = (),
+        version_kind: Literal["pinned", "channel"] = "pinned",
+        channel_family: str | None = None,
+        supported_roles: frozenset[str] | None = None,
+        selectable: bool = True,
+        pricing: Optional[tuple[float, float, float]] = None,
+        *,
+        in_picker: bool | None = None,
+    ) -> None:
+        """Accept the former display/execution form while adapters migrate."""
+        is_legacy = execution_value is _MISSING or not isinstance(execution_value, str)
+        if is_legacy:
+            legacy_pricing = execution_value if isinstance(execution_value, tuple) else None
+            canonical_id = display_name
+            resolved_display = model_id
+            resolved_execution = display_name
+            resolved_pricing = legacy_pricing
+        else:
+            canonical_id = model_id
+            resolved_display = display_name
+            resolved_execution = execution_value
+            resolved_pricing = pricing
+        object.__setattr__(self, "model_id", canonical_id)
+        object.__setattr__(self, "display_name", resolved_display)
+        object.__setattr__(self, "execution_value", resolved_execution)
+        object.__setattr__(self, "aliases", aliases)
+        object.__setattr__(self, "version_kind", version_kind)
+        object.__setattr__(self, "channel_family", channel_family)
+        object.__setattr__(self, "supported_roles", supported_roles)
+        object.__setattr__(self, "selectable", selectable if in_picker is None else in_picker)
+        object.__setattr__(self, "pricing", resolved_pricing)
+
+    @property
+    def display(self) -> str:
+        """Legacy display-name view."""
+        return self.display_name
+
+    @property
+    def execution(self) -> str:
+        """Legacy execution-value view."""
+        return self.execution_value
+
+    @property
+    def in_picker(self) -> bool:
+        """Legacy picker view."""
+        return self.selectable
+
+
+@dataclass(frozen=True)
+class ExecutionNormalization:
+    """One precomputed CLI execution value or its discovery-time error."""
+
+    resolved_execution_value: str | None
+    error: str = ""
+
+    def __post_init__(self) -> None:
+        if bool(self.resolved_execution_value) == bool(self.error):
+            raise ValueError(
+                "execution normalization requires exactly one value or error"
+            )
+
+
+class ExecutionNormalizer(Protocol):
+    """Provider-owned batch snapshot boundary for ambient CLI discovery."""
+
+    def snapshot(
+        self,
+        models: tuple[ModelSpec, ...],
+        roles: tuple[str, ...],
+    ) -> Mapping[tuple[str, str], ExecutionNormalization]: ...
+
+
+def snapshot_execution_normalizations(
+    models: tuple[ModelSpec, ...],
+    roles: tuple[str, ...],
+    normalize: Callable[[str, str], str],
+) -> Mapping[tuple[str, str], ExecutionNormalization]:
+    """Evaluate a pure provider normalizer for every model/role pair."""
+    outcomes: dict[tuple[str, str], ExecutionNormalization] = {}
+    for model in models:
+        for role in roles:
+            try:
+                resolved = normalize(model.execution_value, role)
+            except Exception as exc:  # provider errors become immutable facts
+                outcomes[(model.model_id, role)] = ExecutionNormalization(
+                    None,
+                    str(exc),
+                )
+            else:
+                outcomes[(model.model_id, role)] = ExecutionNormalization(resolved)
+    return outcomes
 
 
 @dataclass(frozen=True)
@@ -37,8 +186,37 @@ class ProviderSpec:
     default_models: Mapping[str, str]
     wrapper: str
     supported_roles: frozenset[str]
+    execution_capabilities: frozenset[str] = frozenset()
     lead_launch: Optional[LeadLaunchSpec] = None
     exec_strategy: Optional["ExecutionStrategy"] = None
+    execution_normalizer: Optional[ExecutionNormalizer] = None
+    served_model_normalizer: ServedModelNormalizer = unavailable_served_model
+    _legacy_role_restriction: frozenset[str] = field(
+        init=False,
+        repr=False,
+        compare=False,
+    )
+
+    def __post_init__(self) -> None:
+        legacy_roles = _normalized_legacy_roles(self.supported_roles)
+        if self.execution_capabilities:
+            capabilities = self.execution_capabilities
+            restriction = frozenset()
+        else:
+            capabilities = _legacy_execution_capabilities(legacy_roles)
+            restriction = legacy_roles
+        object.__setattr__(self, "execution_capabilities", capabilities)
+        object.__setattr__(self, "_legacy_role_restriction", restriction)
+
+    def supports_role(self, role: str) -> bool:
+        try:
+            canonical_role = normalize_role(role)
+        except RoleCatalogError:
+            return False
+        if self._legacy_role_restriction:
+            return canonical_role in self._legacy_role_restriction
+        required = ROLE_CATALOG.required_capabilities(canonical_role)
+        return required.issubset(self.execution_capabilities)
 
 
 @dataclass(frozen=True)
@@ -60,6 +238,8 @@ class LeadProviderAssignment:
 class ModelAssignment:
     display: str
     execution: str
+    model_ref: str = ""
+    version_kind: Literal["pinned", "channel"] = "pinned"
 
 
 class UnknownModelError(ValueError):
@@ -68,3 +248,29 @@ class UnknownModelError(ValueError):
 
 class UnknownProviderError(ValueError):
     """Raised when a requested provider is absent from the registry."""
+
+
+def _normalized_legacy_roles(roles: frozenset[str]) -> frozenset[str]:
+    normalized: set[str] = set()
+    for role in roles:
+        try:
+            normalized.add(normalize_role(role))
+        except RoleCatalogError:
+            continue
+    return frozenset(normalized)
+
+
+def _legacy_execution_capabilities(roles: frozenset[str]) -> frozenset[str]:
+    capabilities: set[str] = set()
+    for role in roles:
+        if role == "leader":
+            capabilities.add("lead-session")
+            continue
+        capabilities.add("worker-artifact-io")
+        if role == "analyser":
+            capabilities.add("source-readonly")
+        if role == "implementer":
+            capabilities.add("project-mutation")
+        if role in {"report-writer", "translator"}:
+            capabilities.add("extended-artifact-authoring")
+    return frozenset(capabilities)

package/runtime/python/okstra_ctl/domain/role.py

@@ -0,0 +1,125 @@
+"""Canonical role identities and the duties that execute them."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Mapping, Sequence
+
+
+class RoleCatalogError(ValueError):
+    """Raised when a role or duty is absent from the canonical catalog."""
+
+
+@dataclass(frozen=True)
+class RoleDefinition:
+    id: str
+    legacy_aliases: tuple[str, ...]
+    required_capabilities: frozenset[str]
+
+
+_READONLY_CAPABILITIES = frozenset({"worker-artifact-io", "source-readonly"})
+
+ROLE_DEFINITIONS = (
+    RoleDefinition("leader", ("lead",), frozenset({"lead-session"})),
+    RoleDefinition("analyser", (), _READONLY_CAPABILITIES),
+    RoleDefinition("critic", (), _READONLY_CAPABILITIES),
+    RoleDefinition("designer", (), _READONLY_CAPABILITIES),
+    RoleDefinition("planner", (), _READONLY_CAPABILITIES),
+    RoleDefinition(
+        "implementer",
+        ("executor",),
+        frozenset({"worker-artifact-io", "project-mutation"}),
+    ),
+    RoleDefinition("verifier", (), _READONLY_CAPABILITIES),
+    RoleDefinition(
+        "report-writer",
+        (),
+        _READONLY_CAPABILITIES | frozenset({"extended-artifact-authoring"}),
+    ),
+    RoleDefinition(
+        "translator",
+        (),
+        _READONLY_CAPABILITIES | frozenset({"extended-artifact-authoring"}),
+    ),
+)
+
+DUTY_ROLE_IDS = {
+    "lead": "leader",
+    "analysis-worker": "analyser",
+    "discovery-worker": "analyser",
+    "diagnosis-worker": "analyser",
+    "scope-critic": "critic",
+    "acceptance-critic": "critic",
+    "direction-selection-worker": "designer",
+    "planning-worker": "planner",
+    "implementation-executor": "implementer",
+    "implementation-verifier": "verifier",
+    "acceptance-verifier": "verifier",
+    "reverification-worker": "verifier",
+    "code-reviewer": "verifier",
+    "schedule-verifier": "verifier",
+    "report-writer": "report-writer",
+    "translator": "translator",
+}
+
+
+class RoleCatalog:
+    def __init__(
+        self,
+        definitions: Sequence[RoleDefinition],
+        duty_role_ids: Mapping[str, str],
+    ) -> None:
+        definition_list = tuple(definitions)
+        self._definition_count = len(definition_list)
+        self._definitions = {definition.id: definition for definition in definition_list}
+        self._aliases = {
+            alias: definition.id
+            for definition in definition_list
+            for alias in definition.legacy_aliases
+        }
+        self._duty_role_ids = dict(duty_role_ids)
+        self._validate()
+
+    def normalize(self, raw: str) -> str:
+        role = raw.strip()
+        canonical = self._aliases.get(role, role)
+        if canonical not in self._definitions:
+            raise RoleCatalogError(f"unknown role: {raw}")
+        return canonical
+
+    def required_capabilities(self, role: str) -> frozenset[str]:
+        return self._definitions[self.normalize(role)].required_capabilities
+
+    def role_for_duty(self, duty_id: str) -> str:
+        try:
+            return self._duty_role_ids[duty_id]
+        except KeyError as exc:
+            raise RoleCatalogError(f"unknown duty: {duty_id}") from exc
+
+    def _validate(self) -> None:
+        if len(self._definitions) != self._definition_count:
+            raise RoleCatalogError("duplicate canonical role")
+        if len(self._aliases) != sum(
+            len(definition.legacy_aliases) for definition in self._definitions.values()
+        ):
+            raise RoleCatalogError("duplicate legacy role alias")
+        for role in self._duty_role_ids.values():
+            self.normalize(role)
+
+
+ROLE_CATALOG = RoleCatalog(ROLE_DEFINITIONS, DUTY_ROLE_IDS)
+
+# Ids plus legacy aliases. Bundled adapters declare this set so every
+# catalog model can be assigned to every role.
+ALL_ROLE_TOKENS = frozenset(
+    token
+    for definition in ROLE_DEFINITIONS
+    for token in (definition.id, *definition.legacy_aliases)
+)
+
+
+def normalize_role(raw: str) -> str:
+    return ROLE_CATALOG.normalize(raw)
+
+
+def role_for_duty(duty_id: str) -> str:
+    return ROLE_CATALOG.role_for_duty(duty_id)

package/runtime/python/okstra_ctl/domain/wizard/interaction.py

@@ -24,6 +24,11 @@ class WizardPrompt:
     multi: bool = False
     questions: tuple["WizardPrompt", ...] = ()
 
+    @property
+    def id(self) -> str:
+        """Stable public identifier shared by static and role-instance prompts."""
+        return self.step
+
 
 @dataclass(frozen=True)
 class AnswerProtocol:
@@ -66,6 +71,14 @@ def _normalize_numbered_item(prompt: WizardPrompt, answer: str) -> str:
         number = int(candidate)
         if 1 <= number <= len(prompt.options):
             return prompt.options[number - 1].value
+        if prompt.step.startswith("role-count:"):
+            role = prompt.step.split(":", 1)[1]
+            minimum = prompt.options[0].value if prompt.options else "?"
+            maximum = prompt.options[-1].value if prompt.options else "?"
+            raise WizardAnswerError(
+                f"role {role!r} count must be in {minimum}..{maximum}: "
+                f"{candidate}"
+            )
         out_of_list = _exact_value_match(prompt, candidate)
         if out_of_list is not None:
             return out_of_list

package/runtime/python/okstra_ctl/domain/worker_exec.py

@@ -9,15 +9,26 @@ from __future__ import annotations
 
 from dataclasses import dataclass, field
 from pathlib import Path
-from typing import Protocol, runtime_checkable
+from collections.abc import Callable, Mapping
+from typing import Any, Literal, Protocol, runtime_checkable
 
 from .worker_stream import Normalise, no_events
+from ..write_policy import WriteEnforcement, WritePolicy
 
 # What ``ExecCommand.stream_format`` may hold. The value decides whether the
 # runner pipes the CLI's output through the stream formatter or forwards it
 # unchanged, so it is part of the contract rather than a display hint.
 STREAM_JSON = "stream-json"
 TEXT = "text"
+SERVED_MODEL_MISMATCH_EXIT_CODE = 78
+
+
+def no_model_observation(_event: Mapping[str, Any]) -> str | None:
+    """Truthful default for provider output that exposes no model identity."""
+    return None
+
+
+ObserveServedModel = Callable[[Mapping[str, Any]], str | None]
 
 
 @dataclass(frozen=True)
@@ -33,6 +44,8 @@ class ExecutionPolicy:
 
     auto_approve: bool
     write_scope: tuple[Path, ...]
+    write_policy: WritePolicy | None = None
+    write_enforcement: WriteEnforcement | None = None
 
 
 @dataclass(frozen=True)
@@ -53,6 +66,11 @@ class WorkerExecRequest:
     worktree_path: Path | None
     policy: ExecutionPolicy
     idle_timeout_seconds: int
+    # The id the dispatcher chose, empty when it chose none. Only a CLI that
+    # accepts a session id reads it. Handing it over means the CLI does not
+    # issue its own, so the recorded id and the session's own jsonl are
+    # guaranteed to name the same session.
+    session_id: str = ""
 
 
 @dataclass(frozen=True)
@@ -79,6 +97,20 @@ class ExecCommand:
     stream_format: str
     cwd: Path
     normalise: Normalise = field(default=no_events)
+    observe_served_model: ObserveServedModel = field(
+        default=no_model_observation
+    )
+
+
+@dataclass(frozen=True)
+class WorkerWriteCapability:
+    """Maximum write-boundary precision exposed by a worker runner."""
+
+    max_boundary_precision: Literal[
+        "exact-path",
+        "directory-boundary",
+        "none",
+    ]
 
 
 @dataclass(frozen=True)
@@ -94,6 +126,12 @@ class PolicySupport:
     can_bound_write_scope: bool
     note: str = ""
 
+    def worker_write_capability(self) -> WorkerWriteCapability:
+        precision = (
+            "directory-boundary" if self.can_bound_write_scope else "none"
+        )
+        return WorkerWriteCapability(precision)
+
 
 @runtime_checkable
 class ExecutionStrategy(Protocol):

package/runtime/python/okstra_ctl/domain/worker_role.py

@@ -9,6 +9,8 @@ from __future__ import annotations
 
 from dataclasses import dataclass
 
+from .role import RoleCatalogError, normalize_role
+
 # Implementation executor / verifier dispatches run whole build + test suites
 # that legitimately emit nothing for minutes; the 600s cap reaped them mid-suite
 # (observed: a silent jest + tsc build TERM'd at ~929s). This stays below the
@@ -16,7 +18,7 @@ from dataclasses import dataclass
 _BUILD_RUNNING_IDLE_SECONDS = 1500
 _DEFAULT_IDLE_SECONDS = 600
 
-_BUILD_RUNNING_ROLES = frozenset({"executor", "verifier"})
+_BUILD_RUNNING_ROLES = frozenset({"implementer", "verifier"})
 
 
 @dataclass(frozen=True)
@@ -26,9 +28,17 @@ class WorkerRoleSpec:
 
 
 def role_spec(role: str) -> WorkerRoleSpec:
+    canonical_role = _canonical_role_or_raw(role)
     seconds = (
         _BUILD_RUNNING_IDLE_SECONDS
-        if role in _BUILD_RUNNING_ROLES
+        if canonical_role in _BUILD_RUNNING_ROLES
         else _DEFAULT_IDLE_SECONDS
     )
-    return WorkerRoleSpec(role=role, idle_timeout_seconds=seconds)
+    return WorkerRoleSpec(role=canonical_role, idle_timeout_seconds=seconds)
+
+
+def _canonical_role_or_raw(role: str) -> str:
+    try:
+        return normalize_role(role)
+    except RoleCatalogError:
+        return role

package/runtime/python/okstra_ctl/domain/worker_stream.py

@@ -88,6 +88,30 @@ StreamEvent = Text | ToolCall | ToolResult | Denial | Result
 Normalise = Callable[[Mapping[str, Any]], tuple[StreamEvent, ...]]
 
 
+def host_event_row(
+    *,
+    event_id: str,
+    sequence: int,
+    event_type: str,
+    invocation_ref: str,
+    attempt: int,
+    payload: Mapping[str, Any],
+    timestamp: str,
+) -> dict[str, Any]:
+    """Build one orchestrator-owned host-event row without I/O."""
+    row = {
+        "schemaVersion": "1.0",
+        "eventId": event_id,
+        "sequence": sequence,
+        "timestamp": timestamp,
+        "eventType": event_type,
+        "invocationRef": invocation_ref,
+        "attempt": attempt,
+    }
+    row.update(dict(payload))
+    return row
+
+
 def no_events(event: Mapping[str, Any]) -> tuple[StreamEvent, ...]:
     """The normaliser for a CLI that emits no events at all.
 

package/runtime/python/okstra_ctl/error_log_write.py

@@ -202,6 +202,7 @@ def append_observed(
     stderr_excerpt,
     context,
     now=None,
+    identity=None,
 ):
     """Append a lead-observed error event to errors.jsonl."""
     if error_type not in ALLOWED_ERROR_TYPES:
@@ -232,6 +233,9 @@ def append_observed(
         "stderrExcerpt": truncate_stderr(stderr_excerpt),
         "context": context,
     }
+    from okstra_ctl.execution_identity import stored_identity
+
+    rec.update(stored_identity(identity))
     append_jsonl_line(out_path, rec)
     return rec
 
@@ -245,6 +249,7 @@ def dump_from_worker_sidecar(
     agent_role,
     model,
     now=None,
+    identity=None,
 ):
     """Read worker sidecar errors[] and append each to errors.jsonl with
     Lead-side metadata filled in. Returns number of records appended.
@@ -303,6 +308,10 @@ def dump_from_worker_sidecar(
             "stderrExcerpt": truncate_stderr(e.get("stderrExcerpt")),
             "context": entry_context,
         }
+        from okstra_ctl.execution_identity import stored_identity
+
+        rec.update(stored_identity(identity))
+        rec.update(stored_identity(e))
         append_jsonl_line(out_path, rec)
         count += 1
     return count