fix(cli): print host-runnable install guidance in the connect hint

loopx/bootstrap.py

@@ -38,8 +38,8 @@
 )
 from .global_registry import sync_project_registry_to_global
 from .install_contract import (
-    ARCHIVE_FALLBACK_INSTALL_COMMAND,
-    DEFAULT_INSTALL_REPAIR_COMMAND,
+    archive_fallback_install_command,
+    install_repair_command,
 )
 from .orchestration import (
     DEFAULT_ORCHESTRATION_MODE,
@@ -504,8 +504,8 @@ def bootstrap_project(
                     "Fix global registry write access, then rerun this command.",
                     "Use --no-global-sync only for an explicit local-only setup.",
                 ],
-                "install_repair_command": DEFAULT_INSTALL_REPAIR_COMMAND,
-                "archive_fallback_install_command": ARCHIVE_FALLBACK_INSTALL_COMMAND,
+                "install_repair_command": install_repair_command(),
+                "archive_fallback_install_command": archive_fallback_install_command(),
                 "install_repair_note": (
                     "If this local LoopX install is missing or stale, repair the PyPI distribution "
                     "and packaged workflow skills, then confirm with loopx doctor before continuing."
@@ -665,8 +665,8 @@ def bootstrap_project(
             f"loopx --registry {runtime_root / 'registry.global.json'} status",
             f"loopx --registry {relative_state_file(project, registry_path)} history --goal-id {goal_id}",
         ],
-        "install_repair_command": DEFAULT_INSTALL_REPAIR_COMMAND,
-        "archive_fallback_install_command": ARCHIVE_FALLBACK_INSTALL_COMMAND,
+        "install_repair_command": install_repair_command(),
+        "archive_fallback_install_command": archive_fallback_install_command(),
         "install_repair_note": (
             "If this local LoopX install is missing or stale, repair the PyPI distribution "
             "and packaged workflow skills, then confirm with loopx doctor before continuing."

loopx/doctor.py

@@ -17,7 +17,11 @@
     PROMOTION_READINESS_RUNTIME_INDEX,
 )
 from .control_plane.runtime.time import chronology_key
-from .install_contract import NO_CLONE_INSTALL_URL
+from .install_contract import (
+    NO_CLONE_INSTALL_URL,
+    local_install_command,
+    no_clone_upgrade_command,
+)
 from .paths import configured_runtime_route, default_runtime_route, global_registry_path
 from .python_install_owner import PythonInstallOwner, python_distribution_upgrade_command, resolve_python_install_owner
 from .capabilities.project_skill_delivery import discover_project_scoped_skill_ids
@@ -81,62 +85,6 @@
 }
 
 
-def _powershell_literal(value: str | Path) -> str:
-    return "'" + str(value).replace("'", "''") + "'"
-
-
-def local_install_command(repo_root: Path, *, skip_skills: bool = False) -> str:
-    if os.name == "nt":
-        return (
-            "pwsh -NoLogo -NoProfile -File "
-            f"{_powershell_literal(repo_root / 'scripts' / 'install-windows.ps1')} "
-            f"-Python {_powershell_literal(sys.executable)}"
-            + (" -SkipSkills" if skip_skills else "")
-        )
-    command = str(repo_root / "scripts" / "install-local.sh")
-    return f"LOOPX_INSTALL_SKILL=0 {command}" if skip_skills else command
-
-
-def no_clone_upgrade_command(
-    source_ref: Any = None,
-    *,
-    doctor_agent_type: str | None = None,
-    skip_skills: bool = False,
-) -> str:
-    if os.name == "nt":
-        repo_root = Path(__file__).resolve().parents[1]
-        doctor_agent_arg = (
-            f" --agent-type {_powershell_literal(doctor_agent_type)}"
-            if doctor_agent_type
-            else ""
-        )
-        return (
-            f"{local_install_command(repo_root, skip_skills=skip_skills)}\n"
-            f"loopx doctor{doctor_agent_arg}"
-        )
-    ref = str(source_ref or "").strip()
-    installer = f"curl -fsSL {NO_CLONE_INSTALL_URL}"
-    doctor_agent_arg = (
-        f" --agent-type {shlex.quote(doctor_agent_type)}"
-        if doctor_agent_type
-        else ""
-    )
-    install_env: list[str] = []
-    if ref and ref != "stable":
-        install_env.append(f"LOOPX_REF={shlex.quote(ref)}")
-    if skip_skills:
-        install_env.append("LOOPX_INSTALL_SKILL=0")
-    if install_env:
-        installer = f"{installer} | env {' '.join(install_env)} bash"
-    else:
-        installer = f"{installer} | bash"
-    return (
-        f"{installer}\n"
-        'export PATH="$HOME/.local/bin:$PATH"\n'
-        f"loopx doctor{doctor_agent_arg}"
-    )
-
-
 def user_local_bin() -> Path:
     return Path.home() / ".local" / "bin"
 

loopx/install_contract.py

@@ -1,3 +1,21 @@
+"""Install, repair, and fallback command text printed to LoopX operators.
+
+One platform-aware owner keeps the bootstrap/connect hint, the doctor freshness
+command, and the archive fallback consistent. POSIX keeps the documented public
+defaults; native Windows has neither a ``python3`` launcher nor Bash, so it
+names the interpreter that runs here and prints the snapshot installer only for a
+checkout that actually ships it.
+"""
+
+from __future__ import annotations
+
+import os
+import shlex
+import sys
+from pathlib import Path
+from typing import Any
+
+
 NO_CLONE_INSTALL_URL = "https://loopx-project.github.io/loopx/install.sh"
 
 DEFAULT_INSTALL_COMMAND = "python3 -m pip install --upgrade loopx"
@@ -12,3 +30,110 @@
     'export PATH="$HOME/.local/bin:$PATH"\n'
     "loopx doctor"
 )
