engineering-platform 2.2.0__py3-none-any.whl

engineering_platform/provider_context.py

@@ -0,0 +1,136 @@
+"""Bounded, role-specific provider context for Engineering Platform work.
+
+The execution host remains the authority for lifecycle and deterministic
+admission.  This module only decides whether a *provider action* is meaningful
+and projects the already-authoritative prompt into a role-appropriate input.
+It never stores prompt text or command output.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import StrEnum
+import re
+
+from .provider_context_scope import POLICY_ID
+
+
+class ProviderRole(StrEnum):
+    SPECIALIST_REVIEW = "SPECIALIST_REVIEW"
+    IMPLEMENTATION = "IMPLEMENTATION"
+    QUALITY_REVIEW = "QUALITY_REVIEW"
+    REPAIR = "REPAIR"
+    FINALIZATION = "FINALIZATION"
+
+
+@dataclass(frozen=True)
+class ProviderNeedDecision:
+    required: bool
+    reason: str
+
+
+@dataclass(frozen=True)
+class ContextProjection:
+    role: ProviderRole
+    text: str
+    source_item_count: int
+    omitted_low_priority_count: int
+    budget_version: str = POLICY_ID
+
+    @property
+    def telemetry(self) -> dict[str, int]:
+        return {
+            "context_source_item_count": self.source_item_count,
+            "context_omitted_low_priority_count": self.omitted_low_priority_count,
+            "context_projected_bytes": len(self.text.encode("utf-8")),
+        }
+
+
+_ROLE_BUDGETS = {
+    ProviderRole.SPECIALIST_REVIEW: 18_000,
+    ProviderRole.IMPLEMENTATION: 60_000,
+    ProviderRole.QUALITY_REVIEW: 22_000,
+    ProviderRole.REPAIR: 18_000,
+    ProviderRole.FINALIZATION: 18_000,
+}
+_MANDATORY_HEADINGS = re.compile(
+    r"\b(?:objective|doel|acceptance|acceptatie|constraint|beperking|"
+    r"safety|veilig|authority|autoriteit|validation|validatie|required|"
+    r"verplicht|non-negotiable|niet-onderhandelbaar|scope|niet wijzigen|do not)\b",
+    re.IGNORECASE,
+)
+_HEADING = re.compile(r"^#{1,6}\s+(.+?)\s*$")
+
+
+def provider_need_for_phase(phase: str, *, passive_observation: bool = False) -> ProviderNeedDecision:
+    """Make provider need explicit; passive/deterministic phases never need one."""
+    if passive_observation:
+        return ProviderNeedDecision(False, "passive observation is deterministic")
+    if phase in {"EXECUTE_AGENT", "LOCAL_REPOSITORY_VALIDATION"}:
+        return ProviderNeedDecision(True, "bounded implementation work requires reasoning")
+    if phase == "QUALITY_CONTROL_AGENT":
+        return ProviderNeedDecision(True, "autonomous quality review requires reasoning")
+    if phase == "REPAIR_AGENT":
+        return ProviderNeedDecision(True, "scoped repair requires reasoning")
+    if phase in {"FINALIZE_AGENT", "RECONCILE_AGENT"}:
+        return ProviderNeedDecision(True, "bounded finalization work requires reasoning")
+    return ProviderNeedDecision(False, "deterministic lifecycle transition")
+
+
+def role_for_phase(phase: str, *, repair: bool = False, quality: bool = False) -> ProviderRole:
+    if repair or phase == "REPAIR_AGENT":
+        return ProviderRole.REPAIR
+    if quality or phase == "QUALITY_CONTROL_AGENT":
+        return ProviderRole.QUALITY_REVIEW
+    if phase in {"FINALIZE_AGENT", "RECONCILE_AGENT"}:
+        return ProviderRole.FINALIZATION
+    return ProviderRole.IMPLEMENTATION
+
+
+def project_context(role: ProviderRole, objective: str) -> ContextProjection:
+    """Keep all mandatory sections while omitting lower-priority prompt history.
+
+    Prompts without recognisable Markdown sections are deliberately retained in
+    full: safety beats an unproven token reduction.  Initial implementation
+    also receives the complete prompt once; downstream roles receive the
+    mandatory contract rather than replaying the complete transcript.
+    """
+    if role == ProviderRole.IMPLEMENTATION:
+        return ContextProjection(role, objective, 1, 0)
+    sections = _markdown_sections(objective)
+    selected = [section for heading, section in sections if heading == "preamble" or _MANDATORY_HEADINGS.search(heading)]
+    if not selected:
+        return ContextProjection(role, objective, 1, 0)
+    budget = _ROLE_BUDGETS[role]
+    included: list[str] = []
+    used = 0
+    for section in selected:
+        size = len(section.encode("utf-8"))
+        # Mandatory material is never silently truncated.  A single oversized
+        # mandatory section is kept whole and may exceed the nominal budget.
+        if included and used + size > budget:
+            continue
+        included.append(section)
+        used += size
+    text = "\n\n".join(included)
+    return ContextProjection(role, text, len(sections), max(0, len(sections) - len(included)))
+
+
+def _markdown_sections(value: str) -> list[tuple[str, str]]:
+    lines = value.splitlines()
+    starts: list[tuple[int, str]] = []
+    for index, line in enumerate(lines):
+        match = _HEADING.match(line)
+        if match:
+            starts.append((index, match.group(1)))
+    if not starts:
+        return []
+    result: list[tuple[str, str]] = []
+    if starts[0][0]:
+        preamble = "\n".join(lines[:starts[0][0]]).strip()
+        if preamble:
+            result.append(("preamble", preamble))
+    for ordinal, (start, heading) in enumerate(starts):
+        end = starts[ordinal + 1][0] if ordinal + 1 < len(starts) else len(lines)
+        result.append((heading, "\n".join(lines[start:end]).strip()))
+    return result

engineering_platform/provider_context_benchmark.py

@@ -0,0 +1,41 @@
+"""Deterministic structural benchmark for provider-context reduction.
+
+This is deliberately a shape benchmark: it makes no production token or cost
+claim and never invokes a provider.
+"""
+
+from __future__ import annotations
+
+from .provider_context import ProviderRole, project_context
+
+
+def benchmark_shape(objective: str) -> dict[str, dict[str, int]]:
+    """Return comparable byte/call proxies for representative role scenarios."""
+    full = len(objective.encode("utf-8"))
+    return {
+        "deterministic_preflight_blocker": {
+            "provider_calls": 0,
+            "context_bytes": 0,
+            "repeated_reads": 0,
+            "injected_output_bytes": 0,
+        },
+        "implementation": {
+            "provider_calls": 1,
+            "context_bytes": project_context(ProviderRole.IMPLEMENTATION, objective).telemetry["context_projected_bytes"],
+            "repeated_reads": 0,
+            "injected_output_bytes": 0,
+        },
+        "repair": {
+            "provider_calls": 1,
+            "context_bytes": project_context(ProviderRole.REPAIR, objective).telemetry["context_projected_bytes"],
+            "repeated_reads": 0,
+            "injected_output_bytes": 0,
+        },
+        "passive_merge_wait": {
+            "provider_calls": 0,
+            "context_bytes": 0,
+            "repeated_reads": 0,
+            "injected_output_bytes": 0,
+        },
+        "baseline_full_replay_bytes": {"context_bytes": full * 2},
+    }

engineering_platform/provider_context_scope.py

@@ -0,0 +1,90 @@
+"""Provider-neutral, current-delta-first execution context policy."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import StrEnum
+import re
+
+
+POLICY_ID = "provider-context-v1"
+MAX_HISTORICAL_COMMITS = 10
+MAX_HISTORICAL_PULL_REQUESTS = 10
+MAX_HISTORICAL_CONTEXT_BYTES = 65_536
+
+
+class ContextScope(StrEnum):
+    NORMAL = "NORMAL"
+    RETRY_REPAIR = "RETRY_REPAIR"
+    INVESTIGATION = "INVESTIGATION"
+
+
+class ContextEscalationReason(StrEnum):
+    REGRESSION_ORIGIN_UNKNOWN = "REGRESSION_ORIGIN_UNKNOWN"
+    MERGE_ANCESTRY_REQUIRED = "MERGE_ANCESTRY_REQUIRED"
+    DIRECT_LINEAGE_REQUIRED = "DIRECT_LINEAGE_REQUIRED"
+    CONTRACT_HISTORY_REQUIRED = "CONTRACT_HISTORY_REQUIRED"
+    BLAME_REQUIRED = "BLAME_REQUIRED"
+    OPERATOR_REQUESTED_AUDIT = "OPERATOR_REQUESTED_AUDIT"
+    OTHER_BOUNDED_INVESTIGATION = "OTHER_BOUNDED_INVESTIGATION"
+
+
+class HistoryBoundaryKind(StrEnum):
+    COMMITS_TOUCHING_PATH = "COMMITS_TOUCHING_PATH"
+    DIRECT_ANCESTRY = "DIRECT_ANCESTRY"
+    DIRECT_PREDECESSOR = "DIRECT_PREDECESSOR"
+    REFERENCED_PULL_REQUESTS = "REFERENCED_PULL_REQUESTS"
+
+
+@dataclass(frozen=True)
+class ContextEscalationRequest:
+    """One bounded, invocation-local admission to historical evidence."""
+
+    reason: ContextEscalationReason
+    boundary_kind: HistoryBoundaryKind
+    boundary: str
+    limit: int
+    diagnostic: str
+
+    def validate(self) -> "ContextEscalationRequest":
+        if not self.boundary.strip() or len(self.boundary) > 240:
+            raise ValueError("A non-empty bounded history boundary is required.")
+        if not self.diagnostic.strip() or len(self.diagnostic) > 240:
+            raise ValueError("A bounded evidence-gap diagnostic is required.")
+        maximum = (
+            MAX_HISTORICAL_PULL_REQUESTS
+            if self.boundary_kind == HistoryBoundaryKind.REFERENCED_PULL_REQUESTS
+            else MAX_HISTORICAL_COMMITS
+        )
+        if not 1 <= self.limit <= maximum:
+            raise ValueError(f"History limit must be between 1 and {maximum}.")
+        return self
+
+
+def initial_context_scope(*, phase: str, repair_iterations: int = 0, objective: str = "") -> ContextScope:
+    """Choose scope from lifecycle evidence, never producer identity."""
+    if phase == "REPAIR_AGENT" or repair_iterations > 0:
+        return ContextScope.RETRY_REPAIR
+    # An explicit audit/history task is itself the bounded objective.  This is
+    # intentionally narrow; ordinary mentions of history do not broaden scope.
+    if re.search(r"\b(?:historical\s+(?:audit|investigation)|(?:audit|investigate)\s+(?:history|historical))\b", objective, re.I):
+        return ContextScope.INVESTIGATION
+    return ContextScope.NORMAL
+
+
+def provider_instruction(scope: ContextScope) -> str:
+    """Return the short operational contract injected into every provider turn."""
+    direct_lineage = (
+        "Direct predecessor run, terminal diagnostic, failed controls, and its direct delta are admitted; do not load older ancestors."
+        if scope == ContextScope.RETRY_REPAIR
+        else "No predecessor lineage is admitted unless the lifecycle supplies it."
+    )
+    return (
+        f"Provider Context Scope: {scope.value}; Policy: {POLICY_ID}. "
+        "Start with the supplied objective, current branch/worktree/status, merge-base delta against canonical base, current source, relevant tests and configuration. "
+        "Do not enumerate historical pull requests or broad git history for orientation. "
+        f"{direct_lineage} "
+        "If current evidence has a concrete gap, before a historical query run "
+        "`engineering-platform-context-escalate REASON BOUNDARY_KIND BOUNDARY LIMIT --diagnostic 'evidence gap'`; "
+        "use only its admitted boundary (maximum 10 commits or 10 PRs) and continue."
+    )

