loopx 0.4.8__py3-none-any.whl

loopx/self_update.py

@@ -0,0 +1,750 @@
+from __future__ import annotations
+
+from pathlib import Path
+import os
+import re
+import shlex
+import subprocess
+from typing import Any
+from urllib.parse import quote
+from urllib.request import Request, urlopen
+
+from .doctor import collect_doctor
+from .install_contract import NO_CLONE_INSTALL_URL
+
+
+UPDATE_PLAN_SCHEMA_VERSION = "loopx_update_plan_v0"
+DEFAULT_UPDATE_REPO = "huangruiteng/loopx"
+DEFAULT_UPDATE_REF = "stable"
+ROLLBACK_PREVIOUS_ALIAS = "previous"
+SOURCE_VERSION_CHECK_SCHEMA_VERSION = "loopx_source_version_check_v0"
+RUNTIME_ACTIVATION_QUALIFICATION_SCHEMA_VERSION = (
+    "loopx_runtime_activation_qualification_v0"
+)
+SOURCE_VERSION_CHECK_TIMEOUT_SECONDS = 3
+SOURCE_VERSION_READ_LIMIT_BYTES = 64 * 1024
+PERSISTED_PYTHON_FILENAME = ".loopx-python"
+_PACKAGE_VERSION_PATTERN = re.compile(r'^__version__\s*=\s*"([^"]+)"$', re.MULTILINE)
+
+
+def _source_config(
+    *,
+    repo: str | None,
+    ref: str | None,
+    archive_url: str | None,
+) -> dict[str, Any]:
+    selected_repo = repo or os.environ.get("LOOPX_REPO") or DEFAULT_UPDATE_REPO
+    ref_override = ref or os.environ.get("LOOPX_REF")
+    selected_ref = ref_override or DEFAULT_UPDATE_REF
+    archive_url_override = archive_url or os.environ.get("LOOPX_ARCHIVE_URL")
+    selected_archive_url = archive_url_override
+    if not selected_archive_url:
+        selected_archive_url = f"https://codeload.github.com/{selected_repo}/tar.gz/{selected_ref}"
+    if archive_url_override:
+        channel = "github_archive_url_override"
+    elif ref_override:
+        channel = "github_archive_override"
+    else:
+        channel = "github_archive_stable"
+    return {
+        "channel": channel,
+        "repo": selected_repo,
+        "ref": selected_ref,
+        "ref_source": "default_stable" if not ref_override else "override",
+        "archive_url": selected_archive_url,
+        "installer_url": NO_CLONE_INSTALL_URL,
+    }
+
+
+def _command_for_source(source: dict[str, Any]) -> str:
+    exports = [
+        f"LOOPX_REPO={shlex.quote(str(source['repo']))}",
+        f"LOOPX_REF={shlex.quote(str(source['ref']))}",
+    ]
+    archive_url = source.get("archive_url")
+    if source.get("channel") == "github_archive_url_override" and archive_url:
+        exports.append(f"LOOPX_ARCHIVE_URL={shlex.quote(str(archive_url))}")
+    return (
+        "set -o errexit -o pipefail\n"
+        + "\n".join(f"export {value}" for value in exports)
+        + f"\ncurl -fsSL {shlex.quote(str(source['installer_url']))} | bash\n"
+        'export PATH="$HOME/.local/bin:$PATH"\n'
+        "loopx doctor"
+    )
+
+
+def _installer_env_for_source(
+    source: dict[str, Any],
+    *,
+    base_env: dict[str, str] | None = None,
+    current_release_root: str | Path | None = None,
+) -> dict[str, str]:
+    env = dict(os.environ if base_env is None else base_env)
+    if not env.get("LOOPX_PYTHON") and current_release_root is not None:
+        marker = Path(current_release_root) / PERSISTED_PYTHON_FILENAME
+        try:
+            persisted_python = marker.read_text(encoding="utf-8").strip()
+        except OSError as exc:
+            raise ValueError(
+                "active LoopX release snapshot is missing its persisted Python runtime; "
+                "set LOOPX_PYTHON to a Python 3.11+ executable before retrying"
+            ) from exc
+        if not persisted_python:
+            raise ValueError(
+                "active LoopX release snapshot has an empty persisted Python runtime; "
+                "set LOOPX_PYTHON to a Python 3.11+ executable before retrying"
+            )
+        env["LOOPX_PYTHON"] = persisted_python
+    env["LOOPX_REPO"] = str(source.get("repo") or DEFAULT_UPDATE_REPO)
+    env["LOOPX_REF"] = str(source.get("ref") or DEFAULT_UPDATE_REF)
+    if source.get("channel") == "github_archive_url_override" and source.get("archive_url"):
+        env["LOOPX_ARCHIVE_URL"] = str(source["archive_url"])
+    else:
+        env.pop("LOOPX_ARCHIVE_URL", None)
+    return env
+
+
+def _source_version_check(source: dict[str, Any]) -> dict[str, Any]:
+    base = {
+        "schema_version": SOURCE_VERSION_CHECK_SCHEMA_VERSION,
+        "attempted": False,
+        "status": "skipped",
+        "version": None,
+        "version_tag": None,
+        "matches_current": None,
+        "source_url": None,
+        "reason": None,
+    }
+    if source.get("channel") == "github_archive_url_override":
+        return {
+            **base,
+            "reason": "custom archive URL is not assumed to match the configured GitHub repo/ref",
+        }
+
+    repo = str(source.get("repo") or "")
+    ref = str(source.get("ref") or "")
+    repo_parts = repo.split("/")
+    if len(repo_parts) != 2 or not all(
+        re.fullmatch(r"[A-Za-z0-9_.-]+", part) for part in repo_parts
+    ):
+        return {**base, "reason": "GitHub repo must use owner/name syntax"}
+    if not ref:
+        return {**base, "reason": "GitHub ref is missing"}
+
+    owner, name = repo_parts
+    source_url = (
+        "https://raw.githubusercontent.com/"
+        f"{quote(owner, safe='')}/{quote(name, safe='')}/{quote(ref, safe='')}/loopx/__init__.py"
+    )
+    request = Request(
+        source_url,
+        headers={"Accept": "text/plain", "User-Agent": "LoopX-update-check"},
+    )
+    try:
+        with urlopen(  # noqa: S310 - the host is fixed to raw.githubusercontent.com.
+            request,
+            timeout=SOURCE_VERSION_CHECK_TIMEOUT_SECONDS,
+        ) as response:
+            body = response.read(SOURCE_VERSION_READ_LIMIT_BYTES).decode("utf-8")
+    except Exception as exc:  # Remote comparison is advisory and must degrade offline.
+        return {
+            **base,
+            "attempted": True,
+            "status": "unavailable",
+            "source_url": source_url,
+            "reason": f"remote version check unavailable ({type(exc).__name__})",
+        }
+
+    match = _PACKAGE_VERSION_PATTERN.search(body)
+    if not match:
+        return {
+            **base,
+            "attempted": True,
+            "status": "unavailable",
+            "source_url": source_url,
+            "reason": "remote package version was not found",
+        }
+    version = match.group(1)
+    return {
+        **base,
+        "attempted": True,
+        "status": "available",
+        "version": version,
+        "version_tag": f"v{version}",
+        "source_url": source_url,
+    }
+
+
+def _runtime_activation_qualification(
+    *,
+    install_freshness: dict[str, Any],
+    source: dict[str, Any],
+) -> dict[str, Any]:
+    installed_commit = install_freshness.get("manifest_source_git_commit")
+    target_commit = install_freshness.get("freshness_source_git_commit")
+    revision_relation = install_freshness.get("manifest_source_freshness_relation")
+    qualified_repo = install_freshness.get("manifest_source_repo")
+    qualified_ref = install_freshness.get("manifest_source_ref")
+    selected_repo = source.get("repo")
+    selected_ref = source.get("ref")
+    package_matches_runtime = install_freshness.get(
+        "manifest_package_version_matches_runtime"
+    )
+    requires_upgrade = install_freshness.get("requires_upgrade")
+    has_commit_pair = all(
+        isinstance(commit, str) and bool(commit)
+        for commit in (installed_commit, target_commit)
+    )
+    source_identity_matches = all(
+        isinstance(value, str) and bool(value)
+        for value in (qualified_repo, qualified_ref, selected_repo, selected_ref)
+    ) and (
+        str(qualified_repo).removesuffix(".git").lower()
+        == str(selected_repo).removesuffix(".git").lower()
+        and str(qualified_ref).removeprefix("refs/heads/")
+        == str(selected_ref).removeprefix("refs/heads/")
+    )
+
+    if package_matches_runtime is False:
+        decision = "release_or_install_successor_required"
+        runtime_active: bool | None = False
+        successor_kind = "release_or_install"
+        reason = "release manifest package version does not match the active runtime"
+    elif not source_identity_matches:
+        decision = "activation_qualification_required"
+        runtime_active = None
+        successor_kind = "activation_qualification"
+        reason = "trusted source lineage does not identify the selected update source"
+    elif has_commit_pair and (
+        installed_commit == target_commit or revision_relation == "installed_ahead"
+    ):
+        decision = "runtime_active"
+        runtime_active = True
+        successor_kind = None
+        reason = "installed source contains the trusted target source commit"
+    elif has_commit_pair and revision_relation in {"installed_behind", "diverged"}:
+        decision = "release_or_install_successor_required"
+        runtime_active = False
+        successor_kind = "release_or_install"
+        reason = "installed source does not contain the trusted target source commit"
+    else:
+        decision = "activation_qualification_required"
+        runtime_active = None
+        successor_kind = "activation_qualification"
+        reason = "trusted installed-versus-target source lineage is unavailable"
+
+    return {
+        "schema_version": RUNTIME_ACTIVATION_QUALIFICATION_SCHEMA_VERSION,
+        "decision": decision,
+        "runtime_active": runtime_active,
+        "installed_release_id": install_freshness.get("release_id"),
+        "installed_version": install_freshness.get("current_version"),
+        "installed_source_commit": installed_commit,
+        "target_source_label": install_freshness.get("freshness_source_label"),
+        "target_source_commit": target_commit,
+        "revision_relation": revision_relation,
+        "qualified_source": {
+            "repo": qualified_repo,
+            "ref": qualified_ref,
+        },
+        "source_identity_matches": source_identity_matches,
+        "package_version_matches_runtime": package_matches_runtime,
+        "requires_upgrade": requires_upgrade,
+        "selected_source": {
+            "repo": selected_repo,
+            "ref": selected_ref,
+        },
+        "successor": {
+            "required": runtime_active is not True,
+            "kind": successor_kind,
+        },
+        "reason": reason,
+    }
+
+
+def _release_root_from_doctor(doctor_payload: dict[str, Any]) -> str | None:
+    package = doctor_payload.get("package") if isinstance(doctor_payload.get("package"), dict) else {}
+    release_root = package.get("release_root")
+    if isinstance(release_root, str) and release_root:
+        return release_root
+    path = doctor_payload.get("path") if isinstance(doctor_payload.get("path"), dict) else {}
+    realpath = path.get("loopx_realpath")
+    if isinstance(realpath, str) and realpath:
+        realpath_path = Path(realpath)
+        if realpath_path.name == "loopx" and realpath_path.parent.name == "scripts":
+            return str(realpath_path.parent.parent)
+    return None
+
+
+def _user_loopx_bin(home: Path | None = None) -> Path:
+    return (home or Path.home()) / ".local" / "bin" / "loopx"
+
+
+def _user_releases_dir(home: Path | None = None) -> Path:
+    return (home or Path.home()) / ".local" / "share" / "loopx" / "releases"
+
+
+def _release_script(release_root: Path) -> Path:
+    return release_root / "scripts" / "loopx"
+
+
+def _list_release_roots(releases_dir: Path) -> list[Path]:
+    if not releases_dir.exists():
+        return []
+    return sorted(
+        (
+            item
+            for item in releases_dir.iterdir()
+            if item.is_dir() and _release_script(item).exists()
+        ),
+        key=lambda item: item.name,
+        reverse=True,
+    )
+
+
+def _rollback_release_command(release_id: str) -> str:
+    return f"loopx update --rollback {shlex.quote(release_id)}\nloopx doctor"
+
+
+def _rollback_plan(doctor_payload: dict[str, Any]) -> dict[str, Any]:
+    release_root = _release_root_from_doctor(doctor_payload)
+    if not release_root:
+        return {
+            "available": False,
+            "reason": "current loopx command is not a release snapshot",
+            "current_release_root": None,
+            "rollback_command": None,
+        }
+    release_id = Path(release_root).name
+    return {
+        "available": True,
+        "reason": "current release snapshot can be restored with the first-class rollback CLI",
+        "rollback_release_id": release_id,
+        "current_release_root": release_root,
+        "rollback_command": _rollback_release_command(release_id),
+    }
+
+
+def build_rollback_plan(
+    *,
+    release_id: str,
+    doctor_payload: dict[str, Any] | None = None,
+    home: Path | None = None,
+) -> dict[str, Any]:
+    doctor = doctor_payload or collect_doctor()
+    current_release_root = _release_root_from_doctor(doctor)
+    releases_dir = _user_releases_dir(home)
+    releases = _list_release_roots(releases_dir)
+    current_root_path = Path(current_release_root).resolve() if current_release_root else None
+    requested_release_id = release_id.strip()
+    selected: Path | None = None
+    reason = None
+
+    if not requested_release_id:
+        reason = "rollback release id is required"
+    elif requested_release_id == ROLLBACK_PREVIOUS_ALIAS:
+        for candidate in releases:
+            if current_root_path and candidate.resolve() == current_root_path:
+                continue
+            selected = candidate
+            break
+        if selected is None:
+            reason = "no previous release snapshot found"
+    elif "/" in requested_release_id or requested_release_id in {".", ".."}:
+        reason = "rollback release id must be a release directory name"
+    else:
+        candidate = releases_dir / requested_release_id
+        if not _release_script(candidate).exists():
+            reason = f"release snapshot not found: {requested_release_id}"
+        else:
+            selected = candidate
+
+    available = selected is not None
+    selected_release_id = selected.name if selected else None
+    selected_release_root = str(selected) if selected else None
+    return {
+        "ok": available,
+        "schema_version": UPDATE_PLAN_SCHEMA_VERSION,
+        "mode": "rollback",
+        "dry_run": False,
+        "execute_requested": True,
+        "requested_release_id": requested_release_id,
+        "current": {
+            "current_release_root": current_release_root,
+        },
+        "plan": {
+            "action": "rollback",
+            "available": available,
+            "reason": reason,
+            "releases_dir": str(releases_dir),
+            "release_count": len(releases),
+            "selected_release_id": selected_release_id,
+            "selected_release_root": selected_release_root,
+            "rollback_command": _rollback_release_command(requested_release_id),
+            "mutates_loopx_runtime_state": False,
+            "mutates_release_install": True,
+            "post_rollback_validation": "loopx doctor",
+        },
+        "execution": None,
+        "recommended_action": (
+            "rollback target selected; execute rollback and validate with doctor"
+            if available
+            else "choose an existing release id or use `loopx update --rollback previous` when available"
+        ),
+    }
+
+
+def build_update_plan(
+    *,
+    repo: str | None = None,
+    ref: str | None = None,
+    archive_url: str | None = None,
+    check_only: bool = False,
+    execute: bool = False,
+    doctor_payload: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    doctor = doctor_payload or collect_doctor()
+    install_freshness = (
+        doctor.get("install_freshness")
+        if isinstance(doctor.get("install_freshness"), dict)
+        else {}
+    )
+    release_manifest = (
+        doctor.get("release_manifest")
+        if isinstance(doctor.get("release_manifest"), dict)
+        else {}
+    )
+    release_manifest_body = (
+        release_manifest.get("manifest")
+        if isinstance(release_manifest.get("manifest"), dict)
+        else {}
+    )
+    source = _source_config(repo=repo, ref=ref, archive_url=archive_url)
+    install_command = _command_for_source(source)
+    dry_run = not execute
+    path = doctor.get("path") if isinstance(doctor.get("path"), dict) else {}
+    requires_upgrade = install_freshness.get("requires_upgrade")
+    current_version = install_freshness.get("current_version")
+    source_version_check = _source_version_check(source) if check_only else {
+        "schema_version": SOURCE_VERSION_CHECK_SCHEMA_VERSION,
+        "attempted": False,
+        "status": "not_requested",
+        "version": None,
+        "version_tag": None,
+        "matches_current": None,
+        "source_url": None,
+        "reason": "remote source comparison runs only for update --check",
+    }
+    source_version = source_version_check.get("version")
+    if source_version_check.get("status") == "available":
+        source_version_check["matches_current"] = (
+            source_version == current_version
+            if isinstance(current_version, str) and current_version
+            else None
+        )
+    runtime_activation = _runtime_activation_qualification(
+        install_freshness=install_freshness,
+        source=source,
+    )
+    if execute:
+        recommended_action = "review execution result and post-update doctor output"
+    elif (
+        check_only
+        and runtime_activation.get("decision")
+        == "release_or_install_successor_required"
+    ):
+        recommended_action = (
+            "installed runtime does not contain the trusted target source; "
+            "project a release/install successor, then run `loopx update --dry-run`"
+        )
+    elif check_only and source_version_check.get("matches_current") is False:
+        recommended_action = (
+            f"source version v{source_version} differs from installed version "
+            f"v{current_version}; run `loopx update --dry-run`, then `loopx update --execute`"
+        )
+    elif check_only and source_version_check.get("status") == "unavailable":
+        recommended_action = (
+            "local install health is known, but the selected source version could not be checked; "
+            "retry online or run `loopx update --execute` to refresh"
+        )
+    elif check_only and source_version_check.get("status") == "skipped":
+        recommended_action = (
+            "local install health is known, but source version comparison was skipped; "
+            "run `loopx update --dry-run` to review the source"
+        )
+    elif (
+        check_only
+        and runtime_activation.get("decision") == "activation_qualification_required"
+    ):
+        recommended_action = (
+            "installed runtime activation is not proven; refresh trusted source lineage "
+            "before claiming the merged behavior is active"
+        )
+    elif check_only and source_version_check.get("matches_current") is True and requires_upgrade is False:
+        recommended_action = "installed version and trusted source lineage match; no update needed"
+    elif check_only and requires_upgrade is True:
+        recommended_action = "run `loopx update --dry-run` to review the source and rollback plan"
+    elif requires_upgrade is False:
+        recommended_action = (
+            "no update needed; use `loopx update --dry-run` or "
+            "`loopx update --execute` only to force a refresh"
+        )
+    elif check_only:
+        recommended_action = "run `loopx update --dry-run` to review the source and rollback plan"
+    else:
+        recommended_action = "run `loopx update --execute` if you accept the source and rollback plan"
+    return {
+        "ok": True,
+        "schema_version": UPDATE_PLAN_SCHEMA_VERSION,
+        "mode": "update",
+        "check_only": check_only,
+        "dry_run": dry_run,
+        "execute_requested": execute,
+        "source": source,
+        "source_version_check": source_version_check,
+        "runtime_activation_qualification": runtime_activation,
+        "current": {
+            "loopx_command": path.get("loopx"),
+            "loopx_realpath": path.get("loopx_realpath"),
+            "current_version": current_version,
+            "current_version_tag": install_freshness.get("current_version_tag"),
+            "manifest_package_version": install_freshness.get("manifest_package_version"),
+            "manifest_package_version_tag": install_freshness.get("manifest_package_version_tag"),
+            "manifest_package_version_matches_runtime": install_freshness.get(
+                "manifest_package_version_matches_runtime"
+            ),
+            "release_id": install_freshness.get("release_id"),
+            "install_freshness_status": install_freshness.get("status"),
+            "requires_upgrade": requires_upgrade,
+            "reason": install_freshness.get("reason"),
+            "release_manifest_available": release_manifest.get("available"),
+            "release_manifest_path": release_manifest.get("path"),
+            "release_manifest": release_manifest_body,
+        },
+        "plan": {
+            "action": "check_only" if check_only else "execute_installer" if execute else "dry_run",
+            "install_command": install_command,
+            "post_update_validation": "loopx doctor",
+            "mutates_loopx_runtime_state": False,
+            "mutates_release_install": execute,
+            "backup": _rollback_plan(doctor),
+        },
+        "execution": None,
+        "recommended_action": recommended_action,
+    }
+
+
+def execute_update_plan(payload: dict[str, Any], *, timeout_seconds: int = 600) -> dict[str, Any]:
+    source = payload.get("source") if isinstance(payload.get("source"), dict) else {}
+    installer_url = str(source.get("installer_url") or NO_CLONE_INSTALL_URL)
+    plan = payload.get("plan") if isinstance(payload.get("plan"), dict) else {}
+    backup = plan.get("backup") if isinstance(plan.get("backup"), dict) else {}
+    current_release_root = backup.get("current_release_root")
+    env = _installer_env_for_source(
+        source,
+        current_release_root=(
+            current_release_root if isinstance(current_release_root, str) else None
+        ),
+    )
+    install_result = subprocess.run(
+        ["bash", "-lc", f"set -o pipefail; curl -fsSL {shlex.quote(installer_url)} | bash"],
+        text=True,
+        capture_output=True,
+        env=env,
+        timeout=timeout_seconds,
+    )
+    loopx_bin = Path.home() / ".local" / "bin" / "loopx"
+    doctor_result = subprocess.run(
+        [str(loopx_bin), "--format", "json", "doctor"],
+        text=True,
+        capture_output=True,
+        env=env,
+        timeout=timeout_seconds,
+    )
+    execution = {
+        "install_returncode": install_result.returncode,
+        "doctor_returncode": doctor_result.returncode,
+        "install_stdout_tail": install_result.stdout[-2000:],
+        "install_stderr_tail": install_result.stderr[-2000:],
+        "doctor_stdout_tail": doctor_result.stdout[-2000:],
+        "doctor_stderr_tail": doctor_result.stderr[-2000:],
+    }
+    updated = dict(payload)
+    updated["execution"] = execution
+    updated["ok"] = install_result.returncode == 0 and doctor_result.returncode == 0
+    if not updated["ok"]:
+        updated["recommended_action"] = "inspect update execution tails and restore from rollback plan if needed"
+    return updated
+
+
+def execute_rollback_plan(
+    payload: dict[str, Any],
+    *,
+    timeout_seconds: int = 600,
+    home: Path | None = None,
+) -> dict[str, Any]:
+    plan = payload.get("plan") if isinstance(payload.get("plan"), dict) else {}
+    selected_release_root = plan.get("selected_release_root")
+    if not payload.get("ok") or not selected_release_root:
+        return payload
+    release_root = Path(str(selected_release_root))
+    target_script = _release_script(release_root)
+    loopx_bin = _user_loopx_bin(home)
+    previous_link_target = os.readlink(loopx_bin) if loopx_bin.is_symlink() else None
+    execution: dict[str, Any] = {
+        "target_script": str(target_script),
+        "loopx_command": str(loopx_bin),
+        "previous_link_target": previous_link_target,
+        "restored_previous_on_failure": False,
+    }
+    updated = dict(payload)
+    try:
+        loopx_bin.parent.mkdir(parents=True, exist_ok=True)
+        temp_link = loopx_bin.with_name(f".{loopx_bin.name}.rollback.{os.getpid()}")
+        if temp_link.exists() or temp_link.is_symlink():
+            temp_link.unlink()
+        temp_link.symlink_to(target_script)
+        os.replace(temp_link, loopx_bin)
+        doctor_result = subprocess.run(
+            [str(loopx_bin), "--format", "json", "doctor"],
+            text=True,
+            capture_output=True,
+            timeout=timeout_seconds,
+        )
+        execution.update(
+            {
+                "doctor_returncode": doctor_result.returncode,
+                "doctor_stdout_tail": doctor_result.stdout[-2000:],
+                "doctor_stderr_tail": doctor_result.stderr[-2000:],
+            }
+        )
+        updated["ok"] = doctor_result.returncode == 0
+        if not updated["ok"] and previous_link_target:
+            restore_link = loopx_bin.with_name(f".{loopx_bin.name}.rollback.restore.{os.getpid()}")
+            if restore_link.exists() or restore_link.is_symlink():
+                restore_link.unlink()
+            restore_link.symlink_to(previous_link_target)
+            os.replace(restore_link, loopx_bin)
+            execution["restored_previous_on_failure"] = True
+    except Exception as exc:
+        execution["error"] = str(exc)
+        updated["ok"] = False
+        if previous_link_target:
+            restore_link = loopx_bin.with_name(f".{loopx_bin.name}.rollback.restore.{os.getpid()}")
+            try:
+                if restore_link.exists() or restore_link.is_symlink():
+                    restore_link.unlink()
+                restore_link.symlink_to(previous_link_target)
+                os.replace(restore_link, loopx_bin)
+                execution["restored_previous_on_failure"] = True
+            except Exception as restore_exc:
+                execution["restore_error"] = str(restore_exc)
+    finally:
+        if "temp_link" in locals() and (temp_link.exists() or temp_link.is_symlink()):
+            temp_link.unlink()
+        if "restore_link" in locals() and (restore_link.exists() or restore_link.is_symlink()):
+            restore_link.unlink()
+    updated["execution"] = execution
+    updated["recommended_action"] = (
+        "rollback complete; review doctor output"
+        if updated["ok"]
+        else "rollback failed; inspect execution error before retrying"
+    )
+    return updated
+
+
+def render_update_plan_markdown(payload: dict[str, Any]) -> str:
+    if payload.get("mode") == "rollback":
+        plan = payload.get("plan") if isinstance(payload.get("plan"), dict) else {}
+        execution = payload.get("execution") if isinstance(payload.get("execution"), dict) else None
+        lines = [
+            "# LoopX Update Rollback",
+            "",
+            f"- OK: `{payload.get('ok')}`",
+            f"- Requested release: `{payload.get('requested_release_id')}`",
+            f"- Selected release: `{plan.get('selected_release_id')}`",
+            f"- Selected root: `{plan.get('selected_release_root')}`",
+            f"- Reason: `{plan.get('reason')}`",
+            f"- Runtime state mutation: `{plan.get('mutates_loopx_runtime_state')}`",
+            f"- Release install mutation: `{plan.get('mutates_release_install')}`",
+            f"- Recommended action: {payload.get('recommended_action')}",
+        ]
+        rollback_command = plan.get("rollback_command")
+        if rollback_command:
+            lines.extend(["", "## Rollback Command", "", "```bash", str(rollback_command), "```"])
+        if execution:
+            lines.extend(
+                [
+                    "",
+                    "## Execution",
+                    "",
+                    f"- Doctor return code: `{execution.get('doctor_returncode')}`",
+                ]
+            )
+        return "\n".join(lines) + "\n"
+
+    source = payload.get("source") if isinstance(payload.get("source"), dict) else {}
+    source_version_check = (
+        payload.get("source_version_check")
+        if isinstance(payload.get("source_version_check"), dict)
+        else {}
+    )
+    runtime_activation = (
+        payload.get("runtime_activation_qualification")
+        if isinstance(payload.get("runtime_activation_qualification"), dict)
+        else {}
+    )
+    current = payload.get("current") if isinstance(payload.get("current"), dict) else {}
+    plan = payload.get("plan") if isinstance(payload.get("plan"), dict) else {}
+    backup = plan.get("backup") if isinstance(plan.get("backup"), dict) else {}
+    lines = [
+        "# LoopX Update",
+        "",
+        f"- OK: `{payload.get('ok')}`",
+        f"- Mode: `{plan.get('action')}`",
+        f"- Dry run: `{payload.get('dry_run')}`",
+        f"- Source: `{source.get('repo')}` @ `{source.get('ref')}`",
+        f"- Source version check: `{source_version_check.get('status')}`",
+        f"- Source version: `{source_version_check.get('version')}`",
+        f"- Source version tag: `{source_version_check.get('version_tag')}`",
+        f"- Source version matches current: `{source_version_check.get('matches_current')}`",
+        f"- Source version check reason: `{source_version_check.get('reason')}`",
+        f"- Runtime activation decision: `{runtime_activation.get('decision')}`",
+        f"- Runtime active: `{runtime_activation.get('runtime_active')}`",
+        f"- Installed source commit: `{runtime_activation.get('installed_source_commit')}`",
+        f"- Target source commit: `{runtime_activation.get('target_source_commit')}`",
+        f"- Source revision relation: `{runtime_activation.get('revision_relation')}`",
+        f"- Runtime activation reason: `{runtime_activation.get('reason')}`",
+        f"- Current version: `{current.get('current_version')}`",
+        f"- Current version tag: `{current.get('current_version_tag')}`",
+        f"- Manifest package version: `{current.get('manifest_package_version')}`",
+        f"- Manifest package version tag: `{current.get('manifest_package_version_tag')}`",
+        f"- Manifest package matches runtime: `{current.get('manifest_package_version_matches_runtime')}`",
+        f"- Freshness: `{current.get('install_freshness_status')}`",
+        f"- Requires upgrade: `{current.get('requires_upgrade')}`",
+        f"- Runtime state mutation: `{plan.get('mutates_loopx_runtime_state')}`",
+        f"- Release install mutation: `{plan.get('mutates_release_install')}`",
+        f"- Rollback available: `{backup.get('available')}`",
+        f"- Recommended action: {payload.get('recommended_action')}",
+        "",
+        "## Install Command",
+        "",
+        "```bash",
+        str(plan.get("install_command") or ""),
+        "```",
+    ]
+    rollback_command = backup.get("rollback_command")
+    if rollback_command:
+        lines.extend(["", "## Rollback Command", "", "```bash", str(rollback_command), "```"])
+    execution = payload.get("execution")
+    if isinstance(execution, dict):
+        lines.extend(
+            [
+                "",
+                "## Execution",
+                "",
+                f"- Install return code: `{execution.get('install_returncode')}`",
+                f"- Doctor return code: `{execution.get('doctor_returncode')}`",
+            ]
+        )
+    return "\n".join(lines) + "\n"