engineering-platform 2.2.0__py3-none-any.whl

engineering_platform/managed_autonomy.py

@@ -0,0 +1,509 @@
+"""Append-only Managed-autonomy evidence and fail-closed qualification read model."""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+import hashlib
+import json
+from pathlib import Path
+import sqlite3
+from typing import Iterable
+
+from .storage import (
+    EngineeringStorageError,
+    load_run_lineage,
+    load_run_qualification_snapshot,
+    load_validation_context,
+    open_storage,
+    record_run_qualification_snapshot,
+)
+
+AUTHORITIES = frozenset(
+    {
+        "AUTONOMOUS_EP_ACTION",
+        "EXPECTED_OPERATOR_GATE",
+        "EXTERNAL_PLATFORM_EVENT",
+        "UNPLANNED_MANUAL_INTERVENTION",
+        "UNKNOWN_AUTHORITY",
+    }
+)
+GATE_TYPES = frozenset({"IMPLEMENTATION_MERGE_APPROVAL", "FINALIZATION_MERGE_APPROVAL"})
+GATE_STATUSES = frozenset({"NOT_REQUIRED", "WAITING", "SATISFIED", "UNAVAILABLE"})
+VALIDATION_STATES = frozenset(
+    {"PASS", "FAIL", "NOT_EXECUTED", "NOT_APPLICABLE", "UNAVAILABLE", "WAITING"}
+)
+PR_CHECK_STATES = frozenset({"PASS", "FAIL", "WAITING", "UNAVAILABLE"})
+PR_ROLES = frozenset({"IMPLEMENTATION", "FINALIZATION"})
+
+
+def _connection(root: Path, central_database: Path | None) -> sqlite3.Connection:
+    """Open the explicitly supplied CENTRAL authority when one is composed.
+
+    ``root`` remains only the physical execution context for compatibility
+    callers.  The standalone runner always supplies ``central_database``.
+    """
+    if central_database is None:
+        return open_storage(root)
+    database = central_database.resolve()
+    if database.name != "engineering.db":
+        raise EngineeringStorageError("CENTRAL_MANAGED_AUTONOMY_DATABASE_INVALID")
+    return sqlite3.connect(database, isolation_level=None)
+
+
+def _now() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+def _safe(value: object, limit: int = 160) -> str:
+    if not isinstance(value, str) or not value or len(value) > limit or "\n" in value:
+        raise EngineeringStorageError("Managed autonomy evidence value is invalid.")
+    return value
+
+
+def append_action(
+    root,
+    *,
+    run_id: str,
+    action: str,
+    authority: str,
+    actor: str = "execution_host",
+    evidence_ref: str = "runtime",
+    observed_at: str | None = None,
+    central_database: Path | None = None,
+) -> None:
+    """Persist identifier-only evidence; raw prompts and tool output are rejected by shape."""
+    if authority not in AUTHORITIES:
+        raise EngineeringStorageError("Managed autonomy action authority is invalid.")
+    connection = _connection(Path(root), central_database)
+    try:
+        connection.execute(
+            "INSERT INTO managed_autonomy_actions(run_id,action,authority,actor,evidence_ref,observed_at) VALUES(?,?,?,?,?,?)",
+            (
+                _safe(run_id),
+                _safe(action),
+                authority,
+                _safe(actor),
+                _safe(evidence_ref),
+                observed_at or _now(),
+            ),
+        )
+    finally:
+        connection.close()
+
+
+def record_gate(
+    root,
+    *,
+    run_id: str,
+    gate_type: str,
+    status: str,
+    related_pr: int | None,
+    phase: str,
+    resolution_actor: str | None = None,
+    requested_at: str | None = None,
+    resolved_at: str | None = None,
+    central_database: Path | None = None,
+) -> None:
+    if (
+        gate_type not in GATE_TYPES
+        or status not in GATE_STATUSES
+        or (
+            related_pr is not None
+            and (isinstance(related_pr, bool) or not isinstance(related_pr, int) or related_pr < 1)
+        )
+    ):
+        raise EngineeringStorageError("Managed governance gate is invalid.")
+    connection = _connection(Path(root), central_database)
+    try:
+        connection.execute(
+            "INSERT INTO managed_governance_gates(run_id,gate_type,gate_authority,status,requested_at,resolved_at,resolution_actor,related_pr,phase) VALUES(?,?,?,?,?,?,?,?,?) ON CONFLICT(run_id,gate_type) DO UPDATE SET status=excluded.status,resolved_at=excluded.resolved_at,resolution_actor=excluded.resolution_actor,related_pr=excluded.related_pr,phase=excluded.phase",
+            (
+                _safe(run_id),
+                gate_type,
+                "OPERATOR",
+                status,
+                requested_at or _now(),
+                resolved_at,
+                resolution_actor,
+                related_pr,
+                _safe(phase),
+            ),
+        )
+    finally:
+        connection.close()
+
+
+def append_validation_observation(
+    root,
+    *,
+    run_id: str,
+    control: str,
+    state: str,
+    required: bool,
+    currentness: int = 0,
+    observed_at: str | None = None,
+    central_database: Path | None = None,
+) -> None:
+    if state not in VALIDATION_STATES or currentness < 0:
+        raise EngineeringStorageError("Managed validation observation is invalid.")
+    connection = _connection(Path(root), central_database)
+    try:
+        connection.execute(
+            "INSERT INTO managed_validation_observations(run_id,control,state,required,currentness,observed_at) VALUES(?,?,?,?,?,?)",
+            (
+                _safe(run_id),
+                _safe(control),
+                state,
+                int(required),
+                currentness,
+                observed_at or _now(),
+            ),
+        )
+    finally:
+        connection.close()
+
+
+def append_pr_check_observation(
+    root,
+    *,
+    run_id: str,
+    pr_number: int,
+    pr_role: str,
+    pr_state: str,
+    merge_commit: str | None,
+    required_checks_state: str,
+    evidence_ref: str,
+    currentness: int = 0,
+    observed_at: str | None = None,
+    central_database: Path | None = None,
+) -> None:
+    """Append a bounded GitHub required-check observation without changing lifecycle."""
+    if (
+        pr_role not in PR_ROLES
+        or required_checks_state not in PR_CHECK_STATES
+        or isinstance(pr_number, bool)
+        or not isinstance(pr_number, int)
+        or pr_number < 1
+        or currentness < 0
+        or (merge_commit is not None and (not isinstance(merge_commit, str) or len(merge_commit) != 40))
+    ):
+        raise EngineeringStorageError("Managed PR check observation is invalid.")
+    connection = _connection(Path(root), central_database)
+    try:
+        connection.execute(
+            "INSERT INTO managed_pr_check_observations(run_id,pr_number,pr_role,pr_state,merge_state,merge_commit,required_checks_state,evidence_ref,observed_at,currentness) VALUES(?,?,?,?,?,?,?,?,?,?)",
+            (
+                _safe(run_id), pr_number, pr_role, _safe(pr_state),
+                "MERGED" if pr_state == "MERGED" else "NOT_MERGED", merge_commit,
+                required_checks_state, _safe(evidence_ref), observed_at or _now(), currentness,
+            ),
+        )
+    finally:
+        connection.close()
+
+
+def _current(rows: Iterable[tuple[object, ...]]) -> tuple[dict[str, str], bool]:
+    grouped: dict[str, list[tuple[str, int]]] = {}
+    for control, state, _required, currentness, _at in rows:
+        grouped.setdefault(str(control), []).append((str(state), int(currentness)))
+    result, conflict = {}, False
+    for control, values in grouped.items():
+        latest = max(item[1] for item in values)
+        states = {item[0] for item in values if item[1] == latest}
+        conflict |= len(states) != 1
+        result[control] = next(iter(states)) if len(states) == 1 else "UNAVAILABLE"
+    return result, conflict
+
+
+def _current_pr_checks(rows: Iterable[tuple[object, ...]]) -> tuple[dict[str, dict[str, object]], bool]:
+    """Keep historical observations append-only while selecting current terminal evidence."""
+    grouped: dict[str, list[tuple[object, ...]]] = {}
+    for row in rows:
+        grouped.setdefault(str(row[2]), []).append(row)
+    result: dict[str, dict[str, object]] = {}
+    conflict = False
+    for role, values in grouped.items():
+        latest = max((int(row[9]), int(row[0])) for row in values)
+        current = [row for row in values if (int(row[9]), int(row[0])) == latest]
+        signatures = {(row[3], row[4], row[5], row[6], row[7]) for row in current}
+        if len(signatures) != 1:
+            conflict = True
+            result[role] = {"required_checks_state": "UNAVAILABLE", "conflict": True}
+            continue
+        row = current[-1]
+        result[role] = {
+            "pr_number": row[1], "pr_state": row[3], "merge_state": row[4],
+            "merge_commit": row[5], "required_checks_state": row[6],
+            "evidence_ref": row[7], "observed_at": row[8], "conflict": False,
+            "historical_observation_count": len(values) - len(current),
+        }
+    return result, conflict
+
+
+def terminal_snapshot(
+    root,
+    *,
+    run_id: str,
+    execution_outcome: str,
+    implementation_pr: int | None,
+    finalization_pr: int | None,
+    repository_state: str,
+    workspace_state: str,
+    main_origin_sync: str,
+    worktree_state: str,
+    active_blocker: str,
+    recovery_required: str,
+    retry_parent: str | None = None,
+    resume_parent: str | None = None,
+    submission_id: str | None = None,
+    lineage_available: bool = False,
+    reviewer_records: tuple[dict[str, object], ...] = (),
+    execution_mode: str = "MANAGED",
+    action_intent: str = "MUTATING_DELIVERY",
+    persist: bool = False,
+) -> dict[str, object]:
+    if persist:
+        persisted = load_run_qualification_snapshot(root, run_id)
+        if persisted is not None:
+            return persisted
+    connection = open_storage(root)
+    try:
+        actions = connection.execute(
+            "SELECT action,authority FROM managed_autonomy_actions WHERE run_id=? ORDER BY id",
+            (run_id,),
+        ).fetchall()
+        gates = connection.execute(
+            "SELECT gate_type,status,related_pr FROM managed_governance_gates WHERE run_id=?",
+            (run_id,),
+        ).fetchall()
+        rows = connection.execute(
+            "SELECT control,state,required,currentness,observed_at FROM managed_validation_observations WHERE run_id=? ORDER BY id",
+            (run_id,),
+        ).fetchall()
+        pr_rows = connection.execute(
+            "SELECT id,pr_number,pr_role,pr_state,merge_state,merge_commit,required_checks_state,evidence_ref,observed_at,currentness FROM managed_pr_check_observations WHERE run_id=? ORDER BY id",
+            (run_id,),
+        ).fetchall()
+    finally:
+        connection.close()
+    validation, conflict = _current(rows)
+    pr_checks, pr_check_conflict = _current_pr_checks(pr_rows)
+    try:
+        persisted_lineage = load_run_lineage(root, run_id)
+        validation_context = load_validation_context(root, run_id)
+    except EngineeringStorageError:
+        persisted_lineage = validation_context = None
+    if persisted_lineage is not None:
+        lineage_available = True
+        submission_id = str(persisted_lineage["submission_id"])
+        retry_parent = persisted_lineage["retry_parent"] if isinstance(persisted_lineage["retry_parent"], str) else None
+        resume_parent = persisted_lineage["resume_parent"] if isinstance(persisted_lineage["resume_parent"], str) else None
+        fresh = "YES" if persisted_lineage["fresh_submission"] else "NO"
+    else:
+        fresh = "YES" if lineage_available and retry_parent is None and resume_parent is None else "NO" if lineage_available else "UNAVAILABLE"
+    required = {str(row[0]) for row in rows if int(row[2])}
+    required_state = "UNRESOLVED"
+    profile_projection: dict[str, object] = {}
+    if validation_context is not None:
+        required = set(validation_context["required_validation_controls"])
+        controls = validation_context["controls"]
+        results = [controls.get(control, {}).get("result") for control in required]
+        required_state = "FAIL" if any(result == "FAIL" for result in results) else "PASS" if results and all(result == "PASS" for result in results) else "UNRESOLVED"
+        profile_projection = {key: validation_context[key] for key in (
+            "selected_validation_tier", "validation_profile_version", "profile_reference",
+            "profile_selection_source", "required_validation_controls", "control_bindings",
+        )}
+        validation = {**validation, **{key: value.get("result", "UNRESOLVED") for key, value in controls.items()}}
+    elif required:
+        # Historical evidence has no persisted profile: do not promote it.
+        required_state = "UNRESOLVED"
+    authorities = [str(row[1]) for row in actions]
+    cleanup_attempted = any(
+        action == "CLEANUP" and authority == "AUTONOMOUS_EP_ACTION"
+        for action, authority in actions
+    )
+    cleanup_outcome = (
+        "COMPLETED" if cleanup_attempted and execution_outcome == "COMPLETE"
+        else "FAILED" if cleanup_attempted and execution_outcome in {"BLOCKED", "FAILED"}
+        else "NOT_REQUIRED" if action_intent == "VALIDATION_ONLY"
+        else "UNAVAILABLE"
+    )
+    snapshot = {
+        "run_id": run_id,
+        "terminal_execution_state": execution_outcome,
+        "execution_mode": execution_mode,
+        "managed_authority_profile": "OPERATOR_OWNED_PR_MERGE",
+        "action_intent": action_intent,
+        "fresh_submission": fresh,
+        "retry_parent": retry_parent or ("NONE" if lineage_available else "UNAVAILABLE"),
+        "resume_parent": resume_parent or ("NONE" if lineage_available else "UNAVAILABLE"),
+        "submission_id": submission_id or "UNAVAILABLE",
+        "implementation_pr": implementation_pr,
+        "finalization_pr": finalization_pr,
+        "gates": [{"gate_type": row[0], "status": row[1], "related_pr": row[2]} for row in gates],
+        "actions": [{"action": row[0], "authority": row[1]} for row in actions],
+        "validation_current": validation,
+        "required_validation_state": required_state,
+        "validation_profile": profile_projection or "UNAVAILABLE",
+        "validation_projection_conflict": conflict,
+        "pr_checks": pr_checks,
+        "pr_check_projection_conflict": pr_check_conflict,
+        "repository_state": repository_state,
+        "workspace_state": workspace_state,
+        "main_origin_sync": main_origin_sync,
+        "worktree_state": worktree_state,
+        "active_blocking_predecessor": active_blocker,
+        "recovery_required": recovery_required,
+        "cleanup_outcome": cleanup_outcome,
+        "expected_operator_gate_count": len(gates),
+        "autonomous_ep_action_count": authorities.count("AUTONOMOUS_EP_ACTION"),
+        "external_platform_event_count": authorities.count("EXTERNAL_PLATFORM_EVENT"),
+        "unplanned_manual_intervention_count": authorities.count("UNPLANNED_MANUAL_INTERVENTION"),
+        "unknown_authority_count": authorities.count("UNKNOWN_AUTHORITY"),
+        "reviewer_independence": "NOT_APPLICABLE"
+        if not reviewer_records
+        else (
+            "PROVEN" if all(not row.get("failed") for row in reviewer_records) else "UNAVAILABLE"
+        ),
+        "observed_at": _now(),
+    }
+    for role, pr_number in (("IMPLEMENTATION", implementation_pr), ("FINALIZATION", finalization_pr)):
+        check = pr_checks.get(role, {})
+        snapshot[f"{role.lower()}_delivery"] = (
+            "COMPLETE"
+            if isinstance(pr_number, int)
+            and check.get("pr_number") == pr_number
+            and check.get("pr_state") == "MERGED"
+            and check.get("merge_state") == "MERGED"
+            and isinstance(check.get("merge_commit"), str)
+            and len(check["merge_commit"]) == 40
+            and check.get("required_checks_state") == "PASS"
+            else "UNAVAILABLE"
+        )
+    snapshot["run_qualification"], snapshot["qualification_failure_reasons"] = evaluate(snapshot)
+    # Compatibility projection retained for existing consumers.  It has the
+    # same run-scoped meaning and must never be mistaken for platform-wide
+    # qualification evidence.
+    snapshot["managed_autonomy_qualification"] = snapshot["run_qualification"]
+    if persist:
+        required_controls = snapshot.get("validation_profile", {})
+        required_controls = required_controls if isinstance(required_controls, dict) else {}
+        required_control_snapshot = {
+            "profile_reference": required_controls.get("profile_reference", "UNAVAILABLE"),
+            "validation_profile_version": required_controls.get("validation_profile_version", "UNAVAILABLE"),
+            "required_validation_controls": required_controls.get("required_validation_controls", ()),
+            "validation_current": snapshot["validation_current"],
+        }
+        snapshot["required_control_snapshot_ref"] = "required-controls:sha256:" + hashlib.sha256(
+            json.dumps(required_control_snapshot, sort_keys=True, separators=(",", ":"), default=str).encode()
+        ).hexdigest()
+        snapshot["terminal_checkpoint_ref"] = f"terminal-checkpoint:{run_id}:{execution_outcome}"
+        snapshot["reconciliation_evidence"] = {
+            "repository_state": repository_state,
+            "workspace_state": workspace_state,
+            "main_origin_sync": main_origin_sync,
+            "worktree_state": worktree_state,
+            "active_blocking_predecessor": active_blocker,
+            "recovery_required": recovery_required,
+        }
+        conflicts = []
+        if snapshot["validation_projection_conflict"]:
+            conflicts.append("VALIDATION_CURRENT_CONFLICT")
+        if snapshot["pr_check_projection_conflict"]:
+            conflicts.append("PR_CHECK_CURRENT_CONFLICT")
+        snapshot["projection_conflicts"] = conflicts
+        # The persisted contract has exactly two outcomes.  The existing
+        # in-memory compatibility label remains available to old callers.
+        if snapshot["run_qualification"] == "EVIDENCE_INSUFFICIENT":
+            snapshot["run_qualification"] = "NOT_QUALIFIED"
+            snapshot["managed_autonomy_qualification"] = "NOT_QUALIFIED"
+        snapshot["persisted_at"] = snapshot["observed_at"]
+        identity_payload = {key: value for key, value in snapshot.items() if key not in {"qualification_snapshot_id", "persisted_at", "observed_at"}}
+        snapshot["qualification_snapshot_id"] = "qualification:sha256:" + hashlib.sha256(
+            json.dumps(identity_payload, sort_keys=True, separators=(",", ":"), default=str).encode()
+        ).hexdigest()
+        return record_run_qualification_snapshot(root, snapshot)
+    return snapshot
+
+
+def evaluate(snapshot: dict[str, object]) -> tuple[str, list[str]]:
+    reasons: list[str] = []
+    terminal = snapshot.get("terminal_execution_state")
+    if terminal == "FAILED":
+        return "NOT_QUALIFIED", ["TERMINAL_EXECUTION_FAILED"]
+    if terminal == "BLOCKED":
+        return "NOT_QUALIFIED", ["TERMINAL_EXECUTION_BLOCKED"]
+    if snapshot.get("fresh_submission") != "YES":
+        reasons.append("FRESH_SUBMISSION_UNPROVEN")
+    validation_only = snapshot.get("action_intent") == "VALIDATION_ONLY"
+    if snapshot.get("terminal_execution_state") != "COMPLETE":
+        reasons.append("VALIDATION_EXECUTION_UNPROVEN" if validation_only else "IMPLEMENTATION_DELIVERY_UNPROVEN")
+    if snapshot.get("unknown_authority_count", 0):
+        reasons.append("EP_ACTION_AUTHORITY_UNPROVEN")
+    if snapshot.get("unplanned_manual_intervention_count", 0):
+        reasons.append("UNEXPECTED_MANUAL_INTERVENTION")
+    gate = {
+        row.get("gate_type"): row.get("status")
+        for row in snapshot.get("gates", [])
+        if isinstance(row, dict)
+    }
+    if not validation_only:
+        if snapshot.get("implementation_delivery") != "COMPLETE":
+            reasons.append("IMPLEMENTATION_DELIVERY_UNPROVEN")
+        if snapshot.get("finalization_delivery") != "COMPLETE":
+            reasons.append("FINALIZATION_DELIVERY_UNPROVEN")
+        if gate.get("IMPLEMENTATION_MERGE_APPROVAL") != "SATISFIED":
+            reasons.append("IMPLEMENTATION_MERGE_GATE_UNPROVEN")
+        if gate.get("FINALIZATION_MERGE_APPROVAL") != "SATISFIED":
+            reasons.append("FINALIZATION_MERGE_GATE_UNPROVEN")
+    autonomous = {
+        row.get("action")
+        for row in snapshot.get("actions", [])
+        if isinstance(row, dict) and row.get("authority") == "AUTONOMOUS_EP_ACTION"
+    }
+    if not validation_only and (
+        not {
+            "IMPLEMENTATION",
+            "POST_IMPLEMENTATION_MERGE",
+            "FINALIZATION",
+            "RECONCILIATION",
+            "CLEANUP",
+        }
+        <= autonomous
+    ):
+        reasons.append("EP_ACTION_AUTHORITY_UNPROVEN")
+    if snapshot.get("required_validation_state") != "PASS":
+        reasons.append("REQUIRED_VALIDATION_UNRESOLVED")
+    if snapshot.get("cleanup_outcome") not in {"COMPLETED", "NOT_REQUIRED"}:
+        reasons.append("CLEANUP_OUTCOME_UNPROVEN")
+    if snapshot.get("validation_projection_conflict"):
+        reasons.append("EVIDENCE_CONFLICT")
+    if snapshot.get("pr_check_projection_conflict"):
+        reasons.append("EVIDENCE_CONFLICT")
+    for role in (() if validation_only else ("IMPLEMENTATION", "FINALIZATION")):
+        if snapshot.get(f"{role.lower()}_pr") is not None:
+            check = snapshot.get("pr_checks", {}).get(role, {})
+            if check.get("required_checks_state") != "PASS":
+                reasons.append(f"{role}_REQUIRED_CHECKS_UNRESOLVED")
+    for key, wanted in {
+        "repository_state": "MERGED_RECONCILED",
+        "workspace_state": "WORKSPACE_READY",
+        "main_origin_sync": "YES",
+        "worktree_state": "CLEAN",
+        "active_blocking_predecessor": "NONE",
+        "recovery_required": "NO",
+    }.items():
+        if snapshot.get(key) != wanted:
+            reasons.append(
+                "REPOSITORY_FINAL_STATE_UNPROVEN"
+                if key in {"repository_state", "main_origin_sync", "worktree_state"}
+                else "WORKSPACE_FINAL_STATE_UNPROVEN"
+            )
+    if snapshot.get("reviewer_independence") not in {"PROVEN", "NOT_APPLICABLE"}:
+        reasons.append("REVIEWER_POLICY_UNPROVEN")
+    reasons = list(dict.fromkeys(reasons))
+    return (
+        ("NOT_QUALIFIED", reasons)
+        if "UNEXPECTED_MANUAL_INTERVENTION" in reasons
+        else (("QUALIFIED", []) if not reasons else ("EVIDENCE_INSUFFICIENT", reasons))
+    )

