quality-loop 0.3.0__tar.gz → 0.4.0__tar.gz

{quality_loop-0.3.0/quality_loop.egg-info → quality_loop-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: quality-loop
-Version: 0.3.0
+Version: 0.4.0
 Summary: Measure what a product teaches - its skill, tools or manual - with isolated agent runs of real tasks, reported by an operator agent
 Author: craftware
 License-Expression: MIT
@@ -110,6 +110,8 @@ under a policy the person sets. See [Running the loop](https://github.com/crftwr
   launch command and a redirected home up to evidence tools of its own.
 - [Reports](https://github.com/crftwr/quality-loop/blob/main/docs/reports.md): problems, severities, kinds and ids, the
   reproduction record, and `FINDINGS.md` / `findings.json`.
+- [Running the app in a VM](https://github.com/crftwr/quality-loop/blob/main/docs/guests.md): one image per OS,
+  the guest over SSH, a clean machine every run, screens in the guest.
 - [Isolation and permissions](https://github.com/crftwr/quality-loop/blob/main/docs/isolation.md): what keeps the room, the
   operator and the conductor in bounds, why each rule exists, and the known limits.
 - [Development](https://github.com/crftwr/quality-loop/blob/main/docs/development.md): tests, live tests, releasing.

{quality_loop-0.3.0 → quality_loop-0.4.0}/README.md

@@ -79,6 +79,8 @@ under a policy the person sets. See [Running the loop](https://github.com/crftwr
   launch command and a redirected home up to evidence tools of its own.
 - [Reports](https://github.com/crftwr/quality-loop/blob/main/docs/reports.md): problems, severities, kinds and ids, the
   reproduction record, and `FINDINGS.md` / `findings.json`.
+- [Running the app in a VM](https://github.com/crftwr/quality-loop/blob/main/docs/guests.md): one image per OS,
+  the guest over SSH, a clean machine every run, screens in the guest.
 - [Isolation and permissions](https://github.com/crftwr/quality-loop/blob/main/docs/isolation.md): what keeps the room, the
   operator and the conductor in bounds, why each rule exists, and the known limits.
 - [Development](https://github.com/crftwr/quality-loop/blob/main/docs/development.md): tests, live tests, releasing.

{quality_loop-0.3.0 → quality_loop-0.4.0}/quality_loop/__init__.py

@@ -12,4 +12,4 @@ room is handed, putting the user's machine back - is code here, not an
 agent's discretion.
 """
 
-__version__ = "0.3.0"
+__version__ = "0.4.0"

quality_loop-0.4.0/quality_loop/guest/__init__.py

@@ -0,0 +1,580 @@
+"""A product's app in a VM, off the host's keyboard and screen (keyhac#271, xefm#750).
+
+Everything Claude does stays on the host: the room, the operator, the
+evidence, the rooms directory. Only the product's app moves into a guest, and
+the run reaches it the way it reaches a local one:
+
+- **A folder is shared.** The host writes into its host side (the stage, the
+  run's home, results); the guest reads the same files under its guest side.
+  :meth:`Guest.path` turns one into the other.
+- **The guest is an SSH host alias.** Its address, user and key live in
+  ``~/.ssh/config``, never here. A port the app opens in the guest is
+  forwarded to the host (:meth:`Guest.forward`), and one the host serves is
+  forwarded into the guest (:meth:`Guest.reverse`).
+- **The guest's runtime is its own image's.** The image carries a Python
+  runtime and nothing that is under test (xefm#750, "Decisions on the shared
+  test image"): the product's working tree and what else its makers build are
+  staged every run, and third-party packages are installed into a fresh venv
+  in the guest every run (:meth:`Guest.venv`), with pip's download cache on
+  the host side of the share so a revert does not lose the downloads.
+- **What has to be on the desktop runs in the desktop session**, where a
+  window is seen and can take focus - not in the SSH session, which has
+  neither. Windows starts it from a scheduled task run as the logged-in user
+  (:meth:`Guest.run_in_session`).
+
+The VM should be clean when a run starts: a Tart clone of a base image, or a
+VMware snapshot reverted to. When the per-machine settings name the VM for
+the alias, :meth:`Guest.machine` does that itself.
+
+Per-machine settings live outside every repository - they name this
+machine's VMs, paths and Keychain items, never a secret itself -
+in ``~/.config/quality-loop/guests.toml`` (``QUALITY_LOOP_GUESTS`` moves it):
+
+    [qa-mac]
+    share = "~/.cache/qa-guest=/Volumes/My Shared Files/qa"
+    python = "/Library/Frameworks/Python.framework/Versions/3.14/bin/python3"
+    tart = "<base VM>"                  # cloned per run, deleted after
+    visible = true
+
+    [qa-win]
+    share = "~/mnt/qa-win=C:\\\\qa"
+    python = "C:\\\\Python314\\\\python.exe"
+    vmx = "~/Virtual Machines.localized/<VM>.vmwarevm/<VM>.vmx"
+    snapshot = "<snapshot>"             # reverted to before the run
+    vm_password = "keychain:<service>"  # the VM's encryption password
+    smb = "//<user>@<guest>/<share>"    # remounted on the share's host side
+    smb_password = "keychain:<service>"
+
+Without a VM named, the run uses the guest as it is, already running.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import hashlib
+import json
+import ntpath
+import os
+import pathlib
+import posixpath
+import shutil
+import socket
+import subprocess
+import tempfile
+import time
+import tomllib
+import urllib.parse
+
+#: Per-machine settings, by SSH alias. QUALITY_LOOP_GUESTS moves it.
+GUESTS = pathlib.Path("~/.config/quality-loop/guests.toml")
+
+HERE = pathlib.Path(__file__).resolve().parent
+
+
+class GuestError(Exception):
+    """The guest could not be reached, started or used."""
+
+
+def settings_for(alias: str, path: pathlib.Path | str | None = None) -> dict:
+    """The table for ``alias`` in the per-machine settings, or ``{}``."""
+    where = pathlib.Path(path or os.environ.get("QUALITY_LOOP_GUESTS", GUESTS)).expanduser()
+    try:
+        with where.open("rb") as f:
+            return tomllib.load(f).get(alias, {})
+    except FileNotFoundError:
+        return {}
+    except tomllib.TOMLDecodeError as error:
+        raise GuestError(f"{where}: {error}") from None
+
+
+def secret(value: str) -> str:
+    """``keychain:<service>`` read from the login Keychain; anything else as
+    it is. Read when a run needs it, never written anywhere."""
+    if not value.startswith("keychain:"):
+        return value
+    service = value.removeprefix("keychain:")
+    said = subprocess.run(["security", "find-generic-password", "-s", service, "-w"],
+                          capture_output=True, text=True)
+    if said.returncode != 0:
+        raise GuestError(f"no Keychain item {service!r}: add it with "
+                         f"security add-generic-password -a <account> -s {service} -w")
+    return said.stdout.rstrip("\n")
+
+
+def sh_quote(word: str) -> str:
+    return "'" + word.replace("'", "'\\''") + "'"
+
+
+def ps_quote(word: str) -> str:
+    """A PowerShell single-quoted literal."""
+    return "'" + word.replace("'", "''") + "'"
+
+
+class Guest:
+    """One VM, reached as an SSH host alias, sharing a folder with the host."""
+
+    def __init__(self, alias: str, host_share: pathlib.Path, guest_share: str,
+                 settings: dict | None = None):
+        self.alias = alias
+        self.host_share = pathlib.Path(host_share).resolve()
+        self.guest_share = guest_share
+        self.settings = settings or {}
+        self._windows: bool | None = None
+        #: Set while a run's clone is up: its address, which the alias's
+        #: HostName does not know.
+        self.hostname: str | None = None
+
+    @classmethod
+    def from_settings(cls, alias: str, settings: dict, share: str | None = None) -> "Guest":
+        """A guest from its settings table; ``share`` (``host=guest``)
+        overrides the table's."""
+        share = share or settings.get("share", "")
+        host, _, guest = share.partition("=")
+        if not host or not guest:
+            raise GuestError(f"the guest {alias!r} needs share = <host dir>=<guest dir>: "
+                             "a folder shared with the VM, as each side sees it")
+        host_share = pathlib.Path(host).expanduser()
+        if not host_share.is_dir():
+            raise GuestError(f"the share's host side, {host_share}, is not a directory")
+        return cls(alias, host_share, guest, settings)
+
+    @classmethod
+    def from_environment(cls, variable: str = "QUALITY_LOOP_GUEST",
+                         share_variable: str | None = None,
+                         settings_path: pathlib.Path | str | None = None) -> "Guest | None":
+        """The guest ``variable`` names, or None when it names none. A product
+        passes its own variable names (``KEYHAC_QA_GUEST``)."""
+        alias = os.environ.get(variable)
+        if not alias:
+            return None
+        share = os.environ.get(share_variable) if share_variable else None
+        return cls.from_settings(alias, settings_for(alias, settings_path), share)
+
+    def to_settings(self) -> dict:
+        """What :mod:`quality_loop.guest.screens` needs to reach this guest
+        from another process: JSON, no secrets."""
+        return {"alias": self.alias, "hostname": self.hostname,
+                "host_share": str(self.host_share), "guest_share": self.guest_share,
+                "windows": self.windows, "python": self.python}
+
+    @classmethod
+    def from_screen_settings(cls, settings: dict) -> "Guest":
+        guest = cls(settings["alias"], pathlib.Path(settings["host_share"]),
+                    settings["guest_share"], {"python": settings.get("python")})
+        guest._windows = settings["windows"]
+        guest.hostname = settings.get("hostname")
+        return guest
+
+    # --- talking to it ---------------------------------------------------------
+
+    def ssh_options(self) -> list[str]:
+        if self.hostname is None:
+            return []
+        # A clone answers with its base's host key at a new address each time.
+        return ["-o", f"HostName={self.hostname}", "-o", f"HostKeyAlias={self.alias}",
+                "-o", "StrictHostKeyChecking=accept-new"]
+
+    def ssh(self, command: str, timeout: float = 60) -> subprocess.CompletedProcess:
+        return subprocess.run(["ssh", "-o", "BatchMode=yes", *self.ssh_options(),
+                               self.alias, command],
+                              capture_output=True, text=True, timeout=timeout,
+                              stdin=subprocess.DEVNULL)
+
+    def reachable(self, patience: float) -> bool:
+        """Whether SSH gets in within ``patience`` seconds."""
+        deadline = time.monotonic() + patience
+        while time.monotonic() < deadline:
+            try:
+                if self.ssh("echo up", timeout=15).stdout.strip() == "up":
+                    return True
+            except subprocess.TimeoutExpired:
+                pass
+            time.sleep(3)
+        return False
+
+    def machine(self):
+        """A context manager for the run: the VM up from a clean state, and
+        put away afterwards, when the settings name one."""
+        if "tart" in self.settings:
+            return TartMachine(self)
+        if "vmx" in self.settings:
+            return VMwareMachine(self)
+        return contextlib.nullcontext()
+
+    @property
+    def windows(self) -> bool:
+        """Whether the guest is Windows - asked once. A Windows guest's shell
+        is PowerShell, where `uname` is no command."""
+        if self._windows is None:
+            said = self.ssh("uname -s")
+            if said.returncode == 255:
+                raise GuestError(f"cannot reach the VM as {self.alias!r}:\n{said.stderr}")
+            self._windows = said.stdout.strip() != "Darwin"
+        return self._windows
+
+    @property
+    def platform(self) -> str:
+        """``sys.platform`` as the guest's own Python would say it."""
+        return "win32" if self.windows else "darwin"
+
+    @property
+    def python(self) -> str:
+        """The image's interpreter, as the guest names it (``python`` in the
+        settings)."""
+        python = self.settings.get("python")
+        if not python:
+            raise GuestError(f"the guest {self.alias!r} has no python = in its settings: "
+                             "the image's interpreter, as the guest names it")
+        return python
+
+    def path(self, host_path: pathlib.Path | str) -> str:
+        """A path under the host side of the share, as the guest sees it."""
+        parts = pathlib.Path(host_path).resolve().relative_to(self.host_share).parts
+        join = ntpath.join if self.windows else posixpath.join
+        return join(self.guest_share, *parts)
+
+    def mkdtemp(self, prefix: str) -> pathlib.Path:
+        """A new directory on the share (its host side)."""
+        return pathlib.Path(tempfile.mkdtemp(prefix=prefix, dir=self.host_share)).resolve()
+
+    def kill(self, pid: int) -> None:
+        if self.windows:
+            self.ssh(f"Stop-Process -Id {int(pid)} -Force -ErrorAction SilentlyContinue")
+        else:
+            self.ssh(f"kill -INT {int(pid)}; sleep 3; kill -9 {int(pid)} 2>/dev/null; true")
+
+    def forward(self, port: int) -> subprocess.Popen:
+        """The guest's 127.0.0.1:port as the host's, until terminated."""
+        return self._tunnel("-L", port)
+
+    def reverse(self, port: int) -> subprocess.Popen:
+        """The host's 127.0.0.1:port as the guest's, until terminated."""
+        return self._tunnel("-R", port, start_new_session=True)
+
+    def _tunnel(self, direction: str, port: int, **popen) -> subprocess.Popen:
+        return subprocess.Popen(
+            ["ssh", "-N", "-o", "BatchMode=yes", "-o", "ExitOnForwardFailure=yes",
+             *self.ssh_options(), direction, f"{port}:127.0.0.1:{port}", self.alias],
+            stdin=subprocess.DEVNULL, stdout=subprocess.DEVNULL, stderr=subprocess.PIPE,
+            **popen)
+
+    # --- what runs in it ---------------------------------------------------------
+
+    def stage(self, prefix: str = "ql-stage-") -> pathlib.Path:
+        """A new stage on the share, carrying what runs in the guest on
+        quality-loop's behalf: its screen backends and the boot scripts
+        (``<stage>/ql``). The product adds its own files beside them."""
+        stage = self.mkdtemp(prefix)
+        ignore = shutil.ignore_patterns("__pycache__", "*.pyc")
+        package = HERE.parent
+        ql = stage / "ql" / "quality_loop"
+        ql.mkdir(parents=True)
+        # quality_loop/__init__.py and screens/ need nothing else; guest/ is
+        # copied for its boot scripts.
+        shutil.copy2(package / "__init__.py", ql / "__init__.py")
+        shutil.copytree(package / "screens", ql / "screens", ignore=ignore)
+        shutil.copytree(HERE, ql / "guest", ignore=ignore)
+        return stage
+
+    def boot_script(self, stage: pathlib.Path, name: str) -> pathlib.Path:
+        """``name`` among the boot scripts, as staged."""
+        return stage / "ql" / "quality_loop" / "guest" / "boot" / name
+
+    def venv(self, stage: pathlib.Path, requirements: list[str], *,
+             timeout: float = 900) -> str:
+        """A fresh venv in the guest with ``requirements`` installed, from the
+        image's Python; returns its interpreter as the guest names it.
+
+        Made on the guest's own disk, which the revert after the run throws
+        away, so every run gets what the working tree asks for now. pip's
+        download cache is on the share (``<host share>/.pip-cache``), so the
+        next run downloads only what changed. Nothing that is under test goes
+        in here: the product stages its own code and its makers' packages."""
+        lines = "\n".join(requirements) + "\n"
+        digest = hashlib.sha256(lines.encode()).hexdigest()[:12]
+        (stage / "requirements.txt").write_text(lines, encoding="utf-8")
+        cache = self.host_share / ".pip-cache"
+        cache.mkdir(exist_ok=True)
+        if self.windows:
+            where = rf"$env:LOCALAPPDATA\ql-venv-{digest}"
+            python = rf"{where}\Scripts\python.exe"
+            command = (f"$ErrorActionPreference = 'Stop'; "
+                       f"& {ps_quote(self.python)} -m venv \"{where}\"; "
+                       f"if ($LASTEXITCODE) {{ exit $LASTEXITCODE }}; "
+                       f"& \"{python}\" -m pip install --disable-pip-version-check -q "
+                       f"--cache-dir {ps_quote(self.path(cache))} "
+                       f"-r {ps_quote(self.path(stage / 'requirements.txt'))}; "
+                       f"if ($LASTEXITCODE) {{ exit $LASTEXITCODE }}; "
+                       f"Write-Output \"{python}\"")
+        else:
+            where = f"$HOME/.ql-venv-{digest}"
+            python = f"{where}/bin/python"
+            command = (f"set -e; {sh_quote(self.python)} -m venv \"{where}\"; "
+                       f"\"{python}\" -m pip install --disable-pip-version-check -q "
+                       f"--cache-dir {sh_quote(self.path(cache))} "
+                       f"-r {sh_quote(self.path(stage / 'requirements.txt'))}; "
+                       f"echo \"{python}\"")
+        said = self.ssh(command, timeout=timeout)
+        if said.returncode != 0:
+            raise GuestError(f"could not install the run's packages in the VM:\n"
+                             f"{said.stdout[-1500:]}{said.stderr[-1500:]}")
+        return said.stdout.strip().splitlines()[-1].strip()
+
+    def run_in_session(self, stage: pathlib.Path, task: str, python: str,
+                       script: pathlib.Path, *arguments: str) -> None:
+        """Windows: start ``script`` (on the stage) with ``python`` - a
+        ``pythonw.exe``, which opens no console window on that desktop - in
+        the logged-in user's desktop session, and return.
+
+        A scheduled task, run interactively, is how a process gets into that
+        session from SSH, where a window it opens is seen and EnumWindows
+        finds it. The task is XML, not schtasks /tr: the program and its
+        arguments stay apart, so nothing has to survive PowerShell's quoting
+        of a native command line - and the ScheduledTasks cmdlets need CIM,
+        which refuses a standard user over SSH. The task is left defined;
+        :meth:`forget_task` removes it."""
+        if not self.windows:
+            raise GuestError("run_in_session is for a Windows guest; on macOS, start "
+                             "the app with `open`, which reaches the desktop session")
+        definition = stage / f"{task}.xml"
+        definition.write_text(task_xml(
+            python, " ".join(f'"{a}"' for a in ("-s", self.path(script), *arguments))),
+            encoding="utf-16")
+        quoted = ps_quote(task)
+        said = self.ssh(f"schtasks /create /tn {quoted} /xml "
+                        f"{ps_quote(self.path(definition))} /f; schtasks /run /tn {quoted}")
+        if "SUCCESS: Attempted to run" not in said.stdout:
+            raise GuestError(f"could not run {script.name} in the VM's desktop session:\n"
+                             f"{said.stdout}{said.stderr}")
+
+    def launch(self, stage: pathlib.Path, task: str, python: str, *,
+               script: str, log: pathlib.Path, environ: dict | None = None,
+               path: list[str] | None = None, cwd: str | None = None,
+               argv: list[str] | None = None) -> None:
+        """Windows: run ``script`` (a guest path) as ``__main__`` in the
+        desktop session, through ``boot/launch.py``: ``environ`` set, ``path``
+        put in front of ``sys.path``, ``cwd`` entered, stdout and stderr into
+        ``log`` (on the share), ``argv`` as its arguments. ``python`` should be
+        a ``pythonw.exe``: a console window would open on the desktop the room
+        looks at."""
+        settings = {"log": self.path(log), "script": script,
+                    "environ": dict(environ or {}), "path": list(path or []),
+                    "cwd": cwd, "argv": list(argv or [])}
+        launch = stage / f"{task}.json"
+        launch.write_text(json.dumps(settings), encoding="utf-8")
+        self.run_in_session(stage, task, python, self.boot_script(stage, "launch.py"),
+                            self.path(launch))
+
+    def forget_task(self, task: str) -> None:
+        if self.windows:
+            self.ssh(f"schtasks /delete /tn {ps_quote(task)} /f")
+
+    def windowless(self, python: str) -> str:
+        """``python``'s ``pythonw.exe`` beside it, on Windows."""
+        if self.windows and python.lower().endswith("python.exe"):
+            return python[:-len("python.exe")] + "pythonw.exe"
+        return python
+
+
+def task_xml(command: str, arguments: str) -> str:
+    """A scheduled task that runs ``command`` in the creating user's desktop
+    session (InteractiveToken), with no time limit."""
+    from xml.sax.saxutils import escape
+    return f"""<?xml version="1.0" encoding="UTF-16"?>
+<Task version="1.2" xmlns="http://schemas.microsoft.com/windows/2004/02/mit/task">
+  <Principals>
+    <Principal id="Author">
+      <LogonType>InteractiveToken</LogonType>
+      <RunLevel>LeastPrivilege</RunLevel>
+    </Principal>
+  </Principals>
+  <Settings>
+    <MultipleInstancesPolicy>IgnoreNew</MultipleInstancesPolicy>
+    <DisallowStartIfOnBatteries>false</DisallowStartIfOnBatteries>
+    <StopIfGoingOnBatteries>false</StopIfGoingOnBatteries>
+    <ExecutionTimeLimit>PT0S</ExecutionTimeLimit>
+    <Enabled>true</Enabled>
+  </Settings>
+  <Actions Context="Author">
+    <Exec>
+      <Command>{escape(command)}</Command>
+      <Arguments>{escape(arguments)}</Arguments>
+    </Exec>
+  </Actions>
+</Task>
+"""
+
+
+def listening(port: int) -> bool:
+    """Whether something answers on the host's 127.0.0.1:port."""
+    with socket.socket() as probe:
+        probe.settimeout(1.0)
+        return probe.connect_ex(("127.0.0.1", port)) == 0
+
+
+def end_tunnels(stage: pathlib.Path) -> None:
+    """The reverse tunnels :mod:`quality_loop.guest.screens` started for the
+    screens' pages: it records each one's pid on the stage, and the operator
+    that started them is gone by the run's end."""
+    for pid_file in (stage / "tunnels").glob("*.pid"):
+        try:
+            os.kill(int(pid_file.read_text()), 15)
+        except (OSError, ValueError):
+            pass
+
+
+# --- the machines -----------------------------------------------------------------
+
+class TartMachine:
+    """A Tart VM cloned from the base for this run, and deleted after it.
+
+    Its share is ``tart run --dir``, tagged with the last part of the share's
+    guest side (``/Volumes/My Shared Files/qa`` -> ``qa``). Shown in a window
+    when ``visible = true``; watch it, but do not type into it.
+    """
+
+    def __init__(self, guest: Guest, patience: float = 240.0):
+        self.guest, self.patience = guest, patience
+        self.base = guest.settings["tart"]
+        self.name = f"{self.base}-run-{os.getpid()}"
+        self.process = None
+
+    def _tart(self, *args, check=True) -> subprocess.CompletedProcess:
+        said = subprocess.run(["tart", *args], capture_output=True, text=True)
+        if check and said.returncode != 0:
+            raise GuestError(f"tart {' '.join(args)}: {said.stderr.strip()}")
+        return said
+
+    def __enter__(self):
+        self._tart("clone", self.base, self.name)
+        tag = posixpath.basename(self.guest.guest_share.rstrip("/"))
+        args = ["tart", "run", f"--dir={tag}:{self.guest.host_share}", self.name]
+        if not self.guest.settings.get("visible"):
+            args.insert(2, "--no-graphics")
+        self.process = subprocess.Popen(args, stdin=subprocess.DEVNULL,
+                                        stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
+        deadline = time.monotonic() + self.patience
+        while time.monotonic() < deadline:
+            said = self._tart("ip", self.name, check=False)
+            if said.returncode == 0 and said.stdout.strip():
+                self.guest.hostname = said.stdout.strip()
+                break
+            time.sleep(2)
+        if self.guest.hostname is None or not self.guest.reachable(
+                max(10.0, deadline - time.monotonic())):
+            self.__exit__()
+            raise GuestError(f"the clone {self.name} of {self.base} did not come up")
+        print(f"vm:      {self.name}, a clone of {self.base}, at {self.guest.hostname}")
+        return self
+
+    def __exit__(self, *exc):
+        self._tart("stop", self.name, check=False)
+        if self.process is not None:
+            try:
+                self.process.wait(30)
+            except subprocess.TimeoutExpired:
+                self.process.kill()
+        self._tart("delete", self.name, check=False)
+        self.guest.hostname = None
+        print(f"vm:      {self.name} deleted")
+        return False
+
+
+class VMwareMachine:
+    """A VMware Fusion VM reverted to a snapshot before the run.
+
+    A snapshot taken while the VM was running comes back running, signed in
+    and with SSH up, after `vmrun start`. The SMB share that was mounted on
+    the host does not survive the revert, so it is mounted again. The VM is
+    shut down afterwards, its share unmounted first: the next run reverts it
+    anyway, and a VM `vmrun` left running headless is one the Fusion app
+    cannot open. ``visible`` has no say here: `vmrun` can only resume it
+    without a window. ``vm_password`` is the VM's encryption password, which
+    `vmrun` needs for a VM with a vTPM.
+
+    Learnt on Fusion 26 with a vTPM-encrypted Windows 11 VM: `vmrun` cannot
+    linked-clone it ("Cannot read the virtual machine configuration file"),
+    nor snapshot it while it runs ("Authentication for encrypted virtual
+    machine failed") - take a running-state snapshot in the Fusion app, after
+    `vmrun suspend` (a headless VM does not show there).
+    """
+
+    VMRUN = "/Applications/VMware Fusion.app/Contents/Library/vmrun"
+
+    def __init__(self, guest: Guest, patience: float = 180.0):
+        self.guest, self.patience = guest, patience
+        settings = guest.settings
+        self.vmx = str(pathlib.Path(settings["vmx"]).expanduser())
+        self.snapshot = settings["snapshot"]
+        self.password = settings.get("vm_password")
+
+    def _vmrun(self, *args, check: bool = True) -> bool:
+        command = [self.VMRUN, "-T", "fusion"]
+        if self.password:
+            command += ["-vp", secret(self.password)]
+        # Into a file, not a pipe: `vmrun start` hands its stdout on to the
+        # vmware-vmx it starts, so a pipe would not close until the VM stops.
+        with tempfile.TemporaryFile("w+") as output:
+            said = subprocess.run(command + list(args), stdin=subprocess.DEVNULL,
+                                  stdout=output, stderr=subprocess.STDOUT, text=True)
+            output.seek(0)
+            if said.returncode != 0 and check:
+                raise GuestError(f"vmrun {args[0]}: {output.read().strip()}")
+            return said.returncode == 0
+
+    def __enter__(self):
+        self._vmrun("revertToSnapshot", self.vmx, self.snapshot)
+        # nogui: start with no argument means gui, which Fusion refuses for a
+        # VM a running-state snapshot left suspended ("The operation is not
+        # supported"). Opening Fusion afterwards shows the running VM.
+        self._vmrun("start", self.vmx, "nogui")
+        if not self.guest.reachable(self.patience):
+            raise GuestError(f"{self.guest.alias} did not answer over SSH after the revert "
+                             f"to {self.snapshot!r}")
+        self._mount()
+        self._wait_for_the_clock()
+        print(f"vm:      {self.guest.alias} reverted to {self.snapshot!r}")
+        return self
+
+    def _mount(self) -> None:
+        url = self.guest.settings.get("smb")
+        if not url:
+            return
+        mount = str(self.guest.host_share)
+        subprocess.run(["umount", mount], capture_output=True)
+        password = self.guest.settings.get("smb_password")
+        if password:
+            user, _, where = url.removeprefix("//").partition("@")
+            url = f"//{user}:{urllib.parse.quote(secret(password), safe='')}@{where}"
+        # -N: never prompt. Without smb_password, the Keychain's internet
+        # password for the server (Finder's "Remember") has to do.
+        said = subprocess.run(["mount_smbfs", "-N", url, mount],
+                              capture_output=True, text=True, stdin=subprocess.DEVNULL)
+        if said.returncode != 0:
+            raise GuestError(f"could not mount the share on {mount}: {said.stderr.strip()}")
+
+    def _wait_for_the_clock(self, patience: float = 60.0) -> None:
+        """A snapshot comes back with the time it was taken; VMware Tools
+        sets it right within seconds. Wait for that, so the run's own record
+        of times means something."""
+        deadline = time.monotonic() + patience
+        while time.monotonic() < deadline:
+            said = self.guest.ssh("[DateTimeOffset]::UtcNow.ToUnixTimeSeconds()"
+                                  if self.guest.windows else "date +%s")
+            try:
+                if abs(int(said.stdout.strip()) - time.time()) < 30:
+                    return
+            except ValueError:
+                pass
+            time.sleep(3)
+        print("vm:      the guest's clock is still off - carrying on")
+
+    def __exit__(self, *exc):
+        if self.guest.settings.get("smb"):
+            subprocess.run(["umount", str(self.guest.host_share)], capture_output=True)
+        # hard: the snapshot it is reverted to next time is all that counts.
+        if self._vmrun("stop", self.vmx, "hard", check=False):
+            print(f"vm:      {self.guest.alias} stopped")
+        else:
+            print(f"vm:      could not stop {self.guest.alias} - stop it before opening Fusion")
+        return False

quality_loop-0.4.0/quality_loop/guest/boot/__init__.py

@@ -0,0 +1,7 @@
+"""Scripts run in the guest, from a run's stage - never imported on the host.
+
+``launch.py`` starts a product's script in the desktop session with no console
+window; ``screen_agent.py`` performs one screen operation there. Both use
+only the standard library and the quality_loop files the stage carries
+(`quality_loop.guest.Guest.stage`).
+"""

quality_loop-0.4.0/quality_loop/guest/boot/launch.py

@@ -0,0 +1,35 @@
+"""A product's script in a Windows guest's desktop session, with no console.
+
+Not run on the host. `quality_loop.guest.Guest.launch` has a scheduled task
+run this with the image's pythonw.exe, the path of a JSON file as its one
+argument. A batch file would do the same with less code, but cmd.exe opens a
+console - on Windows 11 a Windows Terminal window - on the desktop the room
+looks at, and an app that hands the foreground back would hand it to that.
+
+What the batch file did is done here instead, from the JSON: the environment,
+the search path in front of the interpreter's own, the working directory, and
+stdout and stderr into the log. Then the script runs as __main__.
+"""
+
+import json
+import os
+import runpy
+import site
+import sys
+
+with open(sys.argv[1], encoding="utf-8") as f:
+    settings = json.load(f)
+
+# pythonw has no stdout or stderr: the log is both.
+log = open(settings["log"], "w", encoding="utf-8", buffering=1)
+sys.stdout = sys.stderr = log
+
+os.environ.update(settings.get("environ") or {})
+if site.USER_SITE in sys.path:
+    sys.path.remove(site.USER_SITE)
+sys.path[0:0] = settings.get("path") or []
+if settings.get("cwd"):
+    os.chdir(settings["cwd"])
+sys.argv = [settings["script"], *settings.get("argv", [])]
+
+runpy.run_path(settings["script"], run_name="__main__")

quality_loop-0.4.0/quality_loop/guest/boot/screen_agent.py

@@ -0,0 +1,54 @@
+"""One screen operation of quality-loop's own OS backend, run in the guest.
+
+Not run on the host. `quality_loop.guest.screens`, the screen backend the
+operator uses when the product runs in a VM, writes a request on the run's
+stage and runs this there: over SSH on macOS, from a scheduled task in the
+desktop session on Windows (a window opened from SSH lands where nobody sees
+it). The request names the operation, its arguments, and where to write the
+answer; the backend waits for that file.
+
+The operations are quality-loop's own (quality_loop.screens._mac and
+_windows, copied onto the stage), so a page or a terminal in the guest is put
+up and recognised exactly as on a desktop the operator shares.
+"""
+
+import json
+import os
+import sys
+import traceback
+
+# <stage>/ql/quality_loop/guest/boot/screen_agent.py -> <stage>/ql
+QL = os.path.dirname(os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__)))))
+sys.path.insert(0, QL)
+
+with open(sys.argv[1], encoding="utf-8") as f:
+    request = json.load(f)
+
+try:
+    from quality_loop.screens import ScreenError
+    if sys.platform == "darwin":
+        from quality_loop.screens import _mac as os_backend
+    else:
+        from quality_loop.screens import _windows as os_backend
+    op = request["op"]
+    if op == "open_page":
+        value = os_backend.open_page(request["url"], request["title"], request["patience"])
+    elif op == "open_terminal":
+        value = os_backend.open_terminal(request["command"], request["title"],
+                                         request["patience"])
+    elif op == "close":
+        os_backend.close(request["kind"], request["handle"])
+        value = None
+    else:
+        raise ValueError(f"no operation {op!r}")
+    answer = {"ok": True, "value": value}
+except ScreenError as error:
+    answer = {"ok": False, "error": str(error)}
+except Exception:
+    answer = {"ok": False, "error": traceback.format_exc()}
+
+# Written whole, then renamed: the host polls for the name.
+partial = request["result"] + ".partial"
+with open(partial, "w", encoding="utf-8") as f:
+    json.dump(answer, f)
+os.replace(partial, request["result"])

quality_loop-0.4.0/quality_loop/guest/screens.py

@@ -0,0 +1,138 @@
+"""The operator's screens, put up in the VM the product runs in.
+
+An adapter whose app runs in a guest returns this file from
+``screen_backend()``, with :func:`settings` as its settings::
+
+    def screen_backend(self):
+        return {"path": quality_loop.guest.screens.__file__,
+                "settings": quality_loop.guest.screens.settings(guest, stage)}
+
+and quality-loop loads it (`quality_loop.screens.load_backend`) in place of
+this machine's own, so `screen_open` puts a page or a terminal up on the
+guest's desktop - where the app reads the screen - and not on the host's.
+
+Each operation is quality-loop's own (screens._mac / _windows), run in the
+guest by ``boot/screen_agent.py`` from the run's stage: over SSH on macOS,
+from a scheduled task in the desktop session on Windows. A request and its
+answer are files on the share.
+
+Pages are served on the host's 127.0.0.1 by the runner. A reverse tunnel
+(`ssh -R`, same port) makes that address the guest's too, so the URL, and the
+page's POSTed events, work unchanged. One tunnel per port, started by the
+first page that needs it; its pid is kept on the stage, and the run's end
+(`quality_loop.guest.end_tunnels`) ends it.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import pathlib
+import shutil
+import time
+import urllib.parse
+import uuid
+
+from quality_loop.guest import Guest, sh_quote
+from quality_loop.screens import ScreenError
+
+_guest: Guest | None = None
+_stage: pathlib.Path | None = None
+_terminal_python: str | None = None
+
+
+def settings(guest: Guest, stage: pathlib.Path, terminal_python: str | None = None) -> dict:
+    """What :func:`configure` needs, from the adapter's live guest and stage.
+    ``terminal_python`` runs a terminal screen's script in the guest; the
+    image's interpreter by default."""
+    return dict(guest.to_settings(), stage=str(stage),
+                terminal_python=terminal_python or guest.python)
+
+
+def configure(settings: dict) -> None:
+    global _guest, _stage, _terminal_python
+    _guest = Guest.from_screen_settings(settings)
+    _stage = pathlib.Path(settings["stage"])
+    _terminal_python = settings.get("terminal_python") or _guest.python
+
+
+def _call(request: dict, patience: float):
+    """Run one operation in the guest and answer its value."""
+    requests = _stage / "screens"
+    requests.mkdir(exist_ok=True)
+    name = uuid.uuid4().hex[:12]
+    asked, answered = requests / f"{name}.json", requests / f"{name}-answer.json"
+    request = dict(request, result=_guest.path(answered))
+    asked.write_text(json.dumps(request), encoding="utf-8")
+    agent = _guest.boot_script(_stage, "screen_agent.py")
+    task = f"ql-screen-{name}"
+    try:
+        if _guest.windows:
+            try:
+                _guest.run_in_session(_stage, task, _guest.windowless(_guest.python),
+                                      agent, _guest.path(asked))
+            except Exception as error:
+                raise ScreenError(str(error)) from None
+        else:
+            # Synchronous over SSH; Safari and Terminal are driven through
+            # Apple Events, which the guest's base image has allowed for SSH.
+            said = _guest.ssh(f"{sh_quote(_guest.python)} {sh_quote(_guest.path(agent))} "
+                              f"{sh_quote(_guest.path(asked))}", timeout=patience + 120)
+            if said.returncode != 0 and not answered.exists():
+                raise ScreenError(f"the VM did not run it: {said.stderr.strip()[:500]}")
+        deadline = time.monotonic() + patience + 60
+        while not answered.exists():
+            if time.monotonic() > deadline:
+                raise ScreenError(f"no answer from the VM within {patience + 60:.0f}s")
+            time.sleep(0.5)
+        answer = json.loads(answered.read_text(encoding="utf-8"))
+    finally:
+        if _guest.windows:
+            _guest.forget_task(task)
+        for leftover in (asked, answered, _stage / f"{task}.xml"):
+            leftover.unlink(missing_ok=True)
+    if not answer["ok"]:
+        raise ScreenError(f"in the VM: {answer['error']}")
+    return answer["value"]
+
+
+def _tunnel(port: int) -> None:
+    """The host's 127.0.0.1:port as the guest's, once per port."""
+    tunnels = _stage / "tunnels"
+    tunnels.mkdir(exist_ok=True)
+    pid_file = tunnels / f"{port}.pid"
+    if pid_file.exists():
+        try:
+            os.kill(int(pid_file.read_text()), 0)
+            return
+        except (OSError, ValueError):
+            pass
+    process = _guest.reverse(port)
+    pid_file.write_text(str(process.pid))
+    time.sleep(2)
+    if process.poll() is not None:
+        pid_file.unlink(missing_ok=True)
+        raise ScreenError(f"could not forward the pages' port {port} into the VM")
+
+
+def open_page(url: str, title: str, patience: float):
+    _tunnel(urllib.parse.urlsplit(url).port)
+    return _call({"op": "open_page", "url": url, "title": title, "patience": patience},
+                 patience)
+
+
+def open_terminal(command: list[str], title: str, patience: float):
+    # The runner's command is this machine's: its interpreter, and a copy of
+    # the script outside the checkout. The guest gets its own interpreter and
+    # a copy of the script on the share.
+    script = pathlib.Path(command[-1])
+    scripts = _stage / "scripts"
+    scripts.mkdir(exist_ok=True)
+    shutil.copy2(script, scripts / script.name)
+    guest_command = [_terminal_python, _guest.path(scripts / script.name)]
+    return _call({"op": "open_terminal", "command": guest_command, "title": title,
+                  "patience": patience}, patience)
+
+
+def close(kind: str, handle) -> None:
+    _call({"op": "close", "kind": kind, "handle": handle}, 15)

{quality_loop-0.3.0 → quality_loop-0.4.0/quality_loop.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: quality-loop
-Version: 0.3.0
+Version: 0.4.0
 Summary: Measure what a product teaches - its skill, tools or manual - with isolated agent runs of real tasks, reported by an operator agent
 Author: craftware
 License-Expression: MIT
@@ -110,6 +110,8 @@ under a policy the person sets. See [Running the loop](https://github.com/crftwr
   launch command and a redirected home up to evidence tools of its own.
 - [Reports](https://github.com/crftwr/quality-loop/blob/main/docs/reports.md): problems, severities, kinds and ids, the
   reproduction record, and `FINDINGS.md` / `findings.json`.
+- [Running the app in a VM](https://github.com/crftwr/quality-loop/blob/main/docs/guests.md): one image per OS,
+  the guest over SSH, a clean machine every run, screens in the guest.
 - [Isolation and permissions](https://github.com/crftwr/quality-loop/blob/main/docs/isolation.md): what keeps the room, the
   operator and the conductor in bounds, why each rule exists, and the known limits.
 - [Development](https://github.com/crftwr/quality-loop/blob/main/docs/development.md): tests, live tests, releasing.

{quality_loop-0.3.0 → quality_loop-0.4.0}/quality_loop.egg-info/SOURCES.txt

@@ -33,6 +33,11 @@ quality_loop/drive/_mac.py
 quality_loop/drive/_windows.py
 quality_loop/drive/keys.py
 quality_loop/drive/terminal.py
+quality_loop/guest/__init__.py
+quality_loop/guest/screens.py
+quality_loop/guest/boot/__init__.py
+quality_loop/guest/boot/launch.py
+quality_loop/guest/boot/screen_agent.py
 quality_loop/screens/__init__.py
 quality_loop/screens/_mac.py
 quality_loop/screens/_windows.py
@@ -41,6 +46,7 @@ quality_loop/skill/references/filing.md
 quality_loop/skill/references/setup.md
 tests/test_core.py
 tests/test_drive.py
+tests/test_guest.py
 tests/test_loop.py
 tests/test_mcp.py
 tests/test_operator.py

quality_loop-0.4.0/tests/test_guest.py

@@ -0,0 +1,215 @@
+"""The guest layer, without a VM: SSH is faked, and what runs in the guest -
+the boot scripts - is run here, on the stage it would read in the guest.
+
+A real VM is checked by the products that use it (Keyhac's and XeFM's qa/).
+"""
+
+import json
+import pathlib
+import subprocess
+import sys
+
+import pytest
+
+from quality_loop import guest as guests
+from quality_loop.guest import Guest, GuestError
+from quality_loop.guest import screens as guest_screens
+from quality_loop.screens import ScreenError
+
+
+@pytest.fixture
+def share(tmp_path):
+    share = tmp_path / "share"
+    share.mkdir()
+    return share.resolve()
+
+
+def _guest(share, windows=False, **settings):
+    guest = Guest("qa-test", share, r"C:\qa" if windows else str(share),
+                  {"python": sys.executable, **settings})
+    guest._windows = windows
+    return guest
+
+
+class FakeSSH:
+    """Records commands; answers with ``answer(command)``."""
+
+    def __init__(self, answer=lambda command: ("", 0)):
+        self.commands, self.answer = [], answer
+
+    def __call__(self, command, timeout=60):
+        self.commands.append(command)
+        out, code = self.answer(command)
+        return subprocess.CompletedProcess([], code, out, "")
+
+
+# --- settings ---------------------------------------------------------------------
+
+def test_settings_by_alias_from_the_named_file(tmp_path, monkeypatch, share):
+    where = tmp_path / "guests.toml"
+    where.write_text(f'[qa-win]\nshare = "{share}=C:\\\\qa"\npython = "C:\\\\P\\\\python.exe"\n')
+    monkeypatch.setenv("QUALITY_LOOP_GUESTS", str(where))
+    assert guests.settings_for("qa-win")["python"] == r"C:\P\python.exe"
+    assert guests.settings_for("nobody") == {}
+    monkeypatch.setenv("QA_GUEST", "qa-win")
+    guest = Guest.from_environment("QA_GUEST")
+    assert (guest.host_share, guest.guest_share) == (share, r"C:\qa")
+    assert Guest.from_environment("UNSET_QA_GUEST") is None
+
+
+def test_a_share_needs_both_sides_and_an_existing_host_side(share):
+    with pytest.raises(GuestError, match="share ="):
+        Guest.from_settings("x", {"share": str(share)})
+    with pytest.raises(GuestError, match="not a directory"):
+        Guest.from_settings("x", {"share": f"{share}/missing=C:\\qa"})
+
+
+def test_python_must_be_named(share):
+    guest = Guest("x", share, "C:\\qa", {})
+    with pytest.raises(GuestError, match="python ="):
+        guest.python
+
+
+def test_a_keychain_secret_is_read_and_anything_else_passes(monkeypatch):
+    assert guests.secret("plain") == "plain"
+    monkeypatch.setattr(subprocess, "run", lambda *a, **k: subprocess.CompletedProcess(
+        a, 0, "s3cret\n", ""))
+    assert guests.secret("keychain:qa-vm") == "s3cret"
+
+
+# --- paths and quoting ---------------------------------------------------------------
+
+def test_a_host_path_as_the_guest_sees_it(share):
+    (share / "stage").mkdir()
+    assert _guest(share, windows=True).path(share / "stage" / "a.json") == r"C:\qa\stage\a.json"
+    assert _guest(share).path(share / "stage") == f"{share}/stage"
+
+
+def test_the_task_keeps_program_and_arguments_apart():
+    xml = guests.task_xml(r"C:\P\pythonw.exe", '"-s" "C:\\qa\\a & b.py"')
+    assert "<Command>C:\\P\\pythonw.exe</Command>" in xml
+    assert "a &amp; b.py" in xml and "InteractiveToken" in xml
+
+
+def test_quoting():
+    assert guests.ps_quote("it's") == "'it''s'"
+    assert guests.sh_quote("it's") == "'it'\\''s'"
+
+
+def test_windowless_is_pythonw_beside_it(share):
+    assert _guest(share, windows=True).windowless(r"C:\P\python.exe") == r"C:\P\pythonw.exe"
+    assert _guest(share).windowless("/usr/bin/python3") == "/usr/bin/python3"
+
+
+# --- the stage, the venv, the session --------------------------------------------------
+
+def test_the_stage_carries_the_screens_and_the_boot_scripts(share):
+    stage = _guest(share).stage()
+    ql = stage / "ql" / "quality_loop"
+    assert (ql / "__init__.py").exists() and (ql / "screens" / "_windows.py").exists()
+    assert _guest(share).boot_script(stage, "screen_agent.py").exists()
+    assert not list(stage.rglob("__pycache__"))
+
+
+def test_the_venv_is_made_in_the_guest_with_the_cache_on_the_share(share, monkeypatch):
+    guest = _guest(share, windows=True, python=r"C:\Python314\python.exe")
+    ssh = FakeSSH(lambda c: ("C:\\Users\\qa\\AppData\\Local\\ql-venv-x\\Scripts\\python.exe\n", 0))
+    monkeypatch.setattr(guest, "ssh", ssh)
+    stage = guest.stage()
+    python = guest.venv(stage, ["pillow>=9", "truststore"])
+    assert python.endswith(r"Scripts\python.exe")
+    (command,) = ssh.commands
+    assert r"'C:\Python314\python.exe' -m venv" in command
+    assert r"--cache-dir 'C:\qa\.pip-cache'" in command
+    assert (share / ".pip-cache").is_dir()
+    assert (stage / "requirements.txt").read_text() == "pillow>=9\ntruststore\n"
+
+
+def test_a_failed_install_says_what_pip_said(share, monkeypatch):
+    guest = _guest(share)
+    monkeypatch.setattr(guest, "ssh", FakeSSH(lambda c: ("No matching distribution", 1)))
+    with pytest.raises(GuestError, match="No matching distribution"):
+        guest.venv(guest.stage(), ["nothing-like-this"])
+
+
+def test_run_in_session_is_a_task_and_launch_hands_it_the_json(share, monkeypatch):
+    guest = _guest(share, windows=True)
+    ssh = FakeSSH(lambda c: ("SUCCESS: Attempted to run the scheduled task", 0))
+    monkeypatch.setattr(guest, "ssh", ssh)
+    stage = guest.stage()
+    guest.launch(stage, "ql-app", r"C:\P\pythonw.exe", script=r"C:\qa\app.py",
+                 log=stage / "app.log", environ={"HOME": r"C:\qa\home"}, argv=["--x"])
+    (command,) = ssh.commands
+    assert "schtasks /create /tn 'ql-app'" in command and "schtasks /run" in command
+    launch = json.loads((stage / "ql-app.json").read_text())
+    assert launch["environ"] == {"HOME": r"C:\qa\home"} and launch["argv"] == ["--x"]
+    assert "launch.py" in (stage / "ql-app.xml").read_text(encoding="utf-16")
+
+
+def test_run_in_session_says_when_the_task_did_not_start(share, monkeypatch):
+    guest = _guest(share, windows=True)
+    monkeypatch.setattr(guest, "ssh", FakeSSH(lambda c: ("ERROR: Access is denied.", 0)))
+    with pytest.raises(GuestError, match="Access is denied"):
+        guest.run_in_session(guest.stage(), "t", "pythonw.exe", share / "x.py")
+    with pytest.raises(GuestError, match="Windows guest"):
+        _guest(share).run_in_session(share, "t", "python", share / "x.py")
+
+
+def test_launch_runs_the_script_with_its_environment_path_and_log(share, tmp_path):
+    """boot/launch.py itself, run here as the task would run it there."""
+    stage = _guest(share).stage()
+    lib = tmp_path / "lib"
+    lib.mkdir()
+    (lib / "helper.py").write_text("WHO = 'staged'\n")
+    script = tmp_path / "app.py"
+    script.write_text("import os, sys, helper\n"
+                      "print(helper.WHO, os.environ['QL_X'], sys.argv[1:], os.getcwd())\n")
+    settings = {"log": str(stage / "app.log"), "script": str(script),
+                "environ": {"QL_X": "set"}, "path": [str(lib)], "cwd": str(tmp_path),
+                "argv": ["--flag"]}
+    (stage / "launch.json").write_text(json.dumps(settings))
+    subprocess.run([sys.executable, "-s", str(_guest(share).boot_script(stage, "launch.py")),
+                    str(stage / "launch.json")], check=True)
+    assert (stage / "app.log").read_text().strip() == f"staged set ['--flag'] {tmp_path}"
+
+
+# --- the screen backend ----------------------------------------------------------------
+
+def test_the_backend_runs_the_agent_in_the_guest_and_reads_its_answer(share, monkeypatch):
+    """macOS shape: the agent over SSH - here, run locally on the stage."""
+    guest = _guest(share)
+    stage = guest.stage()
+    settings = guest_screens.settings(guest, stage)
+    assert settings["terminal_python"] == sys.executable
+    guest_screens.configure(settings)
+
+    def run_agent(command, timeout=60):
+        agent = guest.boot_script(stage, "screen_agent.py")
+        asked = command.rsplit(" ", 1)[1].strip("'")
+        return subprocess.run([sys.executable, str(agent), asked],
+                              capture_output=True, text=True)
+
+    monkeypatch.setattr(guest_screens._guest, "ssh", run_agent)
+    with pytest.raises(ScreenError, match="no operation 'paint'"):
+        guest_screens._call({"op": "paint"}, patience=5)
+    assert not list((stage / "screens").iterdir()), "the request and answer are cleaned up"
+
+
+def test_a_terminal_script_is_staged_and_run_with_the_guest_python(share, monkeypatch, tmp_path):
+    guest = _guest(share)
+    stage = guest.stage()
+    guest_screens.configure(guest_screens.settings(guest, stage, terminal_python="/g/python"))
+    seen = {}
+    monkeypatch.setattr(guest_screens, "_call", lambda request, patience: seen.update(request))
+    script = tmp_path / "deploy.py"
+    script.write_text("print('x')\n")
+    guest_screens.open_terminal(["/host/python", str(script)], "deploy", 5)
+    assert seen["command"] == ["/g/python", str(stage / "scripts" / "deploy.py")]
+    assert (stage / "scripts" / "deploy.py").exists()
+
+
+def test_machine_follows_the_settings(share):
+    assert isinstance(_guest(share, tart="base").machine(), guests.TartMachine)
+    assert isinstance(_guest(share, vmx="/v.vmx", snapshot="s").machine(), guests.VMwareMachine)
+    with _guest(share).machine():
+        pass