ODS V3 Pre-Release: Public testing and refinement ahead of the official V3 launch. Turn your PC, Mac, or Linux box into a private AI server.
Python ai-agentsamdcomfyuidockerllama-cppllmlocal-ain8nnvidiaopen-webuiragself-hostedspeech-to-textstrix-halotext-to-speechworkflow-automation
"""Bounded access to this WSL installation's owned Windows llama-server task.
This is a finite PowerShell command, not a server. The controller is the
authority for task/process ownership; a flag or reachable port never is.
The plan schema and controller protocol are runtime-neutral: the plan's
``ExecutablePath`` names the pinned ``llama-server.exe``.
"""
from __future__ import annotations
import json
import logging
import math
import os
from pathlib import Path, PureWindowsPath
import platform
import re
import shutil
import stat
import subprocess
import threading
import time
from typing import NamedTuple
from urllib.parse import urlsplit
_LIMIT = 65536
_WSLPATH = "/usr/bin/wslpath"
_CONTROLLER = "installers/windows/portal-model-control.ps1"
_SOURCE = Path(__file__).resolve().parents[2]
_DIGEST = re.compile(r"[0-9a-f]{64}")
_PLAN_KEYS = {"ExecutablePath", "Port", "ModelsDir", "ContextSize", "GgufFile",
"WslDistro", "WslInstallDir"}
# A vision model's projector, beside its weights. Only a launcher whose
# options declare it (status ``planFeatures``) is planned one.
_PROJECTOR_KEY = "MmprojFile"
TRANSPORT_KEY = "ODS_HOST_LLM_TRANSPORT"
HOST_BASE_URL_KEY = "NATIVE_LLM_BASE_URL"
CONTAINER_BASE_URL_KEY = "NATIVE_LLM_CONTAINER_BASE_URL"
# Compatibility reads for one release: installations written before round F
# carry these names until their .env migration has run.
_LEGACY_KEYS = {
TRANSPORT_KEY: "LEMONADE_HOST_TRANSPORT",
HOST_BASE_URL_KEY: "LEMONADE_BASE_URL",
CONTAINER_BASE_URL_KEY: "LEMONADE_CONTAINER_BASE_URL",
}
_ENDPOINT_PATHS = {"", "/v1"}
_LEGACY_ENDPOINT_PATHS = {"", "/api", "/api/v1", "/v1"}
# Status may carry why the model is not running: the launcher's own error, at
# most 1024 printable characters, and on the CUDA route the memory refusal
# the owner can override with Start anyway (the next start of that plan).
_RUNTIME_ERROR_LIMIT = 1024
START_REFUSALS = frozenset({"memory_refused", "gpu_busy"})
def env_value(env: dict, key: str):
"""Return ``(name, value)`` for ``key`` or its one-release legacy name."""
if key in env:
return key, env[key]
legacy = _LEGACY_KEYS.get(key)
if legacy is not None and legacy in env:
return legacy, env[legacy]
return key, None
class BridgeError(OSError):
"""A rejected or uncertain controller operation; never retry blindly."""
def __init__(self, message: str, *, code: str = "wsl_runtime_unavailable", response=None):
super().__init__(message)
self.code = code
self.response = response or {}
digest = self.response.get("newPlanDigest")
self.new_plan_digest = digest if isinstance(digest, str) and _DIGEST.fullmatch(digest) else None
class _WindowsTools(NamedTuple):
shell: str
probe: str
module_path: str
class _Context(NamedTuple):
distro: str
install_dir: str
controller: str
windows: _WindowsTools
def _run(command: list[str], *, data: bytes | None = None, timeout: float = 10,
environ: dict | None = None) -> subprocess.CompletedProcess:
"""Bound memory as well as wall time, including a noisy/crashed controller."""
if not math.isfinite(timeout) or not 0 < timeout <= 1200:
raise ValueError("Invalid Windows controller deadline")
if data is not None and len(data) > _LIMIT:
raise ValueError("Windows controller request exceeds 64 KiB")
process = subprocess.Popen(command, stdin=subprocess.PIPE if data is not None else subprocess.DEVNULL,
stdout=subprocess.PIPE, stderr=subprocess.PIPE, env=environ)
output = {}
oversized = threading.Event()
def read(name, stream):
content = stream.read(_LIMIT + 1)
output[name] = content
if len(content) > _LIMIT:
oversized.set()
try:
process.kill()
except ProcessLookupError:
pass
stream.close()
def write():
try:
process.stdin.write(data)
process.stdin.flush()
except (BrokenPipeError, OSError):
pass # The bounded process result below is authoritative.
finally:
process.stdin.close()
threads = [threading.Thread(target=read, args=(name, stream), daemon=True)
for name, stream in (("stdout", process.stdout), ("stderr", process.stderr))]
if data is not None:
threads.append(threading.Thread(target=write, daemon=True))
for thread in threads:
thread.start()
try:
process.wait(timeout=timeout)
except subprocess.TimeoutExpired:
process.kill()
process.wait(timeout=5)
raise
finally:
for thread in threads:
thread.join(timeout=1)
if oversized.is_set() or any(thread.is_alive() for thread in threads):
raise BridgeError("Windows controller output exceeds its bounded contract")
return subprocess.CompletedProcess(command, process.returncode, output["stdout"], output["stderr"])
def _socket_identity(value: str):
"""Only root-owned WSL sockets in root-protected directories are eligible."""
if not isinstance(value, str) or not re.fullmatch(r"/run/WSL/[1-9][0-9]*_interop", value):
return None
try:
for parent in (Path("/run"), Path("/run/WSL")):
row = parent.lstat()
if not stat.S_ISDIR(row.st_mode) or row.st_uid != 0 or row.st_mode & 0o022:
return None
row = Path(value).lstat()
if not stat.S_ISSOCK(row.st_mode) or row.st_uid != 0:
return None
return row.st_dev, row.st_ino
except OSError:
return None
def _sockets() -> list[tuple[str, tuple]]:
inherited = os.environ.get("WSL_INTEROP", "")
candidates = {inherited: 0}
try:
with os.scandir("/run/WSL") as entries:
for index, entry in enumerate(entries):
if index >= 64:
break
try:
candidates[entry.path] = entry.stat(follow_symlinks=False).st_mtime_ns
except OSError:
continue
except OSError as exc:
if not _socket_identity(inherited):
raise BridgeError("No trusted WSL interop session is available") from exc
result = []
# Prefer the caller's session, then recent sessions. Do not silently drop
# a responsive session because scandir happened to list stale ones first.
for candidate in sorted(candidates, key=lambda item: (item == inherited, candidates[item]), reverse=True):
identity = _socket_identity(candidate)
if identity:
result.append((candidate, identity))
return result
def candidate(env: dict) -> bool:
return (platform.system() == "Linux" and "microsoft" in platform.release().casefold()
and env_value(env, TRANSPORT_KEY)[1] == "model-router")
def _text(value, maximum=4096) -> bool:
return isinstance(value, str) and 0 < len(value) <= maximum and not any(ord(c) < 32 for c in value)
def _windows_path(value) -> bool:
return (_text(value) and bool(re.match(r"^[A-Za-z]:[\\/]", value))
and ".." not in PureWindowsPath(value).parts
and not any(character in value[2:] for character in ':*?"<>|'))
def _gguf(value) -> bool:
return (_text(value, 240) and value.lower().endswith(".gguf")
and not any(character in value for character in '/\\:*?"<>|')
and value == value.strip() and not value.startswith("."))
def _path(path: str, direction: str) -> str:
if not _text(path):
raise ValueError("Invalid path for WSL translation")
result = _run([_WSLPATH, direction, "-a", path], timeout=5)
if result.returncode:
raise BridgeError("WSL path translation failed")
value = result.stdout.decode("utf-8-sig").strip()
if not _text(value):
raise BridgeError("WSL path translation returned an invalid path")
return value
def drive_mount(drive: str) -> Path:
"""Where this distribution mounts a Windows drive such as ``C:``.
wslpath honours a custom DrvFS mount root ([automount] root in wsl.conf).
"""
if not isinstance(drive, str) or not re.fullmatch(r"[A-Za-z]:", drive):
raise ValueError("A Windows drive letter such as C: is required")
return Path(_path(drive + "\\", "-u"))
def _windows_tools(env: dict) -> _WindowsTools:
system = env.get('ODS_WINDOWS_SYSTEM_DIRECTORY', '')
if not system:
# Compatibility for an older interactive installation only. A Linux
# executable or UNC path cannot become a Windows control executable.
inherited = shutil.which('powershell.exe')
if not inherited:
raise BridgeError('Windows system directory is unknown; rerun the Windows installer')
windows_shell = _path(inherited, '-w')
if (not _windows_path(windows_shell)
or tuple(part.casefold() for part in PureWindowsPath(windows_shell).parts[-3:])
!= ('windowspowershell', 'v1.0', 'powershell.exe')):
raise BridgeError('The inherited Windows PowerShell path is not a system executable')
system = str(PureWindowsPath(windows_shell).parents[2])
if not _windows_path(system) or PureWindowsPath(system).name.casefold() != 'system32':
raise ValueError('ODS_WINDOWS_SYSTEM_DIRECTORY must name a local Windows System32 directory')
windows = PureWindowsPath(system)
drive = Path(_path(windows.anchor, '-u'))
directory = drive.joinpath(*windows.parts[1:])
if (not directory.is_absolute() or directory.resolve() != directory
or PureWindowsPath(_path(str(directory), '-w')) != windows):
raise BridgeError('The Windows system directory did not survive canonical WSL translation')
shell = directory / 'WindowsPowerShell/v1.0/powershell.exe'
probe = directory / 'whoami.exe'
if any(not path.is_file() or path.is_symlink() or path.resolve() != path for path in (shell, probe)):
raise BridgeError('Windows system PowerShell interop is unavailable; rerun the Windows installer')
return _WindowsTools(str(shell), str(probe), str(windows / 'WindowsPowerShell/v1.0/Modules'))
def _context(install_dir: Path, env: dict) -> _Context:
root = Path(install_dir).resolve(strict=True)
if not root.is_dir() or not root.as_posix().startswith("/"):
raise ValueError("A canonical WSL installation directory is required")
# Execute the controller shipped with this trusted module. A candidate
# uninstaller can retire an older target whose tree lacks these scripts;
# the target root remains the exact Windows task/plan binding below.
controller = _SOURCE / _CONTROLLER
if controller.is_symlink() or not controller.is_file() or controller.resolve().parent != controller.parent:
raise BridgeError("The installed Windows model controller is unavailable")
windows = _windows_tools(env)
windows_root = _path("/", "-w")
match = re.fullmatch(r"\\\\(?:wsl\.localhost|wsl\$)\\([^\\/]+)\\?", windows_root, re.IGNORECASE)
if not match or not _text(match[1], 128) or match[1] in {".", ".."}:
raise BridgeError("Cannot identify this WSL distribution")
return _Context(match[1], root.as_posix(), _path(str(controller), "-w"), windows)
def _projector(gguf, projector) -> bool:
return _gguf(projector) and projector.casefold() != str(gguf).casefold()
def _plan(plan, context: _Context) -> None:
if not isinstance(plan, dict) or set(plan) - {_PROJECTOR_KEY} != _PLAN_KEYS:
raise ValueError("Invalid Windows runtime plan schema")
if (not isinstance(plan["WslDistro"], str) or plan["WslDistro"].casefold() != context.distro.casefold()
or plan["WslInstallDir"] != context.install_dir
or not _windows_path(plan["ExecutablePath"]) or not _windows_path(plan["ModelsDir"])
or not _gguf(plan["GgufFile"]) or type(plan["Port"]) is not int
or not 1 <= plan["Port"] <= 65535 or type(plan["ContextSize"]) is not int
or not 4096 <= plan["ContextSize"] <= 262144
or (_PROJECTOR_KEY in plan and not _projector(plan["GgufFile"], plan[_PROJECTOR_KEY]))):
raise ValueError("Windows runtime plan does not match this installation")
def _response(value, context: _Context) -> dict:
if not isinstance(value, dict) or value.get("ok") is not True or type(value.get("managed")) is not bool:
raise BridgeError("Windows controller did not return an ownership result")
if type(value.get("running")) is not bool:
raise BridgeError("Windows controller returned an invalid process status")
if not value["managed"]:
return value
_plan(value.get("plan"), context)
features = value.get("planFeatures", [])
if not isinstance(features, list) or len(features) > 16 or not all(_text(item, 64) for item in features):
raise BridgeError("Windows controller returned invalid plan features")
if (not isinstance(value.get("planDigest"), str) or not _DIGEST.fullmatch(value["planDigest"])
or value.get("modelStoreWindowsPath") != value["plan"]["ModelsDir"]):
raise BridgeError("Windows controller returned an invalid plan identity")
expected_path = PureWindowsPath(value["plan"]["ModelsDir"]).parent / "portal-runtime" / "runtime.json"
if not _windows_path(value.get("planPathWindows")) or PureWindowsPath(value["planPathWindows"]) != expected_path:
raise BridgeError("Windows controller returned an unexpected durable plan path")
observed = value.get("observation")
if observed is not None and (not isinstance(observed, dict) or observed.get("status") != "verified"
or not _text(observed.get("modelId"), 512) or type(observed.get("contextLength")) is not int
or not 4096 <= observed["contextLength"] <= 262144 or not value["running"]):
raise BridgeError("Windows controller returned an invalid runtime observation")
error = value.get("runtimeError")
if error is not None and not _text(error, _RUNTIME_ERROR_LIMIT):
raise BridgeError("Windows controller returned an invalid runtime error")
source = value.get("runtimeErrorSource")
if source is not None and (source not in ("launcher", "observation") or error is None):
raise BridgeError("Windows controller returned an invalid runtime error source")
refusal = value.get("startRefusal")
if refusal is not None and (not isinstance(refusal, str) or refusal not in START_REFUSALS
or value["running"] or source != "launcher"):
raise BridgeError("Windows controller returned an invalid start refusal")
return value
def launcher_error(value: dict) -> dict:
"""The launcher's own startup error and memory refusal from a validated status, if any.
Observation failures (a stale process record, a model that is still
loading) stay internal; only what the launcher wrote is shown to owners.
"""
if value.get("managed") is not True or value.get("running") is not False:
return {}
if value.get("runtimeErrorSource") != "launcher" or not isinstance(value.get("runtimeError"), str):
return {}
fields = {"runtimeError": value["runtimeError"]}
if value.get("startRefusal") in START_REFUSALS:
fields["startRefusal"] = value["startRefusal"]
return fields
def _environment(socket: str, windows: _WindowsTools) -> dict:
environ = os.environ.copy()
environ["WSL_INTEROP"] = socket
# A WSL session started from PS7 otherwise gives Windows PowerShell 5.1
# the PS7 module search path, breaking even Get-Acl. Scope this override
# to this child; /w explicitly exports it from WSL to Windows.
environ["PSModulePath"] = windows.module_path
exports = [entry for entry in environ.get("WSLENV", "").split(":")
if entry and entry.split("/", 1)[0].casefold() != "psmodulepath"]
environ["WSLENV"] = ":".join([*exports, "PSModulePath/w"])
return environ
def _probe(socket_info: tuple, timeout: float, windows: _WindowsTools) -> bool:
socket, identity = socket_info
if _socket_identity(socket) != identity:
return False
# Fixed, read-only native executable: liveness only, never ownership.
result = _run([windows.probe, "/user", "/fo", "csv", "/nh"], timeout=timeout,
environ=_environment(socket, windows))
return result.returncode == 0 and bool(result.stdout.strip()) and _socket_identity(socket) == identity
def _select_socket(windows: _WindowsTools, *, excluded: tuple = (), timeout: float = 3) -> tuple:
sockets = [socket for socket in _sockets() if socket not in excluded]
if not sockets:
raise BridgeError("No trusted WSL interop session is available")
deadline = time.monotonic() + timeout
for socket in sockets:
remaining = deadline - time.monotonic()
if remaining <= 0:
break
try:
# A cold Windows executable can take over 500 ms (antivirus and
# image loading); keep the global bound, not a warm-start cutoff.
if _probe(socket, min(remaining, 2), windows):
return socket
except subprocess.TimeoutExpired:
continue # Only this native read-only liveness probe is retried.
raise BridgeError("No responsive trusted WSL interop session is available")
def _call(context: _Context, socket_info: tuple, request: dict, timeout: float) -> dict:
socket, identity = socket_info
if _socket_identity(socket) != identity:
raise BridgeError("The trusted WSL interop session changed before dispatch", code="interop_changed")
message = {"action": "status", "distro": context.distro, "installDir": context.install_dir, **request}
data = json.dumps(message, allow_nan=False, separators=(",", ":")).encode("utf-8")
result = _run([context.windows.shell, "-NoLogo", "-NoProfile", "-NonInteractive", "-ExecutionPolicy", "Bypass",
"-File", context.controller], data=data, timeout=timeout, environ=_environment(socket, context.windows))
if _socket_identity(socket) != identity:
raise BridgeError("The WSL session changed during the operation; inspect status before retrying",
code="interop_changed")
if result.returncode and not result.stdout.strip() and b"invalid argument" in result.stderr.lower():
raise BridgeError("The selected WSL interop session is unavailable", code="interop_unavailable")
try:
value = json.loads(result.stdout.decode("utf-8-sig"))
except (ValueError, UnicodeError) as exc:
# The fixed controller accepts no credentials and emits only its
# ownership result/errors. Keep diagnostics bounded; never log env/stdin.
logging.getLogger(__name__).warning(
"Windows runtime controller returned invalid JSON (exit=%s, stdout=%r, stderr=%r)",
result.returncode, result.stdout[:500], result.stderr[:500])
raise BridgeError("Windows controller returned invalid JSON") from exc
if result.returncode != 0 or (isinstance(value, dict) and value.get("ok") is False):
failure = {}
if isinstance(value, dict):
for key in ("code", "error", "newPlanDigest"):
if _text(value.get(key), 2000):
failure[key] = value[key]
raise BridgeError(failure.get("error", "Windows controller operation failed"),
code=failure.get("code", "windows_controller_failed"), response=failure)
return _response(value, context)
def _endpoint_matches_plan(env: dict, value: dict) -> None:
if not value["managed"]:
return
port = value["plan"]["Port"]
for key, hosts in ((HOST_BASE_URL_KEY, {"localhost", "127.0.0.1", "::1"}),
(CONTAINER_BASE_URL_KEY, {"host.docker.internal"})):
name, raw = env_value(env, key)
if raw is None:
continue
paths = _ENDPOINT_PATHS if name == key else _LEGACY_ENDPOINT_PATHS
try:
url = urlsplit(raw) if _text(raw) else None
valid = (url is not None and url.scheme == "http" and url.hostname in hosts
and url.username is None and url.password is None and not url.query and not url.fragment
and url.path.rstrip("/") in paths
and (url.port or 80) == port)
except ValueError:
valid = False
if not valid:
raise BridgeError("The configured runtime endpoint does not match the owned Windows task", code="endpoint_mismatch")
if "AMD_INFERENCE_PORT" in env and str(env["AMD_INFERENCE_PORT"]) != str(port):
raise BridgeError("The configured runtime port does not match the owned Windows task", code="endpoint_mismatch")
def _connected_status(install_dir: Path, env: dict):
if not candidate(env):
raise BridgeError("This installation does not use a managed Windows runtime", code="unsupported_runtime")
context = _context(install_dir, env)
deadline = time.monotonic() + 18
excluded = ()
for attempt in range(2):
remaining = deadline - time.monotonic()
if remaining <= 0:
raise BridgeError("Windows ownership verification exceeded its deadline")
socket = _select_socket(context.windows, excluded=excluded, timeout=min(3, remaining))
remaining = deadline - time.monotonic()
if remaining <= 0:
raise BridgeError("Windows ownership verification exceeded its deadline")
try:
# Ownership needs its full budget; the former 5-second discovery
# attempts killed healthy controllers before checks completed.
value = _call(context, socket, {}, min(15, remaining))
except BridgeError as exc:
if exc.code != "interop_changed" or attempt:
raise
# A short-lived interactive session can disappear after its probe.
# Retry only read-only status after proven inode loss/replacement.
excluded = (socket,)
continue
_endpoint_matches_plan(env, value)
return context, socket, value
def status(install_dir: Path, env: dict) -> dict:
if not candidate(env):
return {"ok": True, "managed": False, "running": False}
return _connected_status(install_dir, env)[2]
def _mutate(install_dir: Path, env: dict, action: str, expected_plan_digest: str, **values) -> dict:
if not isinstance(expected_plan_digest, str) or not _DIGEST.fullmatch(expected_plan_digest):
raise ValueError("A valid expected plan digest is required")
context, socket, current = _connected_status(install_dir, env)
if not current["managed"]:
raise BridgeError("The Windows runtime task is not managed by this installation", code="unmanaged_runtime")
if current["planDigest"] != expected_plan_digest:
raise BridgeError("The Windows runtime plan changed before activation", code="plan_changed")
if action == "restore":
_plan(values.get("plan"), context)
immutable = _PLAN_KEYS - {"GgufFile", "ContextSize", "WslDistro"}
if any(values["plan"][key] != current["plan"][key] for key in immutable):
raise ValueError("Restore cannot change runtime ownership or location")
result = _call(context, socket, {"action": action, "expectedPlanDigest": expected_plan_digest, **values},
1200 if action in {"activate", "restore", "start"} else 90)
if not result["managed"] or result["running"] != (action != "stop"):
raise BridgeError("Windows controller did not prove the requested process state")
target = values.get("plan") if action == "restore" else current["plan"]
gguf = values.get("gguf", target["GgufFile"])
size = values.get("contextSize", target["ContextSize"])
projector = values.get("mmproj") if action == "activate" else target.get(_PROJECTOR_KEY)
if (result["plan"]["GgufFile"] != gguf or result["plan"]["ContextSize"] != size
or result["plan"].get(_PROJECTOR_KEY) != projector):
raise BridgeError("Windows controller did not persist the requested model plan")
if action != "stop" and (not result.get("observation") or result["observation"]["contextLength"] != size):
raise BridgeError("Windows controller did not prove the requested model context")
return result
def supports_projector(value: dict) -> bool:
"""Does the owned launcher declare that it loads a vision projector?"""
return value.get("managed") is True and _PROJECTOR_KEY in value.get("planFeatures", [])
def activate(install_dir: Path, env: dict, gguf: str, context_size: int, expected_plan_digest: str,
mmproj: str | None = None) -> dict:
if not _gguf(gguf) or type(context_size) is not int or not 4096 <= context_size <= 262144:
raise ValueError("A safe GGUF filename and supported context size are required")
if mmproj is None:
return _mutate(install_dir, env, "activate", expected_plan_digest, gguf=gguf, contextSize=context_size)
if not _projector(gguf, mmproj):
raise ValueError("A vision projector needs its own safe GGUF filename")
return _mutate(install_dir, env, "activate", expected_plan_digest, gguf=gguf, contextSize=context_size,
mmproj=mmproj)
def restore(install_dir: Path, env: dict, plan: dict, expected_plan_digest: str) -> dict:
return _mutate(install_dir, env, "restore", expected_plan_digest, plan=plan)
def stop(install_dir: Path, env: dict, expected_plan_digest: str) -> dict:
return _mutate(install_dir, env, "stop", expected_plan_digest)
def start(install_dir: Path, env: dict, expected_plan_digest: str) -> dict:
return _mutate(install_dir, env, "start", expected_plan_digest)
def disable_startup(install_dir: Path, env: dict, *, validate_only: bool = False,
retire_relay: bool = False) -> dict:
"""Retire bound Windows login startup and, for uninstall, its owned relay."""
state_root = env.get('ODS_WSL_STATE_ROOT')
if 'ODS_WSL_STATE_ROOT' in env:
if not _text(state_root) or any(character in state_root for character in '\"*?<>|'):
raise ValueError('ODS_WSL_STATE_ROOT must name an absolute Windows state directory')
path = PureWindowsPath(state_root)
local = bool(re.match(r'^[A-Za-z]:[\\/]', state_root))
unc = state_root.startswith('\\\\') and len(path.drive.split('\\')) == 4
if (not path.is_absolute() or not (local or unc) or path == PureWindowsPath(path.anchor)
or re.search(r'(^|[\\/])\.{1,2}([\\/]|$)', state_root)
or ':' in (state_root[2:] if local else state_root)):
raise ValueError('ODS_WSL_STATE_ROOT must not be a filesystem root, device or traversal path')
context = _context(install_dir, env)
program = _SOURCE / 'installers/wsl-lifecycle.ps1'
if not program.is_file() or program.is_symlink() or program.resolve() != program:
raise BridgeError('The installed WSL startup controller is unavailable')
controller = _path(str(program), '-w')
socket, identity = _select_socket(context.windows)
if _socket_identity(socket) != identity:
raise BridgeError('The WSL session changed before startup retirement')
command = [context.windows.shell, '-NoLogo', '-NoProfile', '-NonInteractive',
'-ExecutionPolicy', 'Bypass', '-File', controller,
'-Action', 'disable-startup', '-Distro', context.distro,
'-InstallRoot', context.install_dir]
if state_root is not None:
command.extend(['-StateRoot', state_root])
if validate_only:
command.append('-ValidateOnly')
if retire_relay:
command.append('-RetireRelay')
# Mutations are issued once, including an uncertain/expired interop call.
# Relay retirement adds bounded scheduler/child shutdown after command.lock.
result = _run(command, timeout=90 if retire_relay and not validate_only else 45,
environ=_environment(socket, context.windows))
if _socket_identity(socket) != identity:
raise BridgeError('The WSL session changed during startup retirement; inspect before retrying')
if result.returncode:
raise BridgeError('Windows startup ownership could not be verified; installation retained')
try:
value = json.loads(result.stdout.decode('utf-8-sig'))
except (ValueError, UnicodeError) as exc:
raise BridgeError('Windows startup controller returned invalid JSON') from exc
expected = {'unmanaged', 'validated' if validate_only else 'disabled'}
owner = value.get('identity') if isinstance(value, dict) else None
if (not isinstance(value, dict) or value.get('scope') != 'wsl-startup'
or value.get('state') not in expected or not isinstance(owner, dict)
or not isinstance(owner.get('distro'), str)
or owner['distro'].casefold() != context.distro.casefold()
or owner.get('installRoot') != context.install_dir):
raise BridgeError('Windows startup controller did not prove this installation was retired')
if retire_relay:
expected_relay = {'unmanaged': 'unmanaged', 'validated': 'validated', 'disabled': 'stopped'}[value['state']]
if value.get('relayRetirement') != expected_relay:
raise BridgeError('Windows startup controller did not prove owned relay retirement')
return value
def _owned_path(install_dir: Path, env: dict, status_info: dict | None, field: str) -> Path:
if not candidate(env):
raise BridgeError("This installation does not use a managed Windows runtime", code="unsupported_runtime")
context = _context(install_dir, env)
proof = _response(status_info, context) if status_info is not None else status(install_dir, env)
if not proof["managed"]:
raise BridgeError("The Windows model store is not owned by this installation")
windows = proof[field]
# Docker Desktop registers bind aliases for individual Windows folders.
# wslpath then prefers that temporary alias for the complete path. Resolve
# only the drive's mount and append validated components, so registration
# remains stable across Compose recreations and custom DrvFS mount roots.
windows_path = PureWindowsPath(windows)
drive = Path(_path(windows_path.anchor, "-u"))
root = drive.joinpath(*windows_path.parts[1:])
exists = root.is_dir() if field == "modelStoreWindowsPath" else root.is_file()
if not root.is_absolute() or root.is_symlink() or not exists or root.resolve() != root:
raise BridgeError("The owned Windows path is not available as a canonical WSL path")
if PureWindowsPath(_path(str(root), "-w")) != PureWindowsPath(windows):
raise BridgeError("The owned Windows path did not survive translation")
return root
def model_store(install_dir: Path, env: dict, status_info: dict | None = None) -> Path:
return _owned_path(install_dir, env, status_info, "modelStoreWindowsPath")
def plan_path(install_dir: Path, env: dict, status_info: dict | None = None) -> Path:
return _owned_path(install_dir, env, status_info, "planPathWindows")