Docs: update screenshots and videos

A Frame that only authorizes the user's own key refused OpenSSH, which
offered FramePort's keys alone (IdentitiesOnly), so every upload fell back
to Paramiko. The connection now records which login worked (Frame.auth):
after a login with this PC's own keys/agent OpenSSH also offers private
copies of ~/.ssh/id_* (OpenSSH skips its defaults once -i is given) and the
agent; a refused strict login is retried that way once. FramePort doesn't
add its key to the Frame for this.

New: Settings > Installing > SSH keys (library ssh.extra_keys, CLI
frameport frame ssh-keys): extra private key files for the connection and
OpenSSH, checked with Paramiko (passphrase keys: use the agent). OpenSSH
runs with -v and a refused login's error lists the keys offered and its
warnings. whoami's SID is read from bytes (non-ASCII user names).
Checked with Windows ssh.exe/sftp.exe against the Frame.

CLAUDE.md

@@ -904,6 +904,13 @@ hide_space_warp / vk_hide_fdm / no Valve layers; FNAF HW (#135) "freeze" = first
 on Zink (threads busy in zink/disk cache), not a hang; VR4 (#199) reporter's patch.203 OBB truncated. Upload benchmark
 (`scripts/upload_bench.py`, #242): home Wi-Fi caps every method at ~11 MB/s; paramiko uses ~3x OpenSSH's CPU; Windows
 OpenSSH refuses FramePort's key file (ACL "bad permissions") until its permissions are tightened.
+**OpenSSH uploads (2026-10-15, #324/#242):** sftp escapes `* ? [` inside double quotes itself (and undoes it for
+put's destination), so `native_upload.quote` escapes only `\\`/`"`; Win32 sftp turns every local backslash into `/`
+(escapes too) → local paths go as `C:/…`. Logins: `Frame.auth` = the attempt that worked (app_key / user_key = a key
+file from Settings → Installing → SSH keys, library `ssh.extra_keys`, CLI `frame ssh-keys` / agent / password).
+OpenSSH strict (FramePort + Settings keys, IdentitiesOnly) unless auth was "agent"; a refused strict login retries
+relaxed (+ private copies of ~/.ssh/id_{rsa,dsa,ecdsa,ed25519}: OpenSSH skips its defaults once any -i is given, + the
+agent); `-v` key lines go into the error. FramePort doesn't add its key to the Frame for this. Windows-tested.
 **Meta user id (GitHub #182, 2026-10-11):** OVRPort's platform loader (runtimes 3.4.3-23204ea and -aa54c3f) answers
 `ovr_GetLoggedInUserID` (and two other callers) without a Meta account with a made-up id from a helper (`stp; mov x29,
 sp; bl random; …; mov/movk x9 = 0x53444835ec580000 (6e18); add x0, x8, x9; ldp; ret`), kept only in memory → a new id

catalog/games/com.asg.clockworkdev.yaml

@@ -1,5 +1,5 @@
 package: com.asg.clockworkdev
-title: Clockwork
+title: The Last Clockwinder
 status: works
 tested_version: '1.29'
 engine: Unity

docs/GAMES.md

@@ -31,7 +31,6 @@ Generated from [catalog/games](../catalog/games) by `scripts/compat_list.py`.
 | BONELAB | Quest | ✅ Works |  |
 | Carve Snowboarding | Quest | ✅ Works |  |
 | Caves | Quest | ✅ Works |  |
-| Clockwork | Quest | ✅ Works |  |
 | COMPOUND | Quest | ✅ Works |  |
 | Cook-Out | Quest | ✅ Works |  |
 | Cosmodread | Quest | ✅ Works |  |
@@ -129,6 +128,7 @@ Generated from [catalog/games](../catalog/games) by `scripts/compat_list.py`.
 | TetrisEffect | Quest | ✅ Works |  |
 | The Boys VR | Quest | ✅ Works |  |
 | The Climb 2 | Quest | ✅ Works |  |
+| The Last Clockwinder | Quest | ✅ Works |  |
 | The Room VR | Quest | ✅ Works |  |
 | The Tale of Onogoro | Quest | ✅ Works |  |
 | Time Crisis II VR (Test) | Quest | ✅ Works |  |

docs/PATCHES.md

@@ -904,7 +904,7 @@ Stops a gray or frozen screen in Unity games that turn on anti-aliasing while ru
 - `frame.unity_gl_shim`
 - **Changes:** Changes the APK (a rebuild and reinstall apply it).
 - **Suggested (on):** Unity GLES game that may switch to MSAA at runtime: hide multisampled render-to-texture, which crashes the Frame's GL driver (for example The Room VR).
-- **Catalog games (23):** Audica, BattleSisters, Beat Saber, Clockwork, COMPOUND, Cosmodread, Down the Rabbit Hole, Drunkn Bar Fight and 15 more.
+- **Catalog games (23):** Audica, BattleSisters, Beat Saber, COMPOUND, Cosmodread, Down the Rabbit Hole, Drunkn Bar Fight, End Space and 15 more.
 - **Suggested by launch-test signatures:**
   - `unreal-msrtt-crash` (fatal): The game's graphics crashed a few seconds after start.
 - **Source:** [patches/frame/vrapi_bridge.py](../src/frameport/patches/frame/vrapi_bridge.py)
@@ -973,7 +973,7 @@ Keeps a smoothing setting off that the game turns on itself and that can freeze
 - `frame.unity_runtime_msaa_off` · revision 2
 - **Changes:** Changes the APK (a rebuild and reinstall apply it).
 - **Suggested (on):** GLES Unity game whose OVRManager turns 4x MSAA on at runtime: multisampled render-to-texture can hang the Frame's GPU.
-- **Catalog games (28):** Audica, BattleSisters, Beat Saber, Clockwork, COMPOUND, Cosmodread, Down the Rabbit Hole, Drunkn Bar Fight and 20 more.
+- **Catalog games (28):** Audica, BattleSisters, Beat Saber, COMPOUND, Cosmodread, Down the Rabbit Hole, Drunkn Bar Fight, End Space and 20 more.
 - **Suggested by launch-test signatures:**
   - `unity-render-crash` (fatal): The game's graphics crashed, so the picture freezes or stays gray.
   - `unity-runtime-msaa` (info): The game turns MSAA on at runtime, which can hang the Frame's GPU.

docs/PLAYBOOK.md

@@ -63,6 +63,8 @@ version is `catalog/triage.yaml` (used by `frameport test` / the Job screen); ke
 | Un-cracked Oculus PC VR game: "Initializing OVR session" then exits / signature check on the runtime | Revive's hooks don't install on Proton-arm64; the Oculus shim rejects the unsigned Revive runtime | Not runnable on the Frame without the repack's crack extracted (not done by FramePort); use the PC version |
 | PC VR game: `Failed to initialize Oculus API (-3001)` / `Unable to load LibOVRRT DLL` | Revive's LoadLibrary hook doesn't work under Proton arm64 (ARM64EC kernelbase); the game's LibOVR shim finds no runtime DLL | Symlink `LibOVRRT64_1.dll` → Revive's DLL in the prefix's system32 (manual so far) → then -3021 (runtime signature check; open) |
 | Uploads to the Frame are slow | The link, storage or transfer backend can limit throughput | Check the job's "Transfer link"; try the Frame's hotspot or USB cable. Large install files prefer system OpenSSH SFTP, retaining paired-host checks and `.part` resume; unavailable or failed native uploads fall back to Paramiko. The log names the backend. Settings → Installing → Parallel uploads accepts 1–8 (default 3; saved preferences are preserved). More is not always faster. Measure the production path with `scripts/upload_bench.py --methods app-files-3 --check-resume` (three repetitions, checksum verification) |
+| Log: `OpenSSH SFTP failed (255): … Permission denied (publickey,password)`, then Paramiko | OpenSSH offered keys the Frame doesn't authorize (GitHub #242) | The log lists the keys OpenSSH offered (`Offering public key`) and its warnings. A connection that logged in with the PC's own keys/agent makes OpenSSH use them too (copies of `~/.ssh/id_*` + the agent); a refused FramePort key is retried that way once. A Frame that accepts only another key file: Settings → Installing → SSH keys (CLI `frameport frame ssh-keys --add <file>`); passphrase keys go through the SSH agent |
+| Log: `OpenSSH SFTP failed (1): stat C://…/[…: No such file or directory` | sftp got glob escapes inside its quotes (GitHub #324, fixed): `[` in a local folder name | Update FramePort; the native_upload `quote()` passes only `\\` and `\"` escapes, Windows paths with `/` |
 | PC VR game exits right away: `Unhandled Exception: 0xc06d007e` (after `FOnlineSubsystemOculus::InitWithWindowsPlatform`) | Delay-loaded `LibOVRPlatform64_1.dll` (Oculus Platform SDK, installed with the Oculus app) is missing | None on the Frame (entitlement check; FramePort doesn't replace it). PC mode with the Oculus app |
 | Unity PC VR game (Oculus + SteamVR build: `OVRPlugin.dll` and `openvr_api.dll` in `<Name>_Data/Plugins`) opens a window and quits after ~20 s; no VR Vulkan instance after the game's DXVK device in launch.log; Unity log (`unity log … Player.log`, agent v67): `OpenVR failed initialization` / `Initialization of device … failed` | Unity's built-in VR tries its SDKs in list order (Oculus first) unless `-vrmode` picks one; a catalog recipe verified with another build of the game (for example SUPERHOT VR's OpenXR build, GitHub #105) used to drop the build's own arguments | `pcvr.launch_args` = `-vrmode OpenVR` (detected for such builds; kept when the catalog's `xr` differs from the build's). A game's Electron launcher next to it (SHVR.exe) is ranked below the game |
 | Unreal PC VR game opens the crash reporter instead of closing | UE starts CrashReportClient.exe on a crash | `pcvr.no_crash_reporter` (default for Unreal Rift games): `-nocrashreports` + CrashReportClient.exe renamed `.disabled` in the Frame copy |

scripts/ui_smoke.py

@@ -137,7 +137,8 @@ def main() -> int:
              ("monitor", lambda a: a.go("monitor")), ("monitor-details", open_monitor_details),
              ("tools", lambda a: a.go("settings")),
              # the index on the left: "This PC" scrolls the page there
-             ("settings-index", lambda a: a.page.run_task(a.settings_view.show_section, "pc"))]
+             ("settings-index", lambda a: a.page.run_task(a.settings_view.show_section, "pc")),
+             ("settings-installing", lambda a: a.page.run_task(a.settings_view.show_section, "installing"))]
     if game:
         steps.insert(1, ("game", lambda a: a.open_game(game)))
         steps.insert(2, ("game-customize", lambda a: a.open_game(game, advanced=True)))

src/frameport/cli.py

@@ -706,6 +706,31 @@ def frame_trust_key(frame: Optional[str] = typer.Option(None, help=FRAME_HELP)):
     typer.echo(f"connected: {info.get('hostname') or t.host} (new key saved)")
 
 
+@frame_app.command("ssh-keys")
+def frame_ssh_keys(add: list[str] = typer.Option([], "--add", help="a private key file to log in with too"),
+                   remove: list[str] = typer.Option([], "--remove", help="stop using this key file (it stays)")):
+    """Private SSH key files FramePort logs in with besides its own key (Settings → Installing → SSH keys): for a
+    Frame that accepts only your own key. The Frame connection and OpenSSH uploads both use them. Lists them."""
+    from .frame.connection import KeyFileError, add_extra_key, extra_key_status, remove_extra_key
+
+    failed = False
+    for path in remove:
+        typer.echo(f"removed {path}" if remove_extra_key(path) else f"not in the list: {path}")
+    for path in add:
+        try:
+            typer.echo(f"added {add_extra_key(path)}")
+        except KeyFileError as exc:
+            typer.echo(f"can't use {path}: {exc}", err=True)
+            failed = True
+    status = extra_key_status()
+    for path, problem in status:
+        typer.echo(f"{path}" + (f"  (not usable: {problem})" if problem else ""))
+    if not status:
+        typer.echo("no extra keys: FramePort's own key and your SSH agent's keys only")
+    if failed:
+        raise typer.Exit(1)
+
+
 @frame_app.command("usb-check")
 def frame_usb_check(frame: Optional[str] = typer.Option(None, help=FRAME_HELP),
                     no_speed: bool = typer.Option(False, help="skip the upload speed test (2 × 128 MB)")):

src/frameport/frame/connection.py

@@ -1,8 +1,8 @@
 """SSH connection to a Steam Frame and the remote agent protocol.
 
 Authentication: FramePort's own keys first (<user data>/ssh/id_ed25519, installed by the bootstrap script, and
-id_rsa, registered through Valve's devkit pairing, which only takes RSA keys), then the user's SSH agent/keys, then a
-password if given.
+id_rsa, registered through Valve's devkit pairing, which only takes RSA keys), then key files the user added in
+Settings (EXTRA_KEYS_SETTING), then the user's SSH agent/keys, then a password if given.
 """
 from __future__ import annotations
 
@@ -163,6 +163,96 @@ def app_keys() -> list[paramiko.PKey]:
     return keys
 
 
+EXTRA_KEYS_SETTING = "ssh.extra_keys"  # library setting: private key files the user added (Settings → Installing)
+
+
+class KeyFileError(ValueError):
+    """A key file the user named can't be used (missing, not a private key, protected with a passphrase)."""
+
+
+def load_key_file(path) -> paramiko.PKey:
+    """A private key FramePort can log in with, or KeyFileError with a sentence saying why not."""
+    p = Path(path).expanduser()
+    if not p.is_file():
+        raise KeyFileError(f"{p}: file not found")
+    try:
+        return paramiko.PKey.from_path(p)
+    except (paramiko.SSHException, ValueError, OSError, UnicodeDecodeError, TypeError) as exc:
+        # paramiko says so with PasswordRequiredException (PEM) or a plain SSHException (OpenSSH format)
+        if isinstance(exc, paramiko.PasswordRequiredException) or "password" in str(exc).lower():
+            raise KeyFileError(f"{p.name} is protected with a passphrase, which FramePort can't ask for: add the "
+                               "key to your SSH agent instead (FramePort also logs in with the agent's keys)") from None
+        raise KeyFileError(f"{p.name} isn't a private SSH key FramePort can read "
+                           f"(OpenSSH or PEM format; a .pub file is the public half): {exc}") from None
+
+
+def extra_key_paths() -> list[Path]:
+    """The key files from Settings, as stored (each may be missing or unreadable by now: see extra_keys)."""
+    try:
+        from ..core import library
+
+        stored = library.peek_setting(EXTRA_KEYS_SETTING, [])
+    except Exception:  # noqa: BLE001 - no library yet
+        return []
+    if isinstance(stored, str):
+        stored = [stored]
+    paths: list[Path] = []
+    for value in stored if isinstance(stored, list) else []:
+        if isinstance(value, str) and value.strip():
+            p = Path(value.strip()).expanduser()
+            if p not in paths:
+                paths.append(p)
+    return paths
+
+
+def add_extra_key(path) -> Path:
+    """Check a key file (KeyFileError if FramePort can't use it) and add it to Settings. Returns the stored path."""
+    p = Path(path).expanduser()
+    if p.name.endswith(".pub") and p.with_name(p.name[:-4]).is_file():
+        raise KeyFileError(f"{p.name} is the public half: pick {p.name[:-4]} (the file without .pub) instead")
+    load_key_file(p)
+    p = p.resolve()
+    from ..core import library
+
+    library.update_setting(EXTRA_KEYS_SETTING, lambda old: [v for v in (old if isinstance(old, list) else [])
+                                                              if Path(v).expanduser() != p] + [str(p)], [])
+    return p
+
+
+def remove_extra_key(path) -> bool:
+    """Take a key file out of Settings (the file itself stays). False if it wasn't there."""
+    from ..core import library
+
+    p = Path(path).expanduser()
+    before = extra_key_paths()
+    library.update_setting(EXTRA_KEYS_SETTING, lambda old: [v for v in (old if isinstance(old, list) else [])
+                                                              if Path(v).expanduser() != p], [])
+    return p in before
+
+
+def extra_key_status() -> list[tuple[Path, str]]:
+    """Each key file from Settings with "" when usable, else why not (for Settings and the CLI)."""
+    status = []
+    for path in extra_key_paths():
+        try:
+            load_key_file(path)
+            status.append((path, ""))
+        except KeyFileError as exc:
+            status.append((path, str(exc)))
+    return status
+
+
+def extra_keys() -> list[tuple[Path, paramiko.PKey]]:
+    """The usable keys from Settings; unusable ones are logged and skipped (a login still tries the others)."""
+    keys = []
+    for path in extra_key_paths():
+        try:
+            keys.append((path, load_key_file(path)))
+        except KeyFileError as exc:
+            log.warning("SSH key from Settings skipped: %s", exc)
+    return keys
+
+
 @dataclass
 class FrameTarget:
     host: str
@@ -409,6 +499,10 @@ class Frame:
     _video_codec_digest: str = ""  # "<manifest digest>:<on|off>" handled on this connection (incl. a failed install)
     _video_codec_lock: threading.Lock = field(default_factory=threading.Lock)
     home: str = ""
+    # how the last login worked: "app_key" (FramePort's own key), "user_key" (a key file from Settings),
+    # "agent" (this PC's SSH agent / ~/.ssh keys) or "password"; OpenSSH uploads follow it (native_upload)
+    auth: str = ""
+    openssh_relaxed: bool | None = None  # native_upload: True once OpenSSH needed this PC's own keys/agent
 
     # ------------------------------------------------------------------ connect
     def connect(self, timeout: float = 10) -> Frame:
@@ -459,7 +553,8 @@ class Frame:
         kwargs = dict(hostname=self.target.host, port=self.target.port, username=self.target.user, timeout=timeout,
                       banner_timeout=timeout, auth_timeout=timeout)
         errors = []
-        attempts = [("app_key", k) for k in app_keys()] + [("agent", None), ("password", None)]
+        attempts = ([("app_key", k) for k in app_keys()] + [("user_key", k) for _, k in extra_keys()]
+                    + [("agent", None), ("password", None)])
         for attempt, pkey in attempts:
             if attempt == "password" and not self.password:
                 continue
@@ -467,7 +562,7 @@ class Frame:
             client.load_host_keys(str(known))
             client.set_missing_host_key_policy(paramiko.AutoAddPolicy())  # trust on first use (pairing)
             try:
-                if attempt == "app_key":
+                if attempt in ("app_key", "user_key"):
                     client.connect(pkey=pkey, allow_agent=False, look_for_keys=False, **kwargs)
                 elif attempt == "agent":
                     client.connect(allow_agent=True, look_for_keys=True, **kwargs)
@@ -492,6 +587,7 @@ class Frame:
                 raise
         else:
             raise FrameNotPaired(bool(self.password), errors)
+        self.auth = attempt
         client.save_host_keys(str(known))
         transport = client.get_transport()
         transport.set_keepalive(15)

src/frameport/frame/native_upload.py

@@ -2,10 +2,9 @@
 from __future__ import annotations
 
 import contextlib
-import csv
-import io
 import os
 import posixpath
+import re
 import shutil
 import signal
 import subprocess
@@ -13,19 +12,30 @@ import tarfile
 import tempfile
 import threading
 import time
-from pathlib import Path
+from pathlib import Path, PureWindowsPath
 
-from .connection import sh_quote, ssh_dir
+from .connection import extra_keys, sh_quote, ssh_dir
 
 
-def quote(value) -> str:
+def quote(value, windows=False) -> str:
+    """One sftp batch argument, taken literally.
+
+    Inside double quotes sftp escapes glob characters (* ? [) itself and undoes that for put's destination, so
+    they must NOT be escaped again: an extra backslash became part of the name (GitHub #324: "[ENG]" in a folder
+    name made every OpenSSH upload fail, on Linux too). Only backslash and the quote are escaped. ``windows``: a
+    local Windows path goes with forward slashes; Win32-OpenSSH's sftp turns every backslash of a local path into
+    '/', escapes included ("C:\\\\Users" → "C://Users").
+    """
     value = str(value)
     if any(c in value for c in "\r\n\x00"):
         raise ValueError("SFTP paths cannot contain newlines or NUL")
-    escaped = value.replace("\\", "\\\\").replace('"', '\\"')
-    for char in "*?[":
-        escaped = escaped.replace(char, "\\" + char)
-    return '"' + escaped + '"'
+    if windows:
+        value = PureWindowsPath(value).as_posix()
+    return '"' + value.replace("\\", "\\\\").replace('"', '\\"') + '"'
+
+
+def quote_local(path) -> str:
+    return quote(path, windows=os.name == "nt")
 
 
 def size_of(sftp, path):
@@ -35,27 +45,74 @@ def size_of(sftp, path):
         return 0
 
 
+def key_files(relaxed=False) -> list[Path]:
+    """The private keys OpenSSH offers: FramePort's own (<data>/ssh) and the usable key files from Settings;
+    ``relaxed`` also this PC's default keys (default_key_files)."""
+    keys = [ssh_dir() / name for name in ("id_ed25519", "id_rsa") if (ssh_dir() / name).exists()]
+    for path in [path for path, _ in extra_keys()] + (default_key_files() if relaxed else []):
+        if path not in keys:
+            keys.append(path)
+    return keys
+
+
+def default_key_files() -> list[Path]:
+    """This PC's own keys that Paramiko's "agent" login tries (look_for_keys: ~/.ssh/id_rsa, id_dsa, id_ecdsa,
+    id_ed25519; on Windows ~/ssh too), usable without a passphrase. OpenSSH needs them named: it skips its default
+    keys as soon as one -i is given, and Windows OpenSSH refuses a key file others can read (a private copy can't
+    be refused)."""
+    from .connection import KeyFileError, load_key_file
+
+    folders = [Path.home() / ".ssh"] + ([Path.home() / "ssh"] if os.name == "nt" else [])
+    found = []
+    for folder in folders:
+        for name in ("id_rsa", "id_dsa", "id_ecdsa", "id_ed25519"):
+            path = folder / name
+            if not path.is_file():
+                continue
+            try:
+                load_key_file(path)
+            except KeyFileError:
+                continue  # passphrase-protected or not a key: only the agent can use it
+            found.append(path)
+    return found
+
+
+def current_sid() -> str:
+    """This Windows account's SID. whoami prints in the console code page: read bytes, so a user name with
+    accents can't break decoding (only the ASCII SID is used)."""
+    out = subprocess.check_output(["whoami", "/user", "/fo", "csv", "/nh"], **hidden())
+    match = re.search(rb"S-1-[0-9]+(?:-[0-9]+)+", out)
+    if not match:
+        raise OSError("cannot find this Windows account's SID for the key copies' permissions")
+    return match.group().decode()
+
+
 @contextlib.contextmanager
-def credentials(frame, port_flag="-P"):
-    """Private temporary copies avoid modifying pairing keys, including their Windows ACLs."""
-    key_paths = [ssh_dir() / name for name in ("id_ed25519", "id_rsa") if (ssh_dir() / name).exists()]
-    if not key_paths:
+def credentials(frame, port_flag="-P", relaxed=False):
+    """OpenSSH arguments that log in like the Frame connection and trust only the host key it pinned.
+
+    Keys are offered as private temporary copies (that avoids modifying pairing keys, including their Windows
+    ACLs; Windows OpenSSH refuses key files others can read). Strict (default): FramePort's keys and the key
+    files from Settings only (IdentitiesOnly). ``relaxed``: also this PC's default ~/.ssh keys and SSH agent, the
+    way Paramiko's "agent" login does (GitHub #242: a Frame that only authorizes the user's own key). Verbose
+    (-v), so a refused login can say which keys were offered (failure()).
+    """
+    key_paths = key_files(relaxed)
+    if not key_paths and not relaxed:
         raise OSError("no FramePort key available for OpenSSH")
     key = frame.client.get_transport().get_remote_server_key()
     with tempfile.TemporaryDirectory(prefix="frameport-upload-") as directory:
         directory = Path(directory)
         sid = None
         if os.name == "nt":
-            row = next(csv.reader(io.StringIO(subprocess.check_output(
-                ["whoami", "/user", "/fo", "csv", "/nh"], text=True, **hidden()))))
-            sid = row[-1]
+            sid = current_sid()
             subprocess.run(["icacls", str(directory), "/inheritance:r", "/grant:r", f"*{sid}:(OI)(CI)F"],
                            check=True, stdout=subprocess.DEVNULL, **hidden())
         else:
             directory.chmod(0o700)
         copies = []
-        for path in key_paths:
-            copy = directory / path.name
+        for n, path in enumerate(key_paths):
+            copy = directory / f"key{n}"  # own names: a key from Settings may be called id_ed25519 too
             shutil.copyfile(path, copy)
             if sid:
                 subprocess.run(["icacls", str(copy), "/inheritance:r", "/remove:g", "*S-1-3-4",
@@ -66,13 +123,72 @@ def credentials(frame, port_flag="-P"):
         known = directory / "known_hosts"
         host = frame.target.host if frame.target.port == 22 else f"[{frame.target.host}]:{frame.target.port}"
         known.write_text(f"{host} {key.get_name()} {key.get_base64()}\n")
-        yield ["-F", os.devnull, *copies, "-o", "BatchMode=yes", "-o", "IdentitiesOnly=yes",
+        yield ["-F", os.devnull, "-v", *copies, "-o", "BatchMode=yes",
+               *([] if relaxed else ["-o", "IdentitiesOnly=yes"]),
                "-o", "StrictHostKeyChecking=yes", "-o", f'UserKnownHostsFile="{known.as_posix()}"',
                "-o", f"GlobalKnownHostsFile={os.devnull}", "-o", "ConnectTimeout=10",
                "-o", "ServerAliveInterval=10", "-o", "ServerAliveCountMax=3",
                port_flag, str(frame.target.port)]
 
 
+class OpenSSHAuthFailed(OSError):
+    """OpenSSH reached the Frame but the login was refused (the keys it offered aren't authorized there)."""
+
+
+AUTH_REFUSED = ("Permission denied (", "Too many authentication failures", "No more authentication methods")
+# debug lines (-v) worth keeping: which keys were found, offered, refused or unreadable
+AUTH_DEBUG = ("identity file", "Offering public key", "Server accepts key", "Will attempt key",
+              "Authentications that can continue", "Authenticated to", "Load key", "no such identity",
+              "Skipping", "agent", "Next authentication method")
+
+
+def failure(what: str, code, stderr: bytes) -> OSError:
+    """The error for a failed OpenSSH run: OpenSSH's own messages (all non-debug lines: warnings such as
+    "UNPROTECTED PRIVATE KEY FILE" included) plus the -v lines about keys; OpenSSHAuthFailed for a refused login."""
+    text = stderr.decode(errors="replace").replace("\r\n", "\n")
+    lines = [line for line in text.splitlines() if line.strip() and (
+        not line.startswith("debug") or any(k in line for k in AUTH_DEBUG))]
+    detail = "\n".join(lines)
+    if len(detail) > 4000:
+        detail = "…" + detail[-4000:]
+    refused = code == 255 and any(marker in text for marker in AUTH_REFUSED)
+    return (OpenSSHAuthFailed if refused else OSError)(f"{what} failed ({code}): {detail}")
+
+
+def login_modes(frame) -> list[bool]:
+    """How OpenSSH logs in, in order (False = FramePort's keys only, True = also this PC's keys and agent).
+
+    A Frame connection that logged in with this PC's own keys/agent (Paramiko's "agent" attempt) goes straight to
+    relaxed: FramePort's key isn't authorized there. Else strict first, relaxed once more after a refused login.
+    A mode that worked is kept for the rest of the connection. FramePort doesn't add its key to the Frame for
+    this: it only does that after a password login, where the user typed the Frame's password for it."""
+    known = getattr(frame, "openssh_relaxed", None)
+    if known is not None:
+        return [bool(known)]
+    if getattr(frame, "auth", "") == "agent":
+        return [True]
+    return [False, True]
+
+
+def with_login_modes(frame, reporter, run):
+    """run(relaxed) in each login mode until one isn't refused (see login_modes)."""
+    modes = login_modes(frame)
+    if modes == [True] and getattr(frame, "openssh_relaxed", None) is None:
+        reporter.log("the Frame connection logged in with this PC's own SSH keys or agent: OpenSSH uses them too")
+    for n, relaxed in enumerate(modes):
+        try:
+            result = run(relaxed)
+        except OpenSSHAuthFailed as exc:
+            if n == len(modes) - 1:
+                raise
+            reporter.log(f"OpenSSH login with FramePort's SSH keys was refused; trying this PC's own SSH keys and "
+                         f"agent too. {exc}")
+            continue
+        with contextlib.suppress(AttributeError):
+            frame.openssh_relaxed = relaxed
+        return result
+
+
 def hidden():
     return {"creationflags": subprocess.CREATE_NO_WINDOW} if os.name == "nt" else {}
 
@@ -99,6 +215,11 @@ def upload(frame, items, remote_root, reporter, total, sent, workers):
     Only successful batches are promoted, after every process has exited successfully. All control operations
     happen in the supervising thread, so Paramiko's SFTP client is never shared across threads.
     """
+    return with_login_modes(frame, reporter, lambda relaxed: _upload(
+        frame, items, remote_root, reporter, total, sent, workers, relaxed))
+
+
+def _upload(frame, items, remote_root, reporter, total, sent, workers, relaxed):
     executable = shutil.which("sftp")
     if not executable:
         raise OSError("system OpenSSH SFTP is unavailable")
@@ -111,7 +232,7 @@ def upload(frame, items, remote_root, reporter, total, sent, workers):
     sizes, offsets, progress = {}, {}, {}
     for path, rel, size in sorted(items, key=lambda item: item[2], reverse=True):
         remote = posixpath.join(remote_root, rel)
-        quote(path)
+        quote_local(path)
         quote(remote)
         offset = size_of(frame.sftp, remote + ".part")
         if offset > size:
@@ -127,7 +248,7 @@ def upload(frame, items, remote_root, reporter, total, sent, workers):
     speed = Speed(total - sent - sum(offsets.values()))
     reporter.log(f"uploading large files with OpenSSH SFTP ({len(groups)} workers)")
     setup_started = time.monotonic()
-    with credentials(frame) as args, contextlib.ExitStack() as stack:
+    with credentials(frame, relaxed=relaxed) as args, contextlib.ExitStack() as stack:
         monitor = stack.enter_context(frame.client.open_sftp())
         monitor.get_channel().settimeout(2)
         reporter.log(f"OpenSSH credentials and progress connection ready in {time.monotonic() - setup_started:.2f}s")
@@ -139,7 +260,7 @@ def upload(frame, items, remote_root, reporter, total, sent, workers):
                 for path, rel, _ in group:
                     remote = posixpath.join(remote_root, rel) + ".part"
                     command = "reput" if offsets[rel] else "put"
-                    batch.write(f"{command} {quote(path)} {quote(remote)}\n".encode())
+                    batch.write(f"{command} {quote_local(path)} {quote(remote)}\n".encode())
                 batch.seek(0)
                 errors = stack.enter_context(tempfile.TemporaryFile())
                 process = subprocess.Popen([executable, *args, "-b", "-",
@@ -152,8 +273,7 @@ def upload(frame, items, remote_root, reporter, total, sent, workers):
                 for process, errors in processes:
                     if process.poll() not in (None, 0):
                         errors.seek(0)
-                        detail = errors.read().decode(errors="replace")[-1500:]
-                        raise OSError(f"OpenSSH SFTP failed ({process.returncode}): {detail}")
+                        raise failure("OpenSSH SFTP", process.returncode, errors.read())
                 for rel, size in sizes.items():
                     reporter.check_cancel()
                     progress[rel] = max(progress[rel], min(size, size_of(
@@ -187,11 +307,16 @@ def upload(frame, items, remote_root, reporter, total, sent, workers):
 
 def put_tar(frame, files, remote_root, reporter, progress):
     """Stream a tar batch over paired OpenSSH; supervise writes so Cancel also stops a blocked pipe."""
+    return with_login_modes(frame, reporter,
+                            lambda relaxed: _put_tar(frame, files, remote_root, reporter, progress, relaxed))
+
+
+def _put_tar(frame, files, remote_root, reporter, progress, relaxed):
     executable = shutil.which("ssh")
     if not executable:
         raise OSError("system OpenSSH SSH is unavailable")
     reporter.check_cancel()
-    with credentials(frame, port_flag="-p") as args, tempfile.TemporaryFile() as errors:
+    with credentials(frame, port_flag="-p", relaxed=relaxed) as args, tempfile.TemporaryFile() as errors:
         command = f"mkdir -p {sh_quote(remote_root)} && tar -xf - -C {sh_quote(remote_root)}"
         process = subprocess.Popen([executable, *args, f"{frame.target.user}@{frame.target.host}", command],
                                    stdin=subprocess.PIPE, stdout=subprocess.DEVNULL, stderr=errors,
@@ -222,12 +347,14 @@ def put_tar(frame, files, remote_root, reporter, progress):
                 if not writer.is_alive() and process.poll() is None:
                     time.sleep(0.1)
             reporter.check_cancel()
+            if failures and process.poll() is None:  # a refused login shows as a broken pipe first
+                with contextlib.suppress(subprocess.TimeoutExpired):
+                    process.wait(timeout=2)
+            if process.poll() not in (None, 0):
+                errors.seek(0)
+                raise failure("OpenSSH tar", process.returncode, errors.read())
             if failures:
                 raise failures[0]
-            if process.poll() != 0:
-                errors.seek(0)
-                raise OSError(f"OpenSSH tar failed ({process.returncode}): "
-                              + errors.read().decode(errors="replace")[-1500:])
         finally:
             stop_process(process)
             writer.join()

src/frameport/locales/template.json

@@ -94,6 +94,7 @@
  "AC Nexus: no AppSW at 72 Hz": "",
  "AC Nexus: no AppSW at 90 Hz": "",
  "Activity": "",
+ "Add a key file…": "",
  "Add a Linux app folder…": "",
  "Add a Linux app…": "",
  "Add a PC game folder…": "",
@@ -557,6 +558,7 @@
  "Frame OpenXR compatibility layer": "",
  "FrameBridge OpenXR adapter": "",
  "FramePort": "",
+ "FramePort also logs in with {name} from the next connection.": "",
  "FramePort can't update itself in {value} (no permission) — opening the release page to download it": "",
  "FramePort changelog": "",
  "FramePort checks GitHub for a new version every few hours. Update now downloads and checks it, then restarts FramePort; your games and settings stay.": "",
@@ -568,6 +570,7 @@
  "FramePort isn't sure which program starts this game. Open the game and use … → Change program… to pick it.": "",
  "FramePort keeps its own copies; nothing is installed system-wide": "",
  "FramePort live view": "",
+ "FramePort logs in to the Frame with its own key. If your Frame accepts only one of your own keys, add that private key file here; fast uploads use it too. A key with a passphrase: add it to your SSH agent instead.": "",
  "FramePort looked at your last session of {n} game and has something to try.": [
   "",
   ""
@@ -1026,6 +1029,7 @@
  "On your Frame": "",
  "on: {names}": "",
  "One PC game folder": "",
+ "Only FramePort's own key, and your SSH agent's keys.": "",
  "Only if 360° pictures show wrongly.": "",
  "Only if 360° pictures show wrongly: 1 = upside down, 2 = mirrored, 4 = turned around (add values to combine).": "",
  "Only install software from sites you trust. FramePort downloads it from {host} and installs it on your Frame.": "",
@@ -1138,6 +1142,7 @@
  "Pretty smooth": "",
  "Prevents a start-up crash in some Unreal games.": "",
  "Previous": "",
+ "Private SSH key file (not the .pub file)": "",
  "Problems and feedback": "",
  "Processes": "",
  "Processor": "",
@@ -1412,6 +1417,7 @@
  "Sound on": "",
  "Source": "",
  "square, 256 × 256": "",
+ "SSH keys": "",
  "Stable (default)": "",
  "Stand in for cube layers": "",
  "Standard for every game": "",
@@ -1462,6 +1468,7 @@
  "Stereo (3D) 360° layers: 0 = as the game sends them, 2 = flat (the left image to both eyes).": "",
  "Stop": "",
  "Stop objects popping in and out": "",
+ "Stop using this key (the file stays)": "",
  "Stopped: {why}": "",
  "Stops a black picture in Minecraft launchers (for example QuestCraft).": "",
  "Stops a crash a few seconds after start in some Unreal games with anti-aliasing (for example Star Wars Pinball VR).": "",
@@ -1513,6 +1520,7 @@
  "Test Proton on the Frame": "",
  "Text and layout size": "",
  "That APK is a different app, not {title}.": "",
+ "That key can't be used: {error}": "",
  "That theme file can't be used: {error}": "",
  "That's me!": "",
  "The APK file is damaged or incomplete. Get the game again and rescan the folder.": "",

src/frameport/ui/help.py

@@ -62,6 +62,9 @@ HELP: dict[str, str] = _Translated({
     "hw_video_decode": "Games with the Hardware video decoding patch play their videos on the Frame's video hardware. "
                        "Turn it off if videos misbehave; games pick it up at their next start. For one game only, put "
                        "FRAMEPORT_NO_HW_VIDEO=1 before %command% in its Steam launch options.",
+    "ssh_keys": "FramePort logs in to the Frame with its own key. If your Frame accepts only one of your own keys, "
+                "add that private key file here; fast uploads use it too. A key with a passphrase: add it to your SSH "
+                "agent instead.",
     "launch_test": "Starts the game on the Frame while nobody wears the headset and reads the log: did it start and "
                    "draw frames. It can't check the picture.",
     "last_session": "After you play a game on the Frame, FramePort reads that session's log: crashes, frame rate and "

src/frameport/ui/views/settings.py

@@ -131,9 +131,55 @@ class SettingsView:
                           C.meta(tr("Large files upload together using OpenSSH when available. "
                                     "Default: 3. Lower this on a busy network.")),
                           C.ghost(tr("Remove converted copies now"), ft.Icons.CLEANING_SERVICES_OUTLINED, clean,
-                                  tooltip=tr("Your own game files aren't touched."))],
+                                  tooltip=tr("Your own game files aren't touched.")),
+                          ft.Container(height=T.S2), self.ssh_keys()],
                          spacing=T.S2, horizontal_alignment=ft.CrossAxisAlignment.START)
 
+    def ssh_keys(self) -> ft.Control:
+        """Settings → Installing: private key files FramePort logs in with besides its own (frame.connection
+        EXTRA_KEYS_SETTING; the Frame connection and OpenSSH uploads both use them, GitHub #242)."""
+        from ...frame import connection
+
+        app = self.app
+        rows = ft.Column(spacing=T.S1)
+
+        def fill():
+            items = []
+            for path, problem in connection.extra_key_status():
+                items.append(ft.Row([
+                    C.as_icon(ft.Icons.KEY_ROUNDED if not problem else ft.Icons.WARNING_AMBER_ROUNDED, T.px(18),
+                              T.TEXT_2 if not problem else T.WARN),
+                    ft.Column([C.body(path.name, T.TEXT), C.meta(problem or str(path), selectable=True)],
+                              spacing=0, expand=True),
+                    C.icon_btn(ft.Icons.DELETE_OUTLINE_ROUNDED, tr("Stop using this key (the file stays)"),
+                               on_click=lambda e, p=path: remove(p)),
+                ], spacing=T.S2, vertical_alignment=ft.CrossAxisAlignment.CENTER))
+            rows.controls = items or [C.meta(tr("Only FramePort's own key, and your SSH agent's keys."))]
+            C.update(rows)
+
+        def remove(path):
+            connection.remove_extra_key(path)
+            fill()
+
+        async def add(e):
+            for path in await C.pick_files(app.page, dialog_title=tr("Private SSH key file (not the .pub file)"),
+                                           multiple=True):
+                try:
+                    stored = connection.add_extra_key(path)
+                except connection.KeyFileError as exc:
+                    app.toast(tr("That key can't be used: {error}").format(error=exc), error=True)
+                    continue
+                app.toast(tr("FramePort also logs in with {name} from the next connection.").format(name=stored.name))
+            fill()
+
+        fill()
+        return ft.Column([
+            ft.Row([C.body(tr("SSH keys"), T.TEXT, weight=ft.FontWeight.W_500), C.help_icon("ssh_keys")],
+                   spacing=T.px(4), vertical_alignment=ft.CrossAxisAlignment.CENTER),
+            rows,
+            C.secondary(tr("Add a key file…"), ft.Icons.VPN_KEY_ROUNDED, add),
+        ], spacing=T.S2, horizontal_alignment=ft.CrossAxisAlignment.START)
+
     def updates_card(self) -> ft.Control:
         """Settings → Updates: FramePort's own updates (ui/updater.py, frameport/updates.py)."""
         import time

tests/test_native_upload.py

@@ -38,8 +38,36 @@ def test_quote_refuses_batch_injection(value):
         native.quote(value)
 
 
-def test_quote_protects_spaces_quotes_globs():
-    assert native.quote('a *?["b') == '"a \\*\\?\\[\\"b"'
+def test_quote_leaves_globs_to_sftp():
+    """Inside double quotes sftp escapes * ? [ itself: an extra backslash became part of the name (GitHub #324)."""
+    assert native.quote('a *?["b') == '"a *?[\\"b"'
+    assert native.quote("/x/te*s?t [ENG] \\b+(1).apk") == '"/x/te*s?t [ENG] \\\\b+(1).apk"'
+
+
+def test_quote_windows_local_path_uses_forward_slashes():
+    """Win32-OpenSSH turns a local path's backslashes into '/', escapes included ("C://Users", "/[ENG]")."""
+    path = r"C:\Users\user_name\AppData\Local\FramePort\output\All-In-One - Sports VR [ENG] v100+1.9.0 (x)\a.apk"
+    assert native.quote(path, windows=True) == (
+        '"C:/Users/user_name/AppData/Local/FramePort/output/All-In-One - Sports VR [ENG] v100+1.9.0 (x)/a.apk"')
+    assert native.quote(r"\\server\share\*?[a].apk", windows=True) == '"//server/share/*?[a].apk"'
+    assert native.quote('C:\\odd "name"\\a.apk', windows=True) == '"C:/odd \\"name\\"/a.apk"'
+
+
+@pytest.mark.parametrize("os_name,expected", [("nt", '"C:/games/[ENG] a/x.apk"'),
+                                              ("posix", '"C:\\\\games\\\\[ENG] a\\\\x.apk"')])
+def test_quote_local_follows_the_platform(monkeypatch, os_name, expected):
+    monkeypatch.setattr(native.os, "name", os_name)
+    assert native.quote_local(r"C:\games\[ENG] a\x.apk") == expected
+
+
+def test_batch_line_for_bracketed_folder(tmp_path, monkeypatch):
+    folder = tmp_path / "All-In-One - Sports VR [ENG] v100+1.9.0"
+    folder.mkdir()
+    frame, items, files, commands, processes = setup_batch(folder, monkeypatch)
+    monkeypatch.setattr(native.os, "name", "posix")
+    native.upload(frame, items, "/incoming", Reporter(), 20, 0, 1)
+    assert sorted(commands[0].splitlines()) == [f'put "{folder}/patch.obb" "/incoming/patch.obb.part"',
+                                                f'reput "{folder}/main.obb" "/incoming/main.obb.part"']
 
 
 def test_size_lookup_does_not_hide_connection_errors():
@@ -65,10 +93,11 @@ def setup_batch(tmp_path, monkeypatch, code=0):
     monitor.stat.side_effect = stat
     monitor.remove.side_effect = lambda path: files.pop(path)
     frame = SimpleNamespace(sftp=monitor, client=SimpleNamespace(open_sftp=lambda: monitor),
-                            target=FrameTarget("paired"), run=Mock(return_value=(0, "", "")))
+                            target=FrameTarget("paired"), run=Mock(return_value=(0, "", "")), modes_seen=[])
     monkeypatch.setattr(native.shutil, "which", lambda _: "sftp")
     @contextlib.contextmanager
-    def creds(frame):
+    def creds(frame, relaxed=False):
+        frame.modes_seen.append(relaxed)
         yield ["-o", "StrictHostKeyChecking=yes"]
     monkeypatch.setattr(native, "credentials", creds)
     commands, processes = [], []
@@ -210,7 +239,7 @@ def setup_tar(tmp_path, monkeypatch, code=0):
 
     path = tmp_path / "small.bin"
     path.write_bytes(b"payload")
-    frame = SimpleNamespace(target=FrameTarget("paired.example", port=2222))
+    frame = SimpleNamespace(target=FrameTarget("paired.example", port=2222), modes_seen=[])
     pipe = io.BytesIO()
     pipe.close = lambda: None
     process = Mock(stdin=pipe, returncode=code)
@@ -219,8 +248,9 @@ def setup_tar(tmp_path, monkeypatch, code=0):
     monkeypatch.setattr(native.subprocess, "Popen", popen)
     monkeypatch.setattr(native.shutil, "which", lambda _: "ssh")
     @contextlib.contextmanager
-    def creds(frame, port_flag):
+    def creds(frame, port_flag, relaxed=False):
         assert port_flag == "-p"
+        frame.modes_seen.append(relaxed)
         yield ["-o", "StrictHostKeyChecking=yes", port_flag, "2222"]
     monkeypatch.setattr(native, "credentials", creds)
     return frame, [(path, "nested/small.bin")], process, popen, pipe

tests/test_ssh_keys.py

@@ -0,0 +1,340 @@
+"""SSH keys beyond FramePort's own (GitHub #242): key files from Settings, the login a connection used, and OpenSSH
+uploads that fall back to this PC's own keys/agent when the Frame refuses FramePort's key."""
+import contextlib
+from pathlib import Path
+from types import SimpleNamespace
+from unittest.mock import Mock
+
+import paramiko
+import pytest
+from cryptography.hazmat.primitives import serialization
+from cryptography.hazmat.primitives.asymmetric import ed25519
+
+from frameport.core import library
+from frameport.core.events import Reporter
+from frameport.frame import connection as C
+from frameport.frame import native_upload as native
+
+REFUSED = (b"debug1: Reading configuration data nul\r\n"
+           b"debug1: identity file C:/Temp/frameport-upload-x/key0 type 3\r\n"
+           b"debug1: Connecting to 10.0.0.2 [10.0.0.2] port 22.\r\n"
+           b"@         WARNING: UNPROTECTED PRIVATE KEY FILE!          @\r\n"
+           b"debug1: Offering public key: C:/Temp/frameport-upload-x/key0 ED25519 SHA256:abc explicit\r\n"
+           b"debug1: Authentications that can continue: publickey,password\r\n"
+           b"debug1: kex: algorithm: curve25519-sha256\r\n"
+           b"steamos@10.0.0.2: Permission denied (publickey,password).\r\n")
+
+
+@pytest.fixture(autouse=True)
+def no_real_home_keys(tmp_path, monkeypatch):
+    """Never read the real ~/.ssh (relaxed mode looks there)."""
+    empty = tmp_path / "empty-home"
+    empty.mkdir()
+    monkeypatch.setattr(native.Path, "home", lambda: empty)
+
+
+def write_key(path: Path, password: bytes | None = None) -> Path:
+    enc = serialization.BestAvailableEncryption(password) if password else serialization.NoEncryption()
+    key = ed25519.Ed25519PrivateKey.generate()
+    path.write_bytes(key.private_bytes(serialization.Encoding.PEM, serialization.PrivateFormat.OpenSSH, enc))
+    path.with_name(path.name + ".pub").write_bytes(key.public_key().public_bytes(
+        serialization.Encoding.OpenSSH, serialization.PublicFormat.OpenSSH))
+    return path
+
+
+# ------------------------------------------------------------------------------------------- key files
+def test_key_file_validation(tmp_path):
+    good = write_key(tmp_path / "id_ed25519")
+    assert isinstance(C.load_key_file(good), paramiko.PKey)
+    with pytest.raises(C.KeyFileError, match="passphrase"):
+        C.load_key_file(write_key(tmp_path / "locked", b"secret"))
+    with pytest.raises(C.KeyFileError, match="public half"):
+        C.load_key_file(tmp_path / "id_ed25519.pub")
+    with pytest.raises(C.KeyFileError, match="not found"):
+        C.load_key_file(tmp_path / "missing")
+    (tmp_path / "notes.txt").write_text("hello")
+    with pytest.raises(C.KeyFileError, match="isn't a private SSH key"):
+        C.load_key_file(tmp_path / "notes.txt")
+
+
+def test_extra_keys_come_from_settings_and_skip_unusable_ones(tmp_path):
+    good = write_key(tmp_path / "mine")
+    locked = write_key(tmp_path / "locked", b"secret")
+    library.set_setting(C.EXTRA_KEYS_SETTING, [str(good), str(good), str(locked), str(tmp_path / "gone"), "", 3])
+    assert C.extra_key_paths() == [good, locked, tmp_path / "gone"]
+    assert [path for path, _ in C.extra_keys()] == [good]
+    library.set_setting(C.EXTRA_KEYS_SETTING, str(good))  # a single path, e.g. edited by hand
+    assert C.extra_key_paths() == [good]
+
+
+class _Client:
+    """paramiko.SSHClient stand-in: accepts the key `accepted` (or the agent when accepted == "agent")."""
+    accepted = None
+    tried: list = []
+
+    def load_host_keys(self, path):
+        pass
+
+    def set_missing_host_key_policy(self, policy):
+        pass
+
+    def close(self):
+        pass
+
+    def save_host_keys(self, path):
+        pass
+
+    def get_transport(self):
+        return Mock()
+
+    def connect(self, pkey=None, password=None, allow_agent=False, look_for_keys=False, **kw):
+        kind = "password" if password else "agent" if allow_agent else pkey
+        _Client.tried.append(kind)
+        if kind != _Client.accepted:
+            raise paramiko.AuthenticationException("Authentication failed.")
+
+
+@pytest.mark.parametrize("accepted,auth", [("app", "app_key"), ("user", "user_key"), ("agent", "agent")])
+def test_connection_records_the_login_that_worked(monkeypatch, accepted, auth):
+    monkeypatch.setattr(C.paramiko, "SSHClient", _Client)
+    monkeypatch.setattr(C, "app_keys", lambda: ["app"])
+    monkeypatch.setattr(C, "extra_keys", lambda: [(Path("/k"), "user")])
+    monkeypatch.setattr(C.Frame, "run", lambda self, cmd: (0, "/home/steamos", ""))
+    _Client.accepted, _Client.tried = accepted, []
+    frame = C.Frame(C.FrameTarget("10.0.0.2")).connect()
+    assert frame.auth == auth
+    assert _Client.tried == ["app", "user", "agent"][:["app", "user", "agent"].index(accepted) + 1]
+
+
+# ------------------------------------------------------------------------------------------- OpenSSH arguments
+def frame_with_key():
+    key = SimpleNamespace(get_name=lambda: "ssh-ed25519", get_base64=lambda: "PAIRED_KEY")
+    client = SimpleNamespace(get_transport=lambda: SimpleNamespace(get_remote_server_key=lambda: key))
+    return C.Frame(C.FrameTarget("paired.example"), client=client)
+
+
+def test_credentials_offer_own_and_settings_keys_strict_or_relaxed(tmp_path, monkeypatch):
+    own = tmp_path / "ssh"
+    own.mkdir()
+    write_key(own / "id_ed25519")
+    mine = write_key(tmp_path / "id_ed25519")  # same file name as FramePort's: copies get their own names
+    monkeypatch.setattr(native, "ssh_dir", lambda: own)
+    library.set_setting(C.EXTRA_KEYS_SETTING, [str(mine)])
+    with native.credentials(frame_with_key()) as args:
+        copies = [Path(args[i + 1]) for i, a in enumerate(args) if a == "-i"]
+        assert [c.read_bytes() for c in copies] == [(own / "id_ed25519").read_bytes(), mine.read_bytes()]
+        assert "IdentitiesOnly=yes" in args and "BatchMode=yes" in args and "-v" in args
+        assert all(oct(c.stat().st_mode & 0o777) == "0o600" for c in copies)
+    assert not any(c.exists() for c in copies)
+    with native.credentials(frame_with_key(), relaxed=True) as args:
+        assert "IdentitiesOnly=yes" not in args and args.count("-i") == 2
+        assert "StrictHostKeyChecking=yes" in args  # host key still pinned
+
+
+def test_relaxed_credentials_work_without_any_key_file(tmp_path, monkeypatch):
+    monkeypatch.setattr(native, "ssh_dir", lambda: tmp_path)
+    with pytest.raises(OSError, match="no FramePort key"):
+        with native.credentials(frame_with_key()):
+            pass
+    with native.credentials(frame_with_key(), relaxed=True) as args:
+        assert "-i" not in args
+
+
+def test_windows_sid_survives_a_non_ascii_user_name(monkeypatch):
+    out = '"desktop-1\\josé müller","S-1-5-21-1004336348-1177238915-682003330-1001"\r\n'.encode("cp850")
+    monkeypatch.setattr(native.subprocess, "check_output", lambda *a, **k: out)
+    assert native.current_sid() == "S-1-5-21-1004336348-1177238915-682003330-1001"
+    monkeypatch.setattr(native.subprocess, "check_output", lambda *a, **k: b"nothing")
+    with pytest.raises(OSError):
+        native.current_sid()
+
+
+# ------------------------------------------------------------------------------------------- failures and modes
+def test_failure_keeps_openssh_messages_and_key_lines():
+    exc = native.failure("OpenSSH SFTP", 255, REFUSED)
+    assert isinstance(exc, native.OpenSSHAuthFailed)
+    text = str(exc)
+    assert "UNPROTECTED PRIVATE KEY FILE" in text and "Offering public key" in text
+    assert "identity file" in text and "Permission denied (publickey,password)" in text
+    assert "kex: algorithm" not in text and "Reading configuration" not in text
+    other = native.failure("OpenSSH SFTP", 1, b"stat x: No such file or directory\n")
+    assert type(other) is OSError and "No such file" in str(other)
+    assert type(native.failure("OpenSSH tar", 255, b"ssh: connect to host x port 22: Connection timed out")) is OSError
+
+
+@pytest.mark.parametrize("auth,known,modes", [("app_key", None, [False, True]), ("user_key", None, [False, True]),
+                                              ("password", None, [False, True]), ("agent", None, [True]),
+                                              ("app_key", True, [True]), ("agent", False, [False])])
+def test_login_modes(auth, known, modes):
+    assert native.login_modes(SimpleNamespace(auth=auth, openssh_relaxed=known)) == modes
+    assert native.login_modes(SimpleNamespace()) == [False, True]  # stand-ins without the fields
+
+
+def sftp_setup(tmp_path, monkeypatch, refuse_strict=True, refuse_relaxed=False, auth="app_key"):
+    """Two .part-less files; strict/relaxed logins refused as asked; returns the frame and the Popen calls."""
+    paths = [tmp_path / "main.obb", tmp_path / "patch.obb"]
+    for path in paths:
+        path.write_bytes(b"0123456789")
+    items = [(path, path.name, 10) for path in paths]
+    files = {}
+    monitor = Mock()
+    monitor.__enter__ = Mock(return_value=monitor)
+    monitor.__exit__ = Mock(return_value=False)
+
+    def stat(path):
+        if path not in files:
+            raise FileNotFoundError(path)
+        return SimpleNamespace(st_size=files[path])
+    monitor.stat.side_effect = stat
+    frame = SimpleNamespace(sftp=monitor, client=SimpleNamespace(open_sftp=lambda: monitor), auth=auth,
+                            openssh_relaxed=None, target=C.FrameTarget("paired"), run=Mock(return_value=(0, "", "")))
+    monkeypatch.setattr(native.shutil, "which", lambda _: "sftp")
+    mode = {}
+
+    @contextlib.contextmanager
+    def creds(frame, port_flag="-P", relaxed=False):
+        mode["relaxed"] = relaxed
+        yield ["relaxed" if relaxed else "strict"]
+    monkeypatch.setattr(native, "credentials", creds)
+    calls = []
+
+    def popen(args, **kwargs):
+        relaxed = mode["relaxed"]
+        calls.append(relaxed)
+        refused = refuse_relaxed if relaxed else refuse_strict
+        if refused:
+            kwargs["stderr"].write(REFUSED)
+            code = 255
+        else:
+            for _, rel, size in items:
+                files["/incoming/" + rel + ".part"] = size
+            code = 0
+        process = Mock(returncode=code)
+        process.poll.return_value = code
+        return process
+    monkeypatch.setattr(native.subprocess, "Popen", popen)
+    return frame, items, calls
+
+
+def test_refused_strict_login_retries_with_this_pcs_keys(tmp_path, monkeypatch):
+    frame, items, calls = sftp_setup(tmp_path, monkeypatch)
+    logs = []
+    reporter = Reporter()
+    reporter.log = lambda message, **k: logs.append(message)
+    assert native.upload(frame, items, "/incoming", reporter, 20, 0, 2) == 20
+    assert calls == [False, False, True, True]  # both strict workers are refused, then both run relaxed
+    assert frame.openssh_relaxed is True
+    assert any("trying this PC's own SSH keys" in m and "UNPROTECTED" in m for m in logs)
+    assert native.login_modes(frame) == [True]  # the next upload starts in the mode that worked
+
+
+def test_agent_login_goes_straight_to_relaxed(tmp_path, monkeypatch):
+    frame, items, calls = sftp_setup(tmp_path, monkeypatch, auth="agent")
+    assert native.upload(frame, items, "/incoming", Reporter(), 20, 0, 1) == 20
+    assert calls == [True]
+
+
+def test_refused_in_both_modes_raises_the_auth_failure(tmp_path, monkeypatch):
+    frame, items, calls = sftp_setup(tmp_path, monkeypatch, refuse_relaxed=True)
+    with pytest.raises(native.OpenSSHAuthFailed, match="Permission denied"):
+        native.upload(frame, items, "/incoming", Reporter(), 20, 0, 1)
+    assert calls == [False, True] and frame.openssh_relaxed is None
+    assert not frame.run.called  # nothing promoted
+
+
+def test_tar_retries_a_refused_login(tmp_path, monkeypatch):
+    path = tmp_path / "small.bin"
+    path.write_bytes(b"abc")
+    frame = SimpleNamespace(target=C.FrameTarget("paired"), auth="app_key", openssh_relaxed=None)
+    monkeypatch.setattr(native.shutil, "which", lambda _: "ssh")
+    mode = {}
+
+    @contextlib.contextmanager
+    def creds(frame, port_flag="-P", relaxed=False):
+        mode["relaxed"] = relaxed
+        yield []
+    monkeypatch.setattr(native, "credentials", creds)
+
+    class Pipe:
+        def write(self, data):
+            if not mode["relaxed"]:
+                raise BrokenPipeError(32, "Broken pipe")  # ssh already exited
+            return len(data)
+
+        def flush(self):
+            pass
+
+        def close(self):
+            pass
+    calls = []
+
+    def popen(args, **kwargs):
+        calls.append(mode["relaxed"])
+        code = 0 if mode["relaxed"] else 255
+        if code:
+            kwargs["stderr"].write(REFUSED)
+        process = Mock(stdin=Pipe(), returncode=code)
+        process.poll.return_value = code
+        return process
+    monkeypatch.setattr(native.subprocess, "Popen", popen)
+    native.put_tar(frame, [(path, "small.bin")], "/incoming", Reporter(), Mock())
+    assert calls == [False, True] and frame.openssh_relaxed is True
+
+
+def test_azure_ad_sid(monkeypatch):
+    out = b'"azuread\\jmueller","S-1-12-1-1234567890-1234567890-1234567890-1234567890"\r\n'
+    monkeypatch.setattr(native.subprocess, "check_output", lambda *a, **k: out)
+    assert native.current_sid() == "S-1-12-1-1234567890-1234567890-1234567890-1234567890"
+
+
+def test_relaxed_mode_names_this_pcs_default_keys(tmp_path, monkeypatch):
+    """OpenSSH skips its default keys once any -i is given, so relaxed mode names the ones Paramiko tries."""
+    home = tmp_path / "home"
+    (home / ".ssh").mkdir(parents=True)
+    rsa = home / ".ssh" / "id_rsa"
+    from cryptography.hazmat.primitives.asymmetric import rsa as rsa_keys
+
+    rsa.write_bytes(rsa_keys.generate_private_key(65537, 2048).private_bytes(
+        serialization.Encoding.PEM, serialization.PrivateFormat.OpenSSH, serialization.NoEncryption()))
+    write_key(home / ".ssh" / "id_ecdsa", b"secret")  # passphrase: only usable through the agent
+    (home / ".ssh" / "id_ed25519").write_text("garbage")
+    monkeypatch.setattr(native.Path, "home", lambda: home)
+    own = tmp_path / "own"
+    own.mkdir()
+    write_key(own / "id_ed25519")
+    monkeypatch.setattr(native, "ssh_dir", lambda: own)
+    assert native.default_key_files() == [rsa]
+    assert native.key_files() == [own / "id_ed25519"]
+    assert native.key_files(relaxed=True) == [own / "id_ed25519", rsa]
+    library.set_setting(C.EXTRA_KEYS_SETTING, [str(rsa)])  # a default key also named in Settings: offered once
+    assert native.key_files(relaxed=True) == [own / "id_ed25519", rsa]
+
+
+def test_add_remove_and_status_of_settings_keys(tmp_path):
+    good = write_key(tmp_path / "frame key")
+    with pytest.raises(C.KeyFileError, match="public half"):
+        C.add_extra_key(tmp_path / "frame key.pub")
+    with pytest.raises(C.KeyFileError, match="passphrase"):
+        C.add_extra_key(write_key(tmp_path / "locked", b"pw"))
+    assert C.add_extra_key(good) == good.resolve()
+    C.add_extra_key(good)  # once only
+    assert C.extra_key_paths() == [good.resolve()]
+    good.unlink()
+    [(path, problem)] = C.extra_key_status()
+    assert path == good.resolve() and "not found" in problem
+    assert C.remove_extra_key(good) is True and C.remove_extra_key(good) is False
+    assert C.extra_key_paths() == []
+
+
+def test_cli_ssh_keys(tmp_path):
+    from typer.testing import CliRunner
+
+    from frameport.cli import app
+
+    good = write_key(tmp_path / "mine")
+    run = CliRunner().invoke(app, ["frame", "ssh-keys", "--add", str(good)])
+    assert run.exit_code == 0 and f"added {good.resolve()}" in run.output
+    run = CliRunner().invoke(app, ["frame", "ssh-keys", "--add", str(tmp_path / "nope")])
+    assert run.exit_code == 1 and str(good.resolve()) in run.output
+    run = CliRunner().invoke(app, ["frame", "ssh-keys", "--remove", str(good.resolve())])
+    assert run.exit_code == 0 and "no extra keys" in run.output