+
+
+def _powershell_literal(value: str | Path) -> str:
+    return "'" + str(value).replace("'", "''") + "'"
+
+
+def _is_windows_host() -> bool:
+    """Whether printed commands target PowerShell instead of a POSIX shell."""
+
+    return os.name == "nt"
+
+
+def _checkout_snapshot_installer(repo_root: Path) -> Path | None:
+    """The snapshot installer only when this module runs from the checkout that owns it.
+
+    An installed distribution places this module under site-packages, which does not
+    ship ``scripts/install-windows.ps1``. Printing that path would hand the operator a
+    ``pwsh -File`` command PowerShell rejects, so the project marker and the script
+    itself decide whether the checkout route is real.
+    """
+
+    installer = repo_root / "scripts" / "install-windows.ps1"
+    if installer.is_file() and (repo_root / "pyproject.toml").is_file():
+        return installer
+    return None
+
+
+def _windows_pypi_upgrade_command(*, doctor_agent_arg: str, skip_skills: bool) -> str:
+    """No-clone upgrade through the interpreter that owns this installation."""
+
+    lines = [f"& {_powershell_literal(sys.executable)} -m pip install --upgrade loopx"]
+    if not skip_skills:
+        lines.append(DEFAULT_WORKFLOW_SKILL_INSTALL_COMMAND)
+    lines.append(f"loopx doctor{doctor_agent_arg}")
+    return "\n".join(lines)
+
+
+def local_install_command(repo_root: Path, *, skip_skills: bool = False) -> str:
+    if _is_windows_host():
+        return (
+            "pwsh -NoLogo -NoProfile -File "
+            f"{_powershell_literal(repo_root / 'scripts' / 'install-windows.ps1')} "
+            f"-Python {_powershell_literal(sys.executable)}"
+            + (" -SkipSkills" if skip_skills else "")
+        )
+    command = str(repo_root / "scripts" / "install-local.sh")
+    return f"LOOPX_INSTALL_SKILL=0 {command}" if skip_skills else command
+
+
+def no_clone_upgrade_command(
+    source_ref: Any = None,
+    *,
+    doctor_agent_type: str | None = None,
+    skip_skills: bool = False,
+) -> str:
+    if _is_windows_host():
+        repo_root = Path(__file__).resolve().parents[1]
+        doctor_agent_arg = (
+            f" --agent-type {_powershell_literal(doctor_agent_type)}"
+            if doctor_agent_type
+            else ""
+        )
+        if _checkout_snapshot_installer(repo_root) is not None:
+            return (
+                f"{local_install_command(repo_root, skip_skills=skip_skills)}\n"
+                f"loopx doctor{doctor_agent_arg}"
+            )
+        return _windows_pypi_upgrade_command(
+            doctor_agent_arg=doctor_agent_arg, skip_skills=skip_skills
+        )
+    ref = str(source_ref or "").strip()
+    installer = f"curl -fsSL {NO_CLONE_INSTALL_URL}"
+    doctor_agent_arg = (
+        f" --agent-type {shlex.quote(doctor_agent_type)}"
+        if doctor_agent_type
+        else ""
+    )
+    install_env: list[str] = []
+    if ref and ref != "stable":
+        install_env.append(f"LOOPX_REF={shlex.quote(ref)}")
+    if skip_skills:
+        install_env.append("LOOPX_INSTALL_SKILL=0")
+    if install_env:
+        installer = f"{installer} | env {' '.join(install_env)} bash"
+    else:
+        installer = f"{installer} | bash"
+    return (
+        f"{installer}\n"
+        'export PATH="$HOME/.local/bin:$PATH"\n'
+        f"loopx doctor{doctor_agent_arg}"
+    )
+
+
+def install_repair_command() -> str:
+    """PyPI repair guidance that runs as printed on this host."""
+
+    if _is_windows_host():
+        return _windows_pypi_upgrade_command(doctor_agent_arg="", skip_skills=False)
+    return DEFAULT_INSTALL_REPAIR_COMMAND
+
+
+def archive_fallback_install_command() -> str:
+    """Archive fallback guidance that runs as printed on this host."""
+
+    if _is_windows_host():
+        return no_clone_upgrade_command()
+    return ARCHIVE_FALLBACK_INSTALL_COMMAND