engineering_platform/provider_interruption.py

@@ -0,0 +1,168 @@
+"""Recovery of provider-proven interrupted transactions after host exit."""
+
+from __future__ import annotations
+
+from dataclasses import replace
+import json
+import logging
+from pathlib import Path
+import sqlite3
+
+from .agent_state import StateError, StateStore, TransactionState
+from .execution_lease import release_terminal_lease
+from .execution_timing import reconcile_interrupted_phases
+from .live_status import write_live_status
+from .storage import open_storage
+from .provider_recovery import create_recovery_available, load_recovery_state
+
+
+INTERRUPTION_CLASSIFICATION = "provider_turn_interrupted"
+TERMINAL_DIAGNOSTIC = (
+    "Provider turn interrupted before returning the required structured AgentResult."
+)
+LOGGER = logging.getLogger(__name__)
+
+
+def _latest_interrupted_invocation(
+    root: Path, run_id: str, *, central_database: Path | None = None,
+) -> tuple[str, str] | None:
+    """Return only durable, allow-listed provider interruption evidence.
+
+    Some providers terminate after streaming an interrupted child command but
+    before emitting their final JSONL ``turn_aborted`` event. That remains a
+    proven interruption only when usage is unavailable and a child span was
+    interrupted under the same provider boundary.
+    """
+    try:
+        connection = open_storage(root) if central_database is None else sqlite3.connect(central_database.resolve(), isolation_level=None)
+        try:
+            row = connection.execute(
+                "SELECT invocation_id,churn,usage_authority FROM provider_invocations WHERE run_id=? "
+                "ORDER BY ordinal DESC LIMIT 1",
+                (run_id,),
+            ).fetchone()
+        finally:
+            connection.close()
+    except Exception:
+        return None
+    if row is None:
+        return None
+    invocation_id = str(row[0]) if isinstance(row[0], str) else None
+    if invocation_id is None:
+        return None
+    try:
+        churn = json.loads(row[1])
+    except (TypeError, json.JSONDecodeError):
+        churn = {}
+    if isinstance(churn, dict) and churn.get("interruption_classification") == INTERRUPTION_CLASSIFICATION:
+        return invocation_id, "provider_reported_abort"
+    if row[2] != "UNAVAILABLE":
+        return None
+    try:
+        connection = open_storage(root) if central_database is None else sqlite3.connect(central_database.resolve(), isolation_level=None)
+        try:
+            interrupted_child = connection.execute(
+                "SELECT 1 FROM execution_phase_spans AS child "
+                "JOIN execution_phase_spans AS provider ON provider.phase_id=child.parent_phase_id "
+                "WHERE child.run_id=? AND child.outcome='INTERRUPTED' "
+                "AND provider.phase_name='PROVIDER_EXECUTION' LIMIT 1",
+                (run_id,),
+            ).fetchone()
+        finally:
+            connection.close()
+    except Exception:
+        return None
+    if interrupted_child is None:
+        return None
+    return invocation_id, "interrupted_child_span_without_provider_result"
+
+
+def terminalize_after_host_exit(
+    root: Path, run_id: str, *, central_database: Path | None = None,
+) -> TransactionState | None:
+    """Close a non-terminal run only when its latest provider evidence proves interruption.
+
+    This is intentionally a watcher-side recovery boundary: the detached
+    Execution Host has already exited, so releasing its lease cannot terminate
+    active provider work.  Generic stale leases remain recoverable and are not
+    converted into failures here.
+    """
+    recovery = load_recovery_state(root, run_id, central_database=central_database)
+    # Durable recovery state takes precedence over retrospective provider
+    # evidence.  Only exhausted/unsafe recovery reaches the old terminalizer.
+    if isinstance(recovery, dict) and recovery.get("state") in {
+        "RECOVERY_AVAILABLE", "RECOVERY_STARTING", "RECOVERY_IN_PROGRESS", "RECOVERED",
+    }:
+        return None
+    evidence = _latest_interrupted_invocation(root, run_id, central_database=central_database)
+    if evidence is None:
+        return None
+    invocation_id, classification = evidence
+    store = StateStore(root / ".engineering" / "engineering-runs", central_database=central_database, emit_local_projection=central_database is None)
+    try:
+        state = store.load(run_id)
+    except StateError:
+        return None
+    if state.terminal:
+        return state
+    terminal = replace(
+        state,
+        phase="FAILED",
+        terminal=True,
+        next_action="NONE",
+        terminal_condition=INTERRUPTION_CLASSIFICATION,
+        diagnostic=(
+            f"{TERMINAL_DIAGNOSTIC} Provider invocation: {invocation_id}. "
+            f"Interruption evidence: {classification}."
+        ),
+    )
+    store.save(terminal)
+    reconcile_interrupted_phases(root, run_id, outcome="INTERRUPTED", central_database=central_database)
+    # The checkpoint is durable before cleanup. A cleanup failure therefore
+    # cannot overwrite the proven failure outcome.
+    try:
+        release_terminal_lease(root, run_id, central_database=central_database)
+    except Exception:
+        # Lease cleanup is secondary evidence.  The durable checkpoint stays
+        # authoritative and normal stale-lease reconciliation can record the
+        # separate cleanup concern on a later cycle.
+        LOGGER.exception("Terminal provider-interruption lease release failed for run %s", run_id)
+    write_live_status(root, terminal, terminal.next_action)
+    return terminal
+
+
+def prepare_same_run_recovery_after_host_exit(
+    root: Path, run_id: str, *, central_database: Path | None = None,
+) -> TransactionState | None:
+    """Persist the sole watcher-side continuation before it launches a host.
+
+    This intentionally accepts only the exact evidence already accepted by
+    ``terminalize_after_host_exit``.  It never creates a submission, branch,
+    or lease; the normal resumed host owns those operations.
+    """
+    evidence = _latest_interrupted_invocation(root, run_id, central_database=central_database)
+    if evidence is None:
+        return None
+    invocation_id, _classification = evidence
+    store = StateStore(root / ".engineering" / "engineering-runs", central_database=central_database, emit_local_projection=central_database is None)
+    try:
+        state = store.load(run_id)
+    except StateError:
+        return None
+    if state.terminal or load_recovery_state(root, run_id, central_database=central_database) is not None:
+        return None
+    try:
+        create_recovery_available(
+            root, run_id=run_id, triggering_invocation_id=invocation_id,
+            lifecycle_phase=state.phase, branch=state.branch,
+            worktree_identity=str(root.resolve()), lease_id=None,
+            central_database=central_database,
+        )
+    except Exception:
+        LOGGER.exception("Provider recovery evidence could not be persisted for %s", run_id)
+        return None
+    # This compact projection has no authority over recovery. It merely keeps
+    # existing status readers coherent until they read the durable row.
+    recovering = replace(state, next_action="recover_provider_turn", diagnostic="Provider interruption recovery is pending under the same execution.")
+    write_live_status(root, recovering, "Provider interrupted — recovering automatically (1/1)")
+    return recovering