engineering_platform/managed_codex_runtime.py

@@ -0,0 +1,105 @@
+"""Installation-owned lifecycle for Engineering Platform's managed Codex CLI.
+
+This preserves the historical explicit-console repair model: startup only
+observes the EP-owned runtime, while a confirmed operator action provisions or
+updates a version pinned from the npm registry.  It never selects a PATH
+``codex`` executable.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+import json
+import re
+import shutil
+from threading import Lock
+
+from .providers import CodexCliProvider, LocalProcessProvider, codex_cli_executable, engineering_platform_codex_cli_prefix
+
+
+CODEX_CLI_PACKAGE = "@openai/codex"
+_VERSION = re.compile(r"^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$")
+_VERSION_IN_OUTPUT = re.compile(r"(?<!\d)(\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?)(?!\d)")
+_install_lock = Lock()
+
+
+class ManagedCodexRuntimeError(RuntimeError):
+    """The explicit managed-runtime repair could not complete safely."""
+
+
+def version(value: object) -> str | None:
+    candidate = str(value or "").strip().removeprefix("v")
+    if _VERSION.fullmatch(candidate):
+        return candidate
+    match = _VERSION_IN_OUTPUT.search(candidate)
+    return match.group(1) if match else None
+
+
+def version_key(value: str) -> tuple[int, int, int, int, str]:
+    base, separator, prerelease = value.partition("-")
+    major, minor, patch = (int(part) for part in base.split("."))
+    return major, minor, patch, 1 if not separator else 0, prerelease
+
+
+def npm_executable() -> str | None:
+    return shutil.which("npm")
+
+
+def inspect(root: Path) -> dict[str, object]:
+    """Classify only the canonical managed launcher without network activity."""
+    executable = engineering_platform_codex_cli_prefix() / "bin" / "codex"
+    if not executable.is_file():
+        return {"state": "MISSING", "path": str(executable), "remediation_available": npm_executable() is not None}
+    if not executable.stat().st_mode & 0o111:
+        return {"state": "BROKEN", "path": str(executable), "remediation_available": npm_executable() is not None}
+    try:
+        completed = CodexCliProvider().command("--version")
+    except OSError:
+        completed = None
+    detected = version((completed.stdout or completed.stderr) if completed is not None and completed.returncode == 0 else None)
+    if detected is None:
+        return {"state": "BROKEN", "path": str(executable), "remediation_available": npm_executable() is not None}
+    return {"state": "READY", "path": str(executable), "version": detected, "remediation_available": npm_executable() is not None}
+
+
+def _published_version(root: Path, npm: str) -> str:
+    try:
+        completed = LocalProcessProvider().execute(root, (npm, "view", CODEX_CLI_PACKAGE, "version", "--json"))
+        raw = json.loads(completed.stdout) if completed.returncode == 0 else None
+    except (OSError, ValueError, json.JSONDecodeError) as error:
+        raise ManagedCodexRuntimeError("codex_cli_update_unavailable") from error
+    candidates = raw if isinstance(raw, list) else [raw]
+    versions = [candidate for item in candidates if (candidate := version(item)) is not None]
+    latest = max(versions, key=version_key, default=None)
+    if latest is None:
+        raise ManagedCodexRuntimeError("codex_cli_update_unavailable")
+    return latest
+
+
+def provision(root: Path, *, allow_current: bool = True) -> dict[str, object]:
+    """Install or update the exact published release into EP's owned prefix."""
+    with _install_lock:
+        npm = npm_executable()
+        if npm is None:
+            raise ManagedCodexRuntimeError("codex_cli_update_unavailable")
+        before = inspect(root)
+        if before["state"] == "READY" and not allow_current:
+            return {"updated": False, "current_version": before["version"]}
+        latest = _published_version(root, npm)
+        if before.get("version") == latest:
+            return {"updated": False, "current_version": latest}
+        try:
+            completed = LocalProcessProvider().execute(
+                root,
+                (npm, "install", "--global", "--prefix", str(engineering_platform_codex_cli_prefix()), f"{CODEX_CLI_PACKAGE}@{latest}"),
+            )
+        except OSError as error:
+            raise ManagedCodexRuntimeError("codex_cli_update_failed") from error
+        if completed.returncode:
+            diagnostic = f"{completed.stdout}\n{completed.stderr}".casefold()
+            raise ManagedCodexRuntimeError(
+                "codex_cli_update_permissions_required" if "eacces" in diagnostic or "permission denied" in diagnostic else "codex_cli_update_failed"
+            )
+        after = inspect(root)
+        if after.get("state") != "READY" or not isinstance(after.get("version"), str) or version_key(after["version"]) < version_key(latest):
+            raise ManagedCodexRuntimeError("codex_cli_update_failed")
+        return {"updated": True, "current_version": after["version"]}