railmux 0.4.0.dev22__tar.gz → 0.4.0.dev25__tar.gz

{railmux-0.4.0.dev22/src/railmux.egg-info → railmux-0.4.0.dev25}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: railmux
-Version: 0.4.0.dev22
+Version: 0.4.0.dev25
 Summary: Terminal UI to navigate, resume, and start Claude Code and Codex sessions
 Author-email: Rightglow <zhang.taian@foxmail.com>
 License-Expression: MIT

railmux-0.4.0.dev25/src/railmux/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.4.0.dev25"

{railmux-0.4.0.dev22 → railmux-0.4.0.dev25}/src/railmux/cli.py

@@ -442,9 +442,20 @@ def main(argv: list[str] | None = None) -> int:
             metavar="ARGS",
             help="a quoted group of ssh arguments for --remote",
         )
+        doctor_parser.add_argument(
+            "--remote-platform",
+            choices=("auto", "posix", "windows"),
+            default="auto",
+            help=(
+                "remote shell family for --remote: auto, posix, or windows "
+                "(default: auto)"
+            ),
+        )
         doctor_args = doctor_parser.parse_args(raw_args[1:])
         if doctor_args.ssh_arg and not doctor_args.remote:
             doctor_parser.error("--ssh-args requires --remote")
+        if doctor_args.remote_platform != "auto" and not doctor_args.remote:
+            doctor_parser.error("--remote-platform requires --remote")
         if doctor_args.remote:
             from railmux.ssh_doctor import run_remote_ssh_doctor
 
@@ -452,6 +463,7 @@ def main(argv: list[str] | None = None) -> int:
                 doctor_args.remote,
                 ssh_args=doctor_args.ssh_arg,
                 json_output=doctor_args.json,
+                remote_platform=doctor_args.remote_platform,
             )
         return run_doctor(
             claude_home=Path(doctor_args.claude_home),
@@ -630,6 +642,7 @@ def main(argv: list[str] | None = None) -> int:
             tmux_server.target_session_id(dedicated_target, "railmux")
             if dedicated_target is not None else None
         )
+        created_detached_session = False
         if dedicated_target is not None and dedicated_session_id is None:
             from railmux.provider_paths import (
                 running_in_managed_windows_wrapper,
@@ -644,6 +657,34 @@ def main(argv: list[str] | None = None) -> int:
                         initial_size=_interactive_terminal_size(),
                     )
                 )
+                created_detached_session = dedicated_session_id is not None
+        if (
+            dedicated_target is not None
+            and dedicated_session_id is not None
+            and not created_detached_session
+        ):
+            from railmux.provider_paths import running_in_managed_windows_wrapper
+
+            if running_in_managed_windows_wrapper():
+                from railmux.windows_ui_transition import ensure_current_ui
+
+                runtime_id = os.environ.get("RAILMUX_MSYS2_RUNTIME_ID", "")
+                app_id = os.environ.get("RAILMUX_MSYS2_APP_ID", "")
+                transition = ensure_current_ui(
+                    dedicated_target,
+                    dedicated_session_id,
+                    runtime=runtime_id,
+                    target_app=app_id,
+                    target_version=__version__,
+                )
+                if transition.status in {"legacy", "pending", "blocked"}:
+                    detail = transition.detail or "the running UI was unchanged"
+                    print(
+                        "info: the Windows app-layer update is pending; "
+                        f"{detail}. Soft Quit the existing UI, then run "
+                        "'railmux' again to finish it.",
+                        file=sys.stderr,
+                    )
         cmd = tmux_server.launcher_argv(launch_prefix, raw_args)
         return _run_tmux_client_with_watchdog(
             cmd,
@@ -676,6 +717,27 @@ def main(argv: list[str] | None = None) -> int:
         ),
     )
     app.run()
+    request = getattr(app, "_ui_upgrade_request", None)
+    if request is not None:
+        from railmux.windows_ui_transition import UpgradeRequest, upgrade_exec_argv
+
+        # Mocked or partially constructed App objects must not manufacture an
+        # upgrade merely by dynamically answering arbitrary attributes.
+        if not isinstance(request, UpgradeRequest):
+            return 0
+
+        upgrade_argv = upgrade_exec_argv(request, [sys.argv[0], *raw_args])
+        if upgrade_argv is None:
+            print(
+                "error: the requested Windows app layer no longer validates; "
+                "run 'railmux runtime status --verify'",
+                file=sys.stderr,
+            )
+            return 2
+        upgrade_env = os.environ.copy()
+        upgrade_env["RAILMUX_MSYS2_RUNTIME_ID"] = request.runtime
+        upgrade_env["RAILMUX_MSYS2_APP_ID"] = request.app
+        os.execve(upgrade_argv[0], upgrade_argv, upgrade_env)
     return 0
 
 