engineering_platform/provider_process_identity.py

@@ -0,0 +1,80 @@
+"""Bounded, provider-neutral OS process identity evidence.
+
+The recovery controller never treats a PID as identity.  This adapter captures
+the process birth marker and executable path without retaining arguments or
+environment values that could contain prompts or credentials.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+import hashlib
+import os
+from pathlib import Path
+import subprocess
+
+
+@dataclass(frozen=True)
+class ProcessIdentity:
+    pid: int
+    process_group: int
+    start_fingerprint: str
+    executable_identity: str
+
+
+def _canonical_executable_identity(value: str) -> str:
+    """Normalize equivalent macOS Python framework executable spellings."""
+    path = Path(value).resolve()
+    parts = path.parts
+    try:
+        framework = parts.index("Python.framework")
+    except ValueError:
+        return str(path)
+    version_root = Path(*parts[: framework + 3])
+    suffix = parts[framework + 3 :]
+    if suffix == ("bin", path.name) or suffix == ("Resources", "Python.app", "Contents", "MacOS", "Python"):
+        return str(version_root / "python-runtime")
+    return str(path)
+
+
+def capture_process_identity(pid: int, process_group: int | None = None) -> ProcessIdentity | None:
+    """Capture portable `ps` birth/executable evidence for a live process."""
+    if pid <= 0:
+        return None
+    try:
+        observed_group = os.getpgid(pid)
+        if process_group is not None and observed_group != process_group:
+            return None
+        # `lstart` is a process-birth value on macOS and common POSIX hosts;
+        # `comm` is the executable identity, not command arguments.
+        completed = subprocess.run(
+            ("ps", "-o", "lstart=", "-o", "comm=", "-p", str(pid)),
+            check=False, capture_output=True, text=True, timeout=2,
+        )
+    except (OSError, subprocess.SubprocessError):
+        return None
+    if completed.returncode != 0:
+        return None
+    line = completed.stdout.strip()
+    if not line:
+        return None
+    # lstart is exactly five fields; the remainder is the executable path.
+    parts = line.split(maxsplit=5)
+    if len(parts) != 6:
+        return None
+    birth = " ".join(parts[:5])
+    executable = _canonical_executable_identity(parts[5][:512])
+    fingerprint = hashlib.sha256(f"{pid}|{observed_group}|{birth}".encode("utf-8")).hexdigest()
+    return ProcessIdentity(pid, observed_group, fingerprint, executable)
+
+
+def verify_process_identity(expected: ProcessIdentity) -> str:
+    """Return MATCH, NOT_ACTIVE, or MISMATCH without trusting PID alone."""
+    observed = capture_process_identity(expected.pid, expected.process_group)
+    if observed is None:
+        return "NOT_ACTIVE"
+    if (
+        observed.start_fingerprint == expected.start_fingerprint
+        and observed.executable_identity == expected.executable_identity
+    ):
+        return "MATCH"
+    return "MISMATCH"

engineering_platform/provider_readiness.py

@@ -0,0 +1,138 @@
+"""Token-free readiness checks for Engineering Platform host providers.
+
+The result is intentionally small and safe to persist or project.  Repairs are
+always explicit dashboard actions; this module never opens a login flow or
+retries authentication on behalf of an execution.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+import re
+import shutil
+import subprocess
+
+from .providers import CodexCliProvider, LocalProcessProvider, codex_cli_executable
+
+
+_VERSION = re.compile(r"\b\d+(?:\.\d+)+(?:[-+][0-9A-Za-z.]+)?\b")
+
+
+def _classify(result: subprocess.CompletedProcess[str] | None) -> str:
+    if result is None:
+        return "CHECK_FAILED"
+    if result.returncode == 0:
+        return "READY"
+    detail = f"{result.stdout}\n{result.stderr}".casefold()
+    return "AUTH_REQUIRED" if any(word in detail for word in (
+        "login", "auth", "credential", "token", "not logged in", "logged out", "not signed in",
+    )) else "CHECK_FAILED"
+
+
+def _repository_classify(result: subprocess.CompletedProcess[str] | None) -> str:
+    """Separate denied repository access from temporary GitHub API failures."""
+    if result is None:
+        return "CHECK_FAILED"
+    if result.returncode == 0:
+        return "READY"
+    detail = f"{result.stdout}\n{result.stderr}".casefold()
+    if any(word in detail for word in (
+        "network", "timed out", "timeout", "resolve host", "connection", "rate limit", "api",
+    )):
+        return "CHECK_FAILED"
+    return "AUTH_REQUIRED"
+
+
+def _version(result: subprocess.CompletedProcess[str] | None) -> str:
+    """Return just a CLI version, never command output or diagnostics."""
+    if result is None or result.returncode:
+        return ""
+    match = _VERSION.search(f"{result.stdout}\n{result.stderr}")
+    return match.group(0) if match else ""
+
+
+def runtime_details(root: Path) -> dict[str, dict[str, str]]:
+    """Project token-free CLI provenance for the host-wide Console projection."""
+    codex_path = codex_cli_executable() or ""
+    try:
+        codex_version = _version(CodexCliProvider().command("--version")) if codex_path else ""
+    except OSError:
+        codex_version = ""
+    github_path = shutil.which("gh") or ""
+    try:
+        github_version = _version(LocalProcessProvider().execute(root, (github_path, "--version"))) if github_path else ""
+    except OSError:
+        github_version = ""
+    return {
+        "codex": {"executable": codex_path, "version": codex_version},
+        "github": {"executable": github_path, "version": github_version},
+    }
+
+
+def host_status(root: Path, *, require_github: bool = True) -> dict[str, dict[str, str]]:
+    """Check host authentication without deriving any checkout authority.
+
+    This is the Server/CENTRAL projection used before a project is selected.
+    It deliberately asks GitHub only whether the local CLI has an active
+    account. Repository access belongs to project admission, where an actual
+    canonical repository identity is available.
+    """
+    codex = CodexCliProvider()
+    codex_installed = codex.status().qualified
+    try:
+        codex_result = codex.command("login", "status") if codex_installed else None
+    except OSError:
+        codex_result = None
+    result = {
+        "codex": {"provider": "CODEX", "state": "UNAVAILABLE" if not codex_installed else _classify(codex_result)},
+    }
+    if not require_github:
+        return result
+    github_path = shutil.which("gh")
+    if github_path is None:
+        result["github"] = {"provider": "GITHUB", "state": "UNAVAILABLE"}
+        return result
+    try:
+        github_result = LocalProcessProvider().execute(
+            root, (github_path, "auth", "status", "--hostname", "github.com"),
+        )
+    except OSError:
+        github_result = None
+    result["github"] = {"provider": "GITHUB", "state": _classify(github_result)}
+    return result
+
+
+def status(root: Path, *, require_github: bool = True) -> dict[str, dict[str, str]]:
+    """Return provider readiness without session details, tokens, or diagnostics."""
+    result = host_status(root, require_github=False)
+    if not require_github:
+        return result
+    if shutil.which("gh") is None:
+        result["github"] = {"provider": "GITHUB", "state": "UNAVAILABLE"}
+        return result
+    try:
+        github_result = LocalProcessProvider().execute(root, ("gh", "auth", "status", "--hostname", "github.com"))
+    except OSError:
+        github_result = None
+    github_state = _classify(github_result)
+    if github_state == "READY":
+        try:
+            # `gh repo view --json` uses GitHub's GraphQL quota. Readiness only
+            # needs a cheap repository-access proof, so use the REST endpoint
+            # and avoid turning an exhausted GraphQL quota into a login repair.
+            repository_result = LocalProcessProvider().execute(
+                root, ("gh", "api", "repos/{owner}/{repo}", "--jq", ".full_name")
+            )
+        except OSError:
+            repository_result = None
+        github_state = _repository_classify(repository_result)
+    result["github"] = {"provider": "GITHUB", "state": github_state}
+    return result
+
+
+def failures(root: Path, *, require_github: bool) -> tuple[str, ...]:
+    """Return the provider names that must be repaired before admission."""
+    return tuple(
+        value["provider"]
+        for value in status(root, require_github=require_github).values()
+        if value["state"] != "READY"
+    )