{railmux-0.4.0.dev22 → railmux-0.4.0.dev25}/src/railmux/config_cli.py

@@ -782,6 +782,15 @@ def main(
         metavar="HOST",
         help="edit the configuration owned by an SSH destination",
     )
+    parser.add_argument(
+        "--remote-platform",
+        choices=("auto", "posix", "windows"),
+        default="auto",
+        help=(
+            "remote shell family for --remote: auto, posix, or windows "
+            "(default: auto)"
+        ),
+    )
     parser.add_argument(
         "--ssh-arg",
         action=AppendSshArgument,
@@ -810,6 +819,8 @@ def main(
             parser.error("--remote and --remote-context cannot be combined")
         if args.ssh_arg and not args.remote:
             parser.error("--ssh-args requires --remote")
+        if args.remote_platform != "auto" and not args.remote:
+            parser.error("--remote-platform requires --remote")
     except SystemExit as exc:
         return int(exc.code)
     if args.remote:
@@ -819,6 +830,7 @@ def main(
             args.remote,
             ssh_args=args.ssh_arg,
             raw_argv=tuple([] if argv is None else argv),
+            remote_platform=args.remote_platform,
         )
     remote_context = bool(args.remote_context)
     stdin = sys.stdin if stdin is None else stdin

{railmux-0.4.0.dev22 → railmux-0.4.0.dev25}/src/railmux/diagnostics.py

@@ -38,7 +38,7 @@ from railmux.terminal_status import (
 _VERSION_RE = re.compile(
     r"(?<![A-Za-z0-9])v?(\d+(?:\.\d+){1,3}(?:[A-Za-z]|[-+][0-9A-Za-z.-]+)?)"
 )
-DOCTOR_SCHEMA_VERSION = 3
+DOCTOR_SCHEMA_VERSION = 4
 
 
 @dataclass(frozen=True)
@@ -79,6 +79,15 @@ class DirectoryDiagnostic:
     writable: bool
 
 
+@dataclass(frozen=True)
+class ManagedWindowsDiagnostic:
+    runtime_id: str | None
+    app_version: str | None
+    base_content_id: str | None
+    running_ui_version: str | None
+    transition_status: str | None
+
+
 @dataclass(frozen=True)
 class DoctorSnapshot:
     """Versioned, privacy-safe authority shared by text and JSON output."""
@@ -103,6 +112,7 @@ class DoctorSnapshot:
     preferred_agent_display: str
     data_directories: dict[str, DirectoryDiagnostic]
     ssh_display: SshDisplayDiagnostic
+    managed_windows: ManagedWindowsDiagnostic | None = None
 
 
 def is_ssh_session(environ: dict[str, str] | None = None) -> bool:
@@ -350,6 +360,11 @@ def collect_doctor_snapshot(
             else _legacy_tmux_diagnostic()
         )
     )
+    managed_windows = None
+    if running_in_windows_wrapper(env):
+        from railmux.windows_ui_transition import diagnostic_status
+
+        managed_windows = ManagedWindowsDiagnostic(**diagnostic_status(env))
     return DoctorSnapshot(
         schema_version=DOCTOR_SCHEMA_VERSION,
         railmux_version=__version__,
@@ -376,6 +391,7 @@ def collect_doctor_snapshot(
             ),
         },
         ssh_display=read_ssh_display_diagnostic(),
+        managed_windows=managed_windows,
     )
 
 
@@ -495,7 +511,7 @@ def _ssh_display_text(diagnostic: SshDisplayDiagnostic) -> str:
 
 def render_doctor_text(snapshot: DoctorSnapshot) -> str:
     """Render the stable human report from the structured authority."""
-    lines = (
+    lines = [
         "Railmux diagnostics",
         f"Railmux: {snapshot.railmux_version}",
         f"Python: {snapshot.python_version}",
@@ -525,6 +541,22 @@ def render_doctor_text(snapshot: DoctorSnapshot) -> str:
         f"Config: {_config_text(snapshot.config)}",
         "Settings repair: run 'railmux config' (no tmux required)",
         f"Preferred agent display: {snapshot.preferred_agent_display}",
+    ]
+    if snapshot.managed_windows is not None:
+        managed = snapshot.managed_windows
+        identity = (
+            managed.base_content_id[:12]
+            if managed.base_content_id is not None
+            else "unavailable"
+        )
+        lines.extend((
+            f"Windows managed runtime: {managed.runtime_id or 'unavailable'}; "
+            f"content={identity}",
+            f"Windows app layer: installed={managed.app_version or 'unavailable'}, "
+            f"running={managed.running_ui_version or 'not running'}, "
+            f"transition={managed.transition_status or 'none'}",
+        ))
+    lines.extend((
         (
             "Most recent railmux ssh (host not recorded): "
             f"{_ssh_display_text(snapshot.ssh_display)}"
@@ -535,7 +567,7 @@ def render_doctor_text(snapshot: DoctorSnapshot) -> str:
             "Privacy: session IDs, transcript content, credentials, hostnames, "
             "and raw custom paths are omitted; review before sharing."
         ),
-    )
+    ))
     return "\n".join(lines)
 
 

{railmux-0.4.0.dev22 → railmux-0.4.0.dev25}/src/railmux/fast_display_client.py

@@ -281,6 +281,7 @@ class RemoteHello:
     config_status: str = "valid"
     tmux_configured: bool = False
     config_protocol: int = 0
+    platform: str = "posix"
 
 
 @dataclass(frozen=True)
@@ -296,6 +297,11 @@ class RemoteStartKind(Enum):
     TIMEOUT = "timeout"
 
 
+class RemoteLaunchMode(Enum):
+    POSIX = "posix"
+    DIRECT = "direct"
+
+
 class RemoteAttachKind(Enum):
     ACCEPTED = "accepted"
     BUSY = "busy"
@@ -310,6 +316,15 @@ class RemoteStartup:
     returncode: int | None = None
 
 
+@dataclass(frozen=True)
+class RemoteProbe:
+    """One cooked-mode launch-family probe before any attach mutation."""
+
+    process: subprocess.Popen
+    startup: RemoteStartup
+    launch_mode: RemoteLaunchMode
+
+
 def await_remote_attach_status(
     process: subprocess.Popen,
     timeout: float = _REMOTE_ATTACH_TIMEOUT,
@@ -369,6 +384,7 @@ def parse_remote_hello(line: bytes) -> RemoteHello:
     config_status = value.get("config_status", "valid")
     tmux_configured = value.get("tmux_configured", False)
     config_protocol = value.get("config_protocol", 0)
+    platform = value.get("platform", "posix")
     if (
         not isinstance(version, str)
         or not version
@@ -383,6 +399,7 @@ def parse_remote_hello(line: bytes) -> RemoteHello:
         or not isinstance(config_protocol, int)
         or isinstance(config_protocol, bool)
         or not 0 <= config_protocol <= 65535
+        or platform not in {"posix", "windows-msys2"}
     ):
         raise ValueError("invalid Railmux remote hello")
     try:
@@ -397,6 +414,7 @@ def parse_remote_hello(line: bytes) -> RemoteHello:
         config_status,
         tmux_configured,
         config_protocol,
+        platform,
     )
 
 
@@ -1540,12 +1558,18 @@ def _remote_launch_command(server_args: Sequence[str]) -> str:
     return "; ".join(branches)
 
 
+def _remote_direct_launch_command(server_args: Sequence[str]) -> str:
+    """Build a shell-neutral command accepted by Windows OpenSSH PowerShell."""
+    return shlex.join(["railmux", *server_args])
+
+
 def build_remote_command_argv(
     destination: str,
     *,
     remote_args: Sequence[str],
     ssh_args: Sequence[str],
     force_tty: bool = False,
+    launch_mode: RemoteLaunchMode = RemoteLaunchMode.POSIX,
 ) -> list[str]:
     """Build SSH argv through the shared remote Railmux discovery ladder."""
     return [
@@ -1556,10 +1580,83 @@ def build_remote_command_argv(
         # user arguments so a copied -t/-T flag cannot invert the transport.
         "-tt" if force_tty else "-T",
         destination,
-        _remote_launch_command(remote_args),
+        (
+            _remote_direct_launch_command(remote_args)
+            if launch_mode is RemoteLaunchMode.DIRECT
+            else _remote_launch_command(remote_args)
+        ),
     ]
 
 
+def probe_remote_launch(
+    destination: str,
+    *,
+    remote_args: Sequence[str],
+    ssh_args: Sequence[str],
+    remote_platform: str = "auto",
+    force_tty: bool = False,
+    timeout: float = _REMOTE_HELLO_TIMEOUT,
+) -> RemoteProbe:
+    """Probe one remote Railmux command and pin its shell launch family.
+
+    ``auto`` preserves the POSIX discovery ladder, then makes one direct
+    shell-neutral attempt only after a non-SSH launch failure.  Each shell
+    family receives the full bounded startup timeout.  Explicit Windows mode
+    requires a managed Windows hello; auto mode accepts an authoritative POSIX
+    hello reached through a shell-neutral direct command.
+    """
+    if remote_platform not in {"auto", "posix", "windows"}:
+        raise ValueError("invalid remote platform")
+    launch_mode = (
+        RemoteLaunchMode.DIRECT
+        if remote_platform == "windows"
+        else RemoteLaunchMode.POSIX
+    )
+    effective_ssh_args = (
+        *ssh_args,
+        "-o",
+        "ServerAliveInterval=5",
+        "-o",
+        "ServerAliveCountMax=3",
+    )
+
+    def start(mode: RemoteLaunchMode) -> tuple[subprocess.Popen, RemoteStartup]:
+        argv = build_remote_command_argv(
+            destination,
+            remote_args=remote_args,
+            ssh_args=effective_ssh_args,
+            force_tty=force_tty,
+            launch_mode=mode,
+        )
+        process = _spawn_remote(argv)
+        startup = await_remote_startup(process, timeout=timeout)
+        return process, startup
+
+    process, startup = start(launch_mode)
+    if (
+        remote_platform == "auto"
+        and launch_mode is RemoteLaunchMode.POSIX
+        and startup.kind is RemoteStartKind.FAILED
+        and startup.returncode != 255
+    ):
+        _stop_unstarted_remote(process)
+        launch_mode = RemoteLaunchMode.DIRECT
+        process, startup = start(launch_mode)
+
+    if (
+        startup.kind is RemoteStartKind.HELLO
+        and startup.hello is not None
+        and remote_platform == "windows"
+        and startup.hello.platform != "windows-msys2"
+    ):
+        _stop_unstarted_remote(process)
+        raise ProbeError(
+            "the direct remote launcher answered from a non-Windows Railmux "
+            "runtime; use --remote-platform posix for that host"
+        )
+    return RemoteProbe(process, startup, launch_mode)
+
+
 def build_ssh_argv(
     destination: str,
     *,
@@ -1570,6 +1667,7 @@ def build_ssh_argv(
     ssh_args: Sequence[str],
     replace_existing_client: bool = False,
     existing_session_only: bool = False,
+    launch_mode: RemoteLaunchMode = RemoteLaunchMode.POSIX,
 ) -> list[str]:
     server_args = _remote_server_args(
         session=session,
@@ -1592,6 +1690,7 @@ def build_ssh_argv(
             "-o",
             "ServerAliveCountMax=3",
         ),
+        launch_mode=launch_mode,
     )
 
 
@@ -1757,6 +1856,55 @@ def remote_install_help(destination: str, version: str) -> str:
     )
 
 
+def remote_windows_install_help(destination: str, version: str) -> str:
+    return (
+        f"Update the user-level Windows preview on {destination} from "
+        "PowerShell, then retry:\n"
+        f"  py -m pip install --upgrade railmux=={version}\n"
+        "  railmux runtime install --yes\n"
+        "The runtime command installs only the matching Railmux app layer and "
+        "reuses a verified managed MSYS2 base when its pinned version is "
+        "unchanged. It does not modify Codex or Claude session files. If 'py' "
+        "is unavailable, use the same Windows Python executable that installed "
+        "the Railmux command."
+    )
+
+
+def local_windows_update_help(version: str) -> str:
+    """Return the native-owner update path for a managed Windows client."""
+    return (
+        "Update this Windows Railmux installation from PowerShell, then "
+        "retry:\n"
+        f"  py -m pip install --upgrade railmux=={version}\n"
+        "  railmux runtime install --yes\n"
+        "Do not update the versioned MSYS2 app environment with its private "
+        "pip; the native bootstrap owns application-layer installation."
+    )
+
+
+def _remote_launch_mode(args: argparse.Namespace) -> RemoteLaunchMode:
+    selected = getattr(args, "_selected_remote_launch_mode", None)
+    if isinstance(selected, RemoteLaunchMode):
+        return selected
+    if getattr(args, "remote_platform", "auto") == "windows":
+        return RemoteLaunchMode.DIRECT
+    return RemoteLaunchMode.POSIX
+
+
+def _remember_remote_launch_mode(
+    args: argparse.Namespace, mode: RemoteLaunchMode
+) -> None:
+    args._selected_remote_launch_mode = mode
+
+
+def _remote_uses_windows_runtime(
+    args: argparse.Namespace, hello: RemoteHello | None = None
+) -> bool:
+    if hello is not None:
+        return hello.platform == "windows-msys2"
+    return _remote_launch_mode(args) is RemoteLaunchMode.DIRECT
+
+
 def remote_tmux_help(destination: str) -> str:
     return (
         f"tmux is not installed or not on PATH on {destination}. Install it "
@@ -1823,8 +1971,12 @@ def _upgrade_local_and_restart(
     *,
     subcommand: str = "ssh",
 ) -> NoReturn:
+    from railmux.provider_paths import running_in_windows_wrapper
     from railmux.self_update import installed_version_matches
 
+    if running_in_windows_wrapper():
+        raise ProbeError(local_windows_update_help(version))
+
     argv = _local_upgrade_argv(version)
     command_label = f"railmux {subcommand}"
     print(
@@ -1989,6 +2141,7 @@ def _reconnect_remote_attach(
         ssh_args=ssh_args,
         replace_existing_client=replace_existing_client,
         existing_session_only=existing_session_only,
+        launch_mode=_remote_launch_mode(args),
     )
     process = (
         _spawn_remote(argv, suppress_stderr=True)
@@ -2215,18 +2368,55 @@ def prepare_remote_process(
         if before_interaction is not None:
             before_interaction()
 
-    argv = build_ssh_argv(
-        args.destination,
+    if on_stage is not None:
+        on_stage("Connecting to remote host…")
+    remote_args = _remote_server_args(
         session=args.session,
         width=current_size.columns,
         height=current_size.lines,
         fps=args.fps,
+    )
+    probe = probe_remote_launch(
+        args.destination,
+        remote_args=remote_args,
         ssh_args=args.ssh_arg,
+        remote_platform=getattr(args, "remote_platform", "auto"),
     )
-    if on_stage is not None:
-        on_stage("Connecting to remote host…")
-    process = _spawn_remote(argv)
-    startup = await_remote_startup(process)
+    process = probe.process
+    startup = probe.startup
+    launch_mode = probe.launch_mode
+    if startup.kind is RemoteStartKind.HELLO:
+        _remember_remote_launch_mode(args, launch_mode)
+    elif (
+        getattr(args, "remote_platform", "auto") == "auto"
+        and launch_mode is RemoteLaunchMode.DIRECT
+    ):
+        _stop_unstarted_remote(process)
+        if startup.returncode == 255:
+            raise ProbeError("ssh could not connect to the remote host")
+        if startup.kind is RemoteStartKind.TIMEOUT:
+            raise ProbeError(
+                "timed out while checking the remote host's direct Railmux launcher"
+            )
+        raise ProbeError(
+            "the remote shell did not accept the POSIX discovery command, "
+            "and a direct Railmux launch did not complete. If this is a "
+            "Windows preview host:\n"
+            f"{remote_windows_install_help(args.destination, __version__)}"
+        )
+
+    if (
+        getattr(args, "remote_platform", "auto") == "windows"
+        and startup.kind is not RemoteStartKind.HELLO
+    ):
+        _stop_unstarted_remote(process)
+        if startup.returncode == 255:
+            raise ProbeError("ssh could not connect to the remote host")
+        if startup.kind is RemoteStartKind.TIMEOUT:
+            raise ProbeError(
+                "timed out waiting for the Windows Railmux compatibility handshake"
+            )
+        raise ProbeError(remote_windows_install_help(args.destination, __version__))
     install_version = __version__
     install_reason: str | None = None
     if startup.kind is RemoteStartKind.MISSING:
@@ -2281,6 +2471,12 @@ def prepare_remote_process(
             if decision.action == "prompt" and decision.prompt == "remote_install":
                 assert decision.reason is not None
                 assert decision.install_version is not None
+                if _remote_uses_windows_runtime(args, hello):
+                    _stop_unstarted_remote(process)
+                    raise ProbeError(
+                        f"{decision.reason}\n"
+                        f"{remote_windows_install_help(args.destination, decision.install_version)}"
+                    )
                 consents["remote_install"] = _confirm_remote_install(
                     args,
                     decision.reason,
@@ -2295,9 +2491,14 @@ def prepare_remote_process(
                 _stop_unstarted_remote(process)
                 message = decision.reason or "incompatible remote Railmux"
                 if decision.install_version is not None:
+                    install_help = (
+                        remote_windows_install_help
+                        if _remote_uses_windows_runtime(args, hello)
+                        else remote_install_help
+                    )
                     message = (
                         f"{message}\n"
-                        f"{remote_install_help(args.destination, decision.install_version)}"
+                        f"{install_help(args.destination, decision.install_version)}"
                     )
                 raise ProbeError(message)
             if decision.warning is not None:
@@ -2320,6 +2521,14 @@ def prepare_remote_process(
             raise AssertionError(f"unknown compatibility action: {decision.action}")
 
     assert install_reason is not None
+    if _remote_uses_windows_runtime(
+        args, startup.hello if startup.kind is RemoteStartKind.HELLO else None
+    ):
+        _stop_unstarted_remote(process)
+        raise ProbeError(
+            f"{install_reason}\n"
+            f"{remote_windows_install_help(args.destination, install_version)}"
+        )
     if startup.kind is not RemoteStartKind.HELLO and not _confirm_remote_install(
         args,
         install_reason,
@@ -2430,6 +2639,16 @@ def parse_args(argv: Optional[Sequence[str]] = None) -> argparse.Namespace:
         default=20.0,
         help="maximum coalesced display update rate, 1-60 (default: 20)",
     )
+    parser.add_argument(
+        "--remote-platform",
+        choices=("auto", "posix", "windows"),
+        default="auto",
+        help=(
+            "remote shell family: auto tries POSIX discovery then direct "
+            "Windows launch; windows avoids the failed POSIX probe and an "
+            "extra password prompt (default: auto)"
+        ),
+    )
     parser.add_argument(
         "--no-mouse",
         action="store_true",

{railmux-0.4.0.dev22 → railmux-0.4.0.dev25}/src/railmux/fast_display_server.py

@@ -248,6 +248,11 @@ def _emit_remote_hello(
             "config_status": config_status,
             "tmux_configured": tmux_configured,
             "config_protocol": REMOTE_CONFIG_PROTOCOL,
+            "platform": (
+                "windows-msys2"
+                if os.environ.get("RAILMUX_WINDOWS_RUNTIME") == "msys2"
+                else "posix"
+            ),
             "version": __version__,
         },
         separators=(",", ":"),

{railmux-0.4.0.dev22 → railmux-0.4.0.dev25}/src/railmux/provider_paths.py

@@ -12,6 +12,7 @@ from pathlib import Path
 
 _DRIVE_PATH = re.compile(r"^(?:\\\\\?\\)?([A-Za-z]):[\\/](.*)\Z")
 _MANAGED_BASE_MARKER = Path("/railmux-base.json")
+_MANAGED_BASE_CONTENT_MARKER = Path("/railmux-base-content-v1.json")
 _MANAGED_APP_ROOT = Path("/opt/railmux/apps")
 _MANAGED_APP_ID = re.compile(
     r"railmux-[0-9]+(?:\.[0-9]+)*(?:\.dev[0-9]+)?\Z"
@@ -59,14 +60,34 @@ def running_in_managed_windows_wrapper(
     )
     from railmux import __version__
 
-    return base_payload == {
+    base_valid = base_payload == {
         "schema": 1,
         "runtime": runtime_id,
-    } and app_payload == {
+    }
+    legacy_app = app_payload == {
         "schema": 1,
         "runtime": runtime_id,
         "railmux": __version__,
     }
+    content_payload = read_safe_marker(_MANAGED_BASE_CONTENT_MARKER)
+    content_id = (
+        content_payload.get("content_id")
+        if isinstance(content_payload, dict)
+        and content_payload.get("schema") == 1
+        and content_payload.get("runtime") == runtime_id
+        else None
+    )
+    exact_app = bool(
+        isinstance(content_id, str)
+        and re.fullmatch(r"[0-9a-f]{64}", content_id)
+        and app_payload == {
+            "schema": 2,
+            "runtime": runtime_id,
+            "railmux": __version__,
+            "base_content_id": content_id,
+        }
+    )
+    return base_valid and (legacy_app or exact_app)
 
 
 def private_mode_is_safe(mode: int) -> bool: