Merge pull request #82 from saphid/fix/release-draft-id

release.yml: read the new draft's id from the REST POST, not the lagging release list

.github/workflows/release.yml

@@ -16,8 +16,12 @@ permissions:
 jobs:
   # One job makes the draft, before the builds: three matrix jobs each running
   # "view || create" could race and make duplicate drafts. The draft is tied to
-  # the pushed tag (--verify-tag, then tag_name set explicitly), so
-  # scripts/publish-release.sh and `gh release upload` find it by tag.
+  # the pushed tag (the tag must already exist on GitHub, then tag_name is set
+  # explicitly), so scripts/publish-release.sh and `gh release upload` find it
+  # by tag. It is created with the REST API so the id comes straight back: the
+  # release list can lag a fresh draft (v0.4.2's first run found nothing and
+  # PATCHed releases/ with an empty id). tests/test_release_workflow.py runs
+  # this step against tests/fakegh.
   draft:
     if: startsWith(github.ref, 'refs/tags/')
     runs-on: ubuntu-latest
@@ -28,11 +32,16 @@ jobs:
           GH_REPO: ${{ github.repository }}
         run: |
           tag="${GITHUB_REF_NAME}"
+          # A rerun finds the draft an earlier attempt made.
           id=$(gh api --paginate "repos/$GH_REPO/releases?per_page=100" --jq ".[] | select(.tag_name == \"$tag\") | .id" | head -n 1)
           if [ -z "$id" ]; then
-            gh release create "$tag" --draft --verify-tag --title "Frame Control ${tag#v}" --notes ""
-            id=$(gh api --paginate "repos/$GH_REPO/releases?per_page=100" --jq ".[] | select(.draft and .name == \"Frame Control ${tag#v}\") | .id" | head -n 1)
+            # Given a missing tag, GitHub would create it on the default branch.
+            gh api "repos/$GH_REPO/git/ref/tags/$tag" >/dev/null \
+              || { echo "tag $tag isn't on GitHub" >&2; exit 1; }
+            id=$(gh api -X POST "repos/$GH_REPO/releases" -f tag_name="$tag" -f name="Frame Control ${tag#v}" \
+              -F draft=true -f body="" --jq .id)
           fi
+          [ -n "$id" ] || { echo "no release id for $tag; not PATCHing releases/" >&2; exit 1; }
           gh api -X PATCH "repos/$GH_REPO/releases/$id" -f tag_name="$tag" --jq '"release " + (.id|tostring) + " tag_name " + .tag_name'
 
   build:

app/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "frame-control",
-  "version": "0.4.1",
+  "version": "0.4.2",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "frame-control",
-      "version": "0.4.1",
+      "version": "0.4.2",
       "license": "MIT",
       "devDependencies": {
         "electron": "^44.4.5",

app/package.json

@@ -1,7 +1,7 @@
 {
   "name": "frame-control",
   "productName": "Frame Control",
-  "version": "0.4.1",
+  "version": "0.4.2",
   "description": "Desktop app for managing a Valve Steam Frame over SSH",
   "private": true,
   "main": "main.js",

docs/privacy.md

@@ -131,10 +131,56 @@ With **Include diagnostics** ticked (the default), the report adds:
 - the OS, its release and CPU, and the Python version
 - the Frame's SteamOS build, if it has connected since the app started
 - which analytics levels are on
+- a short connection summary, so "the app can't find the headset" can be
+  diagnosed. It is made of fixed words and counts only; no text from an
+  error message or from ssh, and no name you chose, goes in it:
+  - the connector's state (idle, connecting, connected or failed), the stage
+    it failed at (network, find, ssh, identity or login), the attempt number
+    and why it started (such as "Starting up" or "Trying again")
+  - how many headsets are saved; whether the active one's ssh alias is the
+    default `frame` or a custom one (a custom alias itself is never named);
+    whether it's saved or a bare ssh alias; and its number of addresses
+  - for the current error and the last failure: the stage and an error
+    category (the same fixed names as error details, such as
+    `frame_unreachable`, `frame_not_set_up`, `frame_auth` or `other`), and
+    how long ago the last failure was. The category is decided when the
+    failure happens
+  - for each address tried, only its kind (`.local`, `ipv4`, `ipv6`,
+    `ipv6 link-local`, `tailscale`, `hostname`, `alias` for one read from
+    `~/.ssh/config`, and what a name resolved to, such as
+    `.local->ipv6 link-local`) and how the try went (answered, unresolved,
+    timeout, refused, unreachable, sshfailed). Never the address itself
+  - when connected, the kind of address used and its round trip in ms
+  - whether this computer has a network gateway, and whether Tailscale is on,
+    off or not installed
+  - which kind of `ssh` the app runs (Windows OpenSSH in System32, OpenSSH in
+    Program Files, Git for Windows, MSYS2/Cygwin, Homebrew or /usr/local,
+    Nix, the system one, or "other"), never its path; its version, rebuilt
+    from the numbers in the banner `ssh -V` prints (such as
+    `OpenSSH for Windows 9.5p1, LibreSSL 3.8.2`; anything that isn't a
+    plain OpenSSH banner is reported as `unknown`); and the kinds of any
+    other `ssh` on the PATH.
+    This is looked up once in the background after the app starts, so a
+    report sent straight away may say "still being checked"
+  - whether `~/.ssh/config` exists, whether it has Set Up Connection's
+    managed block for the active alias, how many managed blocks it has, and
+    whether a hand-written `Host` line also names the alias (yes or no; the
+    alias isn't named)
 
 **Also include recent activity and the server log** is off by default,
 because those lines can name files and apps. When ticked, it adds the newest
-Activity lines and server log lines, without the request lines.
+Activity lines and server log lines, without the request lines. The server
+log has a line for each failed connection attempt: its stage, the message
+shown on the connection pill, ssh's last line about it, and the address kinds
+above. That free text is scrubbed when the line is written: the addresses, ssh alias
+and display name of the headset being tried (whole, whatever their case), and
+then any name ssh gives after "hostname", "host" or "to", become `<host>`; a Windows home folder's
+whole name (spaces and apostrophes included) becomes `<user>`, and ssh's
+whole `user@host:` field (spaces, `DOMAIN\user` and full domain names
+included) becomes `<user>@<host>:`; then the scrubbing below. A host name ssh mentions
+in some other wording can still get through, so check the log lines in **Show
+exactly what's included** before sending. A failure that repeats on every
+retry is written at most once every 5 minutes.
 
 Everything is scrubbed like error details and limited to what fits in the
 report. Environment details are kept first, then the newest lines. **Show

tests/fakegh/gh

@@ -1,11 +1,17 @@
 #!/usr/bin/env python3
-"""A stand-in for the GitHub CLI's `gh api`, for tests/test_publish_release.py. Serves
-the releases in $FAKEGH_RELEASES (a JSON list, drafts included) and the tags in
-$FAKEGH_TAGS (space-separated); an upload's body is written to $FAKEGH_UPLOAD.
-Every call is appended to $FAKEGH_LOG as a JSON line. Anything else fails, so the
-script under test can't fall back to `gh release ...` (GraphQL) unnoticed."""
+"""A stand-in for the GitHub CLI's `gh api`, for tests/test_publish_release.py and
+tests/test_release_workflow.py. Serves the releases in $FAKEGH_RELEASES (a JSON list,
+drafts included) and the tags in $FAKEGH_TAGS (space-separated); an upload's body is
+written to $FAKEGH_UPLOAD. Every call is appended to $FAKEGH_LOG as a JSON line.
+Anything else fails, so the script under test can't fall back to `gh release ...`
+(GraphQL) unnoticed. POST .../releases (release.yml's draft step) answers as release
+$FAKEGH_NEW_ID (default 9001) without adding it to the listing, like GitHub's list
+lagging a fresh draft. With jq installed, --jq filters a response the way gh does
+(raw strings, compact JSON)."""
 import json
 import os
+import shutil
+import subprocess
 import sys
 
 args = sys.argv[1:]
@@ -14,7 +20,7 @@ with open(os.environ["FAKEGH_LOG"], "a") as f:
 if not args or args[0] != "api":
     sys.exit("fakegh: only `gh api` is supported: %r" % args)
 
-method, endpoint, fields, inp, i = "GET", None, {}, None, 1
+method, endpoint, fields, inp, jq, i = "GET", None, {}, None, None, 1
 while i < len(args):
     a = args[i]
     if a == "-X":
@@ -23,7 +29,9 @@ while i < len(args):
         k, _, v = args[i + 1].partition("="); fields[k] = v; i += 2
     elif a == "--input":
         inp = args[i + 1]; i += 2
-    elif a in ("-H", "--jq"):
+    elif a == "--jq":
+        jq = args[i + 1]; i += 2
+    elif a == "-H":
         i += 2
     elif a.startswith("-"):
         i += 1
@@ -34,14 +42,34 @@ while i < len(args):
 
 releases = json.load(open(os.environ["FAKEGH_RELEASES"]))
 repo = "repos/saphid/frame-control/"
+
+
+def answer(response, fallback):
+    """Print response through --jq when jq is here, else the fixed fallback text."""
+    if jq and shutil.which("jq"):
+        out = subprocess.run(["jq", "-r", "-c", jq], input=json.dumps(response),
+                             stdout=subprocess.PIPE, stderr=subprocess.PIPE, universal_newlines=True)
+        sys.stdout.write(out.stdout)
+        if out.returncode:
+            sys.exit("fakegh: jq failed: " + out.stderr)
+    else:
+        print(fallback)
+
+
 if method == "GET" and endpoint.startswith(repo + "git/ref/tags/"):
     tag = endpoint.rsplit("/", 1)[1]
     if tag not in os.environ.get("FAKEGH_TAGS", "").split():
         sys.exit("gh: Not Found (HTTP 404)")
     print(json.dumps({"ref": "refs/tags/" + tag}))
 elif method == "GET" and endpoint.startswith(repo + "releases?"):
-    for r in releases:  # what --jq '.[]' prints
-        print(json.dumps(r))
+    # The fallback is what --jq '.[]' prints.
+    answer(releases, "\n".join(json.dumps(r) for r in releases))
+elif method == "POST" and endpoint == repo + "releases":
+    new = {"id": int(os.environ.get("FAKEGH_NEW_ID", "9001")), "tag_name": fields.get("tag_name"),
+           "name": fields.get("name"), "draft": fields.get("draft") == "true",
+           "body": fields.get("body"), "assets": [],
+           "html_url": "https://github.com/saphid/frame-control/releases/tag/untagged-be29e900f7855d794136"}
+    answer(new, json.dumps(new))
 elif method == "DELETE" and endpoint.startswith(repo + "releases/assets/"):
     pass
 elif method == "POST" and endpoint.startswith("https://uploads.github.com/" + repo + "releases/"):
@@ -49,7 +77,11 @@ elif method == "POST" and endpoint.startswith("https://uploads.github.com/" + re
         dst.write(src.read())
     print("{}")
 elif method == "PATCH" and endpoint.startswith(repo + "releases/"):
-    print("published %s at https://github.com/saphid/frame-control/releases/tag/%s"
-          % (fields.get("tag_name"), fields.get("tag_name")))
+    rid = endpoint[len(repo + "releases/"):]
+    if not rid.isdigit():  # what GitHub said to v0.4.2's PATCH of releases/ (an empty id)
+        sys.exit("gh: Not Found (HTTP 404)")
+    page = "https://github.com/saphid/frame-control/releases/tag/%s" % fields.get("tag_name")
+    answer({"id": int(rid), "tag_name": fields.get("tag_name"), "html_url": page},
+           "published %s at %s" % (fields.get("tag_name"), page))
 else:
     sys.exit("fakegh: unhandled %s %s" % (method, endpoint))

tests/test_link.py

@@ -6,6 +6,7 @@ Run: python3 -m unittest discover -s tests
 """
 import sandbox  # noqa: F401  (first: keeps tests off real data and services)
 import http.client
+import io
 import json
 import os
 import shutil
@@ -599,6 +600,260 @@ class Connecting(unittest.TestCase):
         (self.dir / "ssh" / "config").write_text("Host frame lab-*\n  HostName 10.0.0.7\n")  # someone's own `frame`
         self.assertEqual(fl.next_alias(self.link), "frame-2")
 
+    # ---- what a failure leaves for a problem report ----
+    def stderr(self):
+        return quiet_log(self)
+
+    def report(self):
+        import frame_report as fr
+        done = threading.Thread(target=lambda: None)
+        done.start()
+        done.join()
+        with mock.patch.object(fr, "link", self.link), \
+                mock.patch.dict(fr._ssh, {"thread": done, "line": "SSH: system OpenSSH, OpenSSH 9.9p1, LibreSSL 3.3.6"}):
+            return fr.diagnostics()
+
+    def test_each_failure_goes_to_the_server_log_scrubbed(self):
+        err = self.stderr()
+        self.device("steamdeck-jane.invalid", "localhost")
+        self.hosts({"localhost": "denied"})
+        self.link.connect(["start"])
+        line = err.getvalue()
+        self.assertIn("frame_link: login failed: The Frame didn't accept this computer's SSH key.", line)
+        self.assertIn("addresses: hostname unresolved; hostname->ipv4", line)
+        for leaked in ("steamdeck-jane", "127.0.0.1", "localhost"):
+            self.assertNotIn(leaked, line)
+        self.assertEqual(self.link.last_failure["stage"], "login")
+
+    def test_reports_carry_a_connection_summary_in_fixed_words(self):
+        self.stderr()
+        self.device("steamdeck-jane.invalid", "frame-t.invalid")
+        (self.dir / "ssh" / "config").write_text(
+            f"{fd.begin_mark('frame-t')}\nHost frame-t\n  HostName 192.168.1.50\n  User steamos\n{fd.end_mark('frame-t')}\n"
+            "Host frame-t\n  HostName 10.0.0.7\n")
+        self.link.connect(["start"])
+        text = self.report()
+        self.assertIn("Connection: failed at find, attempt 1 (Starting up)", text)
+        self.assertIn("Headsets: 1 saved; active alias custom (saved, 2 address(es))", text)
+        self.assertIn("Error: find, frame_not_set_up", text)
+        self.assertRegex(text, r"Last failure: find, frame_not_set_up, 0 min \d+ s ago")
+        self.assertIn("Addresses tried: hostname unresolved; hostname unresolved", text)
+        self.assertIn("Network: gateway yes, Tailscale not installed", text)
+        self.assertIn("SSH: system OpenSSH, OpenSSH 9.9p1", text)
+        self.assertIn("~/.ssh/config: managed block for the active alias yes (1 managed in all); "
+                      "hand-written Host for it yes", text)
+        # No free text from the error or ssh at all, and not the custom alias.
+        for leaked in ("steamdeck-jane", "Could not resolve", "Can't find", "192.168", "10.0.0.7", "steamos",
+                       "frame-t", str(self.dir)):
+            self.assertNotIn(leaked, text)
+
+    def test_a_failure_on_the_last_headset_leaves_nothing_of_it_after_switching(self):
+        self.stderr()
+        a = self.device("steamdeck-jane.invalid")
+        self.link.connect(["start"])
+        b = self.reg.add_device("frame-2", port=self.port, hosts=[])
+        self.reg.add_address(b["id"], "localhost", kind="lan")
+        self.hosts({"localhost": "ok"})
+        self.reg.set_active(b["id"])
+        self.link.connect(["switch"])
+        self.assertEqual(self.link.snapshot()["phase"], "connected")
+        text = self.report()
+        self.assertIn("Connection: connected via hostname->ipv4", text)
+        self.assertRegex(text, r"Last failure: find, frame_not_set_up, ")
+        self.assertNotIn("steamdeck-jane", text)
+        self.assertNotEqual(a["id"], b["id"])
+
+    def test_the_headsets_alias_and_name_stay_out_of_the_log(self):
+        import frame_report as fr
+        err = self.stderr()
+        d = self.reg.add_device("jane-office.example.com", name="Jane Doe's work headset", hosts=[])
+        self.reg.set_active(d["id"])
+        self.link.connect(["start"])
+        self.assertIn("find failed: The active headset has no addresses.", err.getvalue())
+        # A message that names it anyway (any case) goes too, in the log and so in a report's log.
+        self.link.note_failure("ssh", "JANE-OFFICE.EXAMPLE.COM: jane doe's work headset stopped answering")
+        log = self.dir / "server.log"
+        log.write_text(err.getvalue())
+        with mock.patch.dict(os.environ, {"FRAME_CONTROL_LOG": str(log)}):
+            with mock.patch.object(fr, "link", self.link), mock.patch.dict(fr._ssh, {"thread": None, "line": "SSH: x"}):
+                text = fr.diagnostics(include_logs=True)
+        self.assertIn("frame_link: ssh failed", text)
+        for leaked in ("jane", "Jane", "JANE"):
+            self.assertNotIn(leaked, err.getvalue())
+            self.assertNotIn(leaked, text)
+
+
+def quiet_log(test):
+    """Catch frame_link's log lines, starting with nothing remembered."""
+    fl._logged.clear()
+    err = io.StringIO()
+    p = mock.patch.object(sys, "stderr", err)
+    p.start()
+    test.addCleanup(p.stop)
+    return err
+
+
+class FailureLog(unittest.TestCase):
+    def test_the_same_failure_isnt_logged_every_retry(self):
+        err = quiet_log(self)
+        for _ in range(3):
+            fl.log_failure("find", "The Frame isn't answering.", "", [{"host": "frame.local", "state": "timeout"}])
+        self.assertEqual(err.getvalue().count("frame_link:"), 1)
+        for v in fl._logged.values():
+            v["at"] -= fl.LOG_REPEAT_EVERY + 1
+        fl.log_failure("find", "The Frame isn't answering.", "", [{"host": "frame.local", "state": "timeout"}])
+        self.assertIn("(and 2 more times)", err.getvalue())
+        self.assertNotIn("frame.local", err.getvalue())
+
+    def test_interleaved_failures_are_throttled_too(self):
+        err = quiet_log(self)
+        for _ in range(4):
+            fl.log_failure("find", "The Frame isn't answering.")
+            fl.log_failure("login", "The Frame didn't accept this computer's SSH key.")
+        self.assertEqual(err.getvalue().count("frame_link:"), 2)
+        for i in range(fl.LOG_REMEMBER + 10):  # many different failures: memory stays bounded
+            fl.log_failure("ssh", f"failure number {i}")
+        self.assertLessEqual(len(fl._logged), fl.LOG_REMEMBER)
+
+    def test_hosts_ssh_names_go_known_or_not_and_whatever_the_case(self):
+        err = quiet_log(self)
+        fl.log_failure("ssh", "ssh stopped", "ssh: Could not resolve hostname bastion-jane: Name or service not known")
+        fl.log_failure("ssh", "ssh stopped", "channel 0: open failed: connect to host jane-office.example.com port 22")
+        fl.log_failure("ssh", "ssh stopped", "kex_exchange_identification: Connection reset by steamdeck-jane",
+                       hosts=["STEAMDECK-JANE"])
+        fl.log_failure("ssh", "Timed out talking to frame-jane", "")
+        out = err.getvalue()
+        self.assertIn("hostname <host>", out)
+        self.assertIn("connect to host <host> port 22", out)
+        for leaked in ("bastion-jane", "jane-office", "steamdeck-jane", "frame-jane"):
+            self.assertNotIn(leaked, out)
+
+    def test_headsets_named_like_sshs_words_dont_shield_the_real_host(self):
+        err = quiet_log(self)
+        for saved in ("host", "hostname", "to"):
+            fl.log_failure("ssh", "ssh stopped", "ssh: connect to host bastion-jane port 22: Connection refused",
+                           hosts=[saved])
+            fl.log_failure("ssh", "ssh stopped", "ssh: Could not resolve hostname jane-office.example.com: not known",
+                           hosts=[saved])
+        out = err.getvalue()
+        self.assertIn("connect to host <host> port 22", out)
+        self.assertIn("hostname <host>", out)
+        for leaked in ("bastion-jane", "jane-office"):
+            self.assertNotIn(leaked, out)
+        self.assertEqual(fl.hide_hosts("<host> and frame", ["host", "frame"]), "<host> and <host>")
+
+    def test_whole_names_go_before_sshs_words_and_only_real_tokens_are_spared(self):
+        for name, said in (("Jane Doe's work headset", "Timed out talking to Jane Doe's work headset"),
+                           ("Jane to Doe headset", "Jane to Doe headset stopped answering"),
+                           ("<Jane Doe>", "<Jane Doe> stopped answering")):
+            out = fl.scrub_failure(said, [name])
+            self.assertTrue(out.startswith("<host>") or out == "Timed out talking to <host>", out)
+            for leaked in ("Jane", "Doe"):
+                self.assertNotIn(leaked, out)
+        self.assertEqual(fl.scrub_failure("Timed out talking to Jane Doe's work headset", ["Jane Doe's work headset"]),
+                         "Timed out talking to <host>")
+        self.assertEqual(fl.hide_hosts("<user>@<host>: <ip>", ["user", "host", "ip"]), "<user>@<host>: <ip>")
+
+    def test_windows_user_names_with_spaces_go_whole(self):
+        err = quiet_log(self)
+        with mock.patch.object(fl.frame_telemetry, "_user_names", return_value=set()):
+            fl.log_failure("ssh", r"Bad owner or permissions on C:\Users\Jane Doe/.ssh/config", "")
+            fl.log_failure("login", "The Frame didn't accept this computer's SSH key.",
+                           "Jane Doe@frame: Permission denied (publickey).")
+            fl.log_failure("login", "refused", r"debug | ssh said: CORP\jane@frame's password: denied")
+        out = err.getvalue()
+        self.assertIn(r"C:\Users\<user>/.ssh/config", out)
+        self.assertIn("<user>@<host>: Permission denied", out)
+        for leaked in ("Jane", "Doe", "jane", "CORP"):
+            self.assertNotIn(leaked, out)
+
+    def test_whole_ssh_user_at_host_fields_and_home_folders_go(self):
+        import frame_telemetry as tm
+        with mock.patch.object(tm, "_user_names", return_value=set()):
+            self.assertEqual(tm.scrub(r"CORP\Jane Doe@jane-office.example.com: Permission denied (publickey)."),
+                             "<user>@<host>: Permission denied (publickey).")
+            self.assertEqual(tm.scrub("jane@jane-office.example.com's password: "), "<user>@<host>'s password: ")
+            self.assertEqual(tm.scrub(r"Bad owner on C:\Users\O'Brien/.ssh/config"), r"Bad owner on C:\Users\<user>/.ssh/config")
+            self.assertEqual(tm.scrub(r"c:\users\Zoë Smith.Jr\.ssh\config"), r"c:\users\<user>\.ssh\config")
+            self.assertEqual(tm.scrub("/users/O'Brien/x and /HOME/jane doe/y"), "/users/<user>/x and /HOME/<user>/y")
+            self.assertEqual(tm.scrub("write to me@example.com today"), "write to <email> today")
+
+
+class ConnectionDiagnostics(unittest.TestCase):
+    def test_address_kinds_never_the_address(self):
+        self.assertEqual(fl.address_kind("frame.local", "fe80::1%eth0"), ".local->ipv6 link-local")
+        self.assertEqual(fl.address_kind("frame.local", "192.168.1.5"), ".local->ipv4")
+        self.assertEqual(fl.address_kind("frame.local"), ".local")
+        self.assertEqual(fl.address_kind("fe80::1%5"), "ipv6 link-local")
+        self.assertEqual(fl.address_kind("2001:db8::1"), "ipv6")
+        self.assertEqual(fl.address_kind("192.168.1.5", "192.168.1.5"), "ipv4")
+        self.assertEqual(fl.address_kind("100.101.102.103"), "tailscale")
+        self.assertEqual(fl.address_kind("frame.tail1234.ts.net", "100.101.102.103"), "tailscale")
+        self.assertEqual(fl.address_kind("steamdeck"), "hostname")
+        self.assertEqual(fl.probes_summary([{"host": "frame", "label": "from ~/.ssh/config", "state": "timeout"}]),
+                         "alias hostname timeout")
+
+    def test_hidden_hosts_leave_the_rest(self):
+        self.assertEqual(fl.hide_hosts("frame_link: Could not resolve hostname frame", ["frame"]),
+                         "frame_link: Could not resolve hostname <host>")
+        self.assertEqual(fl.hide_hosts("ssh frame to frame.local", ["frame.local", "frame"], keep=("frame",)),
+                         "ssh frame to <host>")
+        self.assertEqual(fl.hide_hosts("reset by SteamDeck", ["steamdeck"]), "reset by <host>")
+        self.assertEqual(fl.hide_operands("The headset took too long to answer."), "The headset took too long to answer.")
+
+    def test_ssh_version_is_rebuilt_from_its_numbers(self):
+        import frame_report as fr
+        for said, want in (("OpenSSH_for_Windows_9.5p1, LibreSSL 3.8.2\n", "OpenSSH for Windows 9.5p1, LibreSSL 3.8.2"),
+                           ("OpenSSH_9.9p1, LibreSSL 3.3.6\n", "OpenSSH 9.9p1, LibreSSL 3.3.6"),
+                           ("OpenSSH_8.9p1 Ubuntu-3ubuntu0.10, OpenSSL 3.0.2 15 Mar 2022\n", "OpenSSH 8.9p1"),
+                           ("OpenSSH_9.6p1, OpenSSL 3.0.13 30 Jan 2024\n", "OpenSSH 9.6p1, OpenSSL 3.0.13"),
+                           ("OpenSSH_9.9p1-Jane-Doe-Laptop, LibreSSL 3.3.6\n", "unknown"),
+                           ("OpenSSH_9.9p1, OpenSSL jane-laptop\n", "OpenSSH 9.9p1"),
+                           (r"C:\Users\Jane\OpenSSH-portable\ssh.exe: not found", "unknown"),
+                           ("", "unknown")):
+            with mock.patch.object(fr.frame_host, "run_ssh", return_value=subprocess.CompletedProcess([], 0, "", said)):
+                self.assertEqual(fr.ssh_version("ssh"), want, said)
+
+    def test_only_the_default_alias_is_named(self):
+        import frame_report as fr
+        self.assertEqual(fr.alias_kind("frame"), 'default ("frame")')
+        self.assertEqual(fr.alias_kind("jane-office.example.com"), "custom")
+
+    def test_a_slow_path_never_holds_up_a_report(self):
+        import frame_report as fr
+        release = threading.Event()
+
+        def slow():
+            release.wait(5)
+            return []
+        with mock.patch.dict(fr._ssh, {"thread": None, "line": None}), mock.patch.object(fr, "_ssh_on_path", slow), \
+                mock.patch.object(fr, "link", None), mock.patch.object(fr.shutil, "which", return_value="/usr/bin/ssh"), \
+                mock.patch.object(fr.frame_host, "run_ssh",
+                                  return_value=subprocess.CompletedProcess([], 0, "", "OpenSSH_9.9p1, LibreSSL 3.3.6\n")):
+            t0 = time.monotonic()
+            self.assertIn("Connection: no connector", fr.diagnostics())
+            self.assertIn("SSH: still being checked", fr.ssh_line())
+            self.assertLess(time.monotonic() - t0, 2)
+            thread = fr._ssh["thread"]
+            release.set()
+            thread.join(5)
+            self.assertTrue(fr._ssh["line"].startswith("SSH: "))
+            self.assertNotEqual(fr.ssh_line(), "SSH: still being checked")
+
+    def test_ssh_kinds(self):
+        import frame_report as fr
+        for path, kind in ((r"C:\WINDOWS\System32\OpenSSH\ssh.exe", "Windows OpenSSH (System32)"),
+                           (r"C:\Program Files\OpenSSH\ssh.exe", "OpenSSH in Program Files"),
+                           (r"C:\Program Files\Git\usr\bin\ssh.exe", "Git for Windows"),
+                           ("/usr/bin/ssh", "system OpenSSH"), ("/opt/homebrew/bin/ssh", "Homebrew or /usr/local"),
+                           ("/home/jane/bin/ssh", "other"), (None, "not found")):
+            self.assertEqual(fr.ssh_path_kind(path), kind)
+
+    def test_no_connector_says_so(self):
+        import frame_report as fr
+        with mock.patch.object(fr, "link", None):
+            self.assertIn("Connection: no connector", fr.diagnostics())
+
 
 @unittest.skipIf(os.name == "nt", "the stand-in ssh is a POSIX script")
 class ServerConnection(unittest.TestCase):

tests/test_release_workflow.py

@@ -0,0 +1,106 @@
+"""The "Create the draft release" step of .github/workflows/release.yml, taken out of
+the workflow and run with bash (as Actions runs it) against a stand-in gh
+(tests/fakegh/gh): a new draft's id comes straight from the POST even when the
+release list doesn't show it yet (v0.4.2's first run), a rerun reuses the draft
+found by tag_name, and a tag that isn't on GitHub stops it. Nothing here talks to
+GitHub.
+
+Run: python3 -m unittest discover -s tests
+"""
+import sandbox  # noqa: F401  (first: keeps tests off real data and services)
+import json
+import os
+import shutil
+import subprocess
+import tempfile
+import textwrap
+import unittest
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent.parent
+WORKFLOW = ROOT / ".github" / "workflows" / "release.yml"
+FAKEGH = ROOT / "tests" / "fakegh"
+STEP = "- name: Create the draft release"
+
+
+def step_script():
+    """The step's `run: |` block, dedented."""
+    lines = WORKFLOW.read_text().splitlines()
+    i = next(n for n, line in enumerate(lines) if line.strip() == STEP)
+    while lines[i].strip() != "run: |":
+        i += 1
+    indent = len(lines[i]) - len(lines[i].lstrip())
+    body = []
+    for line in lines[i + 1:]:
+        if line.strip() and len(line) - len(line.lstrip()) <= indent:
+            break
+        body.append(line)
+    return textwrap.dedent("\n".join(body)).strip() + "\n"
+
+
+def release(rid, tag_name, name="Frame Control 9.8.7", draft=True):
+    return {"id": rid, "tag_name": tag_name, "name": name, "draft": draft, "assets": []}
+
+
+# The step only runs on ubuntu-latest. On Windows `bash` is often the WSL launcher
+# (with no distribution on GitHub's runners), not a bash that can run tests/fakegh.
+@unittest.skipUnless(os.name != "nt" and shutil.which("bash") and shutil.which("jq"),
+                     "needs a POSIX bash and jq (for gh --jq); the step runs on ubuntu only")
+class DraftStep(unittest.TestCase):
+    def run_step(self, releases, tags="v9.8.7", tag="v9.8.7"):
+        d = Path(tempfile.mkdtemp())
+        (d / "step.sh").write_text(step_script())
+        (d / "releases.json").write_text(json.dumps(releases))
+        env = dict(os.environ, PATH="%s:%s" % (FAKEGH, os.environ["PATH"]),
+                   FAKEGH_RELEASES=str(d / "releases.json"), FAKEGH_TAGS=tags,
+                   FAKEGH_LOG=str(d / "log"), GITHUB_REF_NAME=tag, GH_REPO="saphid/frame-control")
+        p = subprocess.run(["bash", "--noprofile", "--norc", "-eo", "pipefail", str(d / "step.sh")],
+                           env=env, stdout=subprocess.PIPE, stderr=subprocess.PIPE,
+                           universal_newlines=True, timeout=30)
+        log = [json.loads(line) for line in (d / "log").read_text().splitlines()] if (d / "log").exists() else []
+        return p, log
+
+    def posts(self, log):
+        return [c for c in log if c[1:4] == ["-X", "POST", "repos/saphid/frame-control/releases"]]
+
+    def patches(self, log):
+        return [c for c in log if c[1:3] == ["-X", "PATCH"]]
+
+    def test_new_draft_uses_the_id_the_post_returns(self):
+        # The list doesn't show the fresh draft (it never does in the fake): v0.4.2's case.
+        p, log = self.run_step([])
+        self.assertEqual(p.returncode, 0, p.stderr + p.stdout)
+        [post] = self.posts(log)
+        for f in ("tag_name=v9.8.7", "name=Frame Control 9.8.7", "draft=true"):
+            self.assertIn(f, post)
+        self.assertIn(["api", "repos/saphid/frame-control/git/ref/tags/v9.8.7"], log)
+        [patch] = self.patches(log)
+        self.assertEqual(patch[3], "repos/saphid/frame-control/releases/9001")
+        self.assertIn("tag_name=v9.8.7", patch)
+        self.assertIn("release 9001 tag_name v9.8.7", p.stdout)
+        self.assertTrue(all(c[0] == "api" for c in log))  # never `gh release ...`
+
+    def test_a_rerun_reuses_the_draft_with_the_tag(self):
+        p, log = self.run_step([release(7, "v9.8.6", "Frame Control 9.8.6"), release(42, "v9.8.7")])
+        self.assertEqual(p.returncode, 0, p.stderr + p.stdout)
+        self.assertEqual(self.posts(log), [])
+        [patch] = self.patches(log)
+        self.assertEqual(patch[3], "repos/saphid/frame-control/releases/42")
+
+    def test_other_releases_alone_mean_a_new_draft(self):
+        p, log = self.run_step([release(7, "v9.8.6", "Frame Control 9.8.6", draft=False),
+                                release(8, "v9.8.70", "Frame Control 9.8.70")])
+        self.assertEqual(p.returncode, 0, p.stderr + p.stdout)
+        self.assertEqual(len(self.posts(log)), 1)
+        self.assertEqual(self.patches(log)[0][3], "repos/saphid/frame-control/releases/9001")
+
+    def test_stops_when_the_tag_is_not_on_github(self):
+        p, log = self.run_step([], tags="")
+        self.assertNotEqual(p.returncode, 0)
+        self.assertIn("tag v9.8.7 isn't on GitHub", p.stderr)
+        self.assertEqual(self.posts(log), [])
+        self.assertEqual(self.patches(log), [])
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/test_server.py

@@ -10,6 +10,7 @@ import http.client
 import io
 import json
 import os
+import shutil
 import socket
 import struct
 import subprocess
@@ -287,15 +288,77 @@ class OneServer(unittest.TestCase):
 
     @unittest.skipIf(os.name == "nt", "no SIGTERM on Windows")
     def test_sigterm_while_the_app_holds_stdin_exits_cleanly(self):
-        """The app keeps stdin open; a stop signal used to abort Python (SIGABRT) at exit."""
-        env = {**os.environ, "FRAME_CONTROL_DATA_DIR": tempfile.mkdtemp(prefix="frame-one-server-"),
-               "FRAME_ALIAS": "frame-control-test.invalid"}
-        proc = subprocess.Popen([sys.executable, str(ROOT / "ui" / "server.py"), "--port", "0", "--exit-on-eof"],
-                                env=env, stdin=subprocess.PIPE, stdout=subprocess.PIPE, stderr=subprocess.STDOUT, text=True)
-        self.addCleanup(lambda: (proc.stdin.close(), proc.stdout.close()))
-        self.assertIn("Frame Control on", proc.stdout.readline())
-        proc.terminate()
-        self.assertEqual(proc.wait(30), 0, proc.stdout.read())
+        """The app keeps stdin open; a stop signal used to abort Python (SIGABRT) at exit,
+        and later, now and then, crash it (SIGSEGV) while background threads were still
+        loading TLS certificates. Run a few times: that crash came about 1 run in 100."""
+        for attempt in range(5):
+            with self.subTest(attempt=attempt):
+                env = {**os.environ, "FRAME_CONTROL_DATA_DIR": tempfile.mkdtemp(prefix="frame-one-server-"),
+                       "FRAME_ALIAS": "frame-control-test.invalid", "PYTHONFAULTHANDLER": "1"}
+                proc = subprocess.Popen([sys.executable, str(ROOT / "ui" / "server.py"), "--port", "0", "--exit-on-eof"],
+                                        env=env, stdin=subprocess.PIPE, stdout=subprocess.PIPE,
+                                        stderr=subprocess.STDOUT, text=True)
+                try:
+                    self.assertIn("Frame Control on", proc.stdout.readline())
+                    proc.terminate()
+                    self.assertEqual(proc.wait(30), 0, proc.stdout.read())
+                finally:
+                    if proc.poll() is None:
+                        proc.kill()
+                        proc.wait()
+                    proc.stdin.close()
+                    proc.stdout.close()
+                    shutil.rmtree(env["FRAME_CONTROL_DATA_DIR"], ignore_errors=True)
+
+    def test_staging_folders_cleared_when_stopped_mid_transfer(self):
+        """The server leaves without interpreter teardown, so TemporaryDirectory cleanup
+        doesn't run for work still in progress: its own staging folders go on the way out,
+        and a dead server's at the next start."""
+        dead = subprocess.Popen([sys.executable, "-c", "pass"])
+        dead.wait()
+        home = tempfile.mkdtemp(prefix="frame-stop-home-")
+        self.addCleanup(shutil.rmtree, home, ignore_errors=True)
+        env = {**os.environ, "FRAME_CONTROL_DATA_DIR": os.path.join(home, "data"),
+               "FRAME_ALIAS": "frame-control-test.invalid", "HOME": home, "XDG_CACHE_HOME": os.path.join(home, ".cache"),
+               "LOCALAPPDATA": home, "APPDATA": home}
+        index_dir = Path(subprocess.run(
+            [sys.executable, "-c", "import sys; sys.path.insert(0, sys.argv[1]); import frame_host; "
+                                   "print(frame_host.cache_dir('apk-sources'))", str(ROOT / "ui")],
+            env=env, capture_output=True, text=True, check=True).stdout.strip())
+        index_dir.mkdir(parents=True)
+        tmp = Path(tempfile.gettempdir())
+
+        def staged(folder, prefix, pid):
+            d = Path(tempfile.mkdtemp(prefix=f"{prefix}{pid}-", dir=folder))
+            self.addCleanup(shutil.rmtree, d, ignore_errors=True)
+            (d / "app.apk").write_bytes(b"\0" * 4096)
+            return d
+
+        # Stopped as the app stops it: by closing stdin (the only way on Windows,
+        # where terminate() is a hard kill) and, elsewhere, by SIGTERM too.
+        for stop in ["stdin"] + (["sigterm"] if os.name != "nt" else []):
+            with self.subTest(stop=stop):
+                left_by_dead = [staged(tmp, "frame-vr-", dead.pid), staged(index_dir, ".download-", dead.pid)]
+                proc = subprocess.Popen([sys.executable, str(ROOT / "ui" / "server.py"), "--port", "0", "--exit-on-eof"],
+                                        env=env, stdin=subprocess.PIPE, stdout=subprocess.PIPE,
+                                        stderr=subprocess.STDOUT, text=True)
+                try:
+                    self.assertIn("Frame Control on", proc.stdout.readline())
+                    self.assertEqual([d for d in left_by_dead if d.exists()], [])
+                    in_flight = [staged(tmp, "frame-vr-", proc.pid), staged(tmp, "frame-agent-", proc.pid),
+                                 staged(index_dir, ".download-", proc.pid)]
+                    if stop == "stdin":
+                        proc.stdin.close()
+                    else:
+                        proc.terminate()
+                    self.assertEqual(proc.wait(30), 0, proc.stdout.read())
+                    self.assertEqual([d for d in in_flight if d.exists()], [])
+                finally:
+                    if proc.poll() is None:
+                        proc.kill()
+                        proc.wait()
+                    proc.stdin.close()
+                    proc.stdout.close()
 
 
 class ArtworkSettings(unittest.TestCase):

tests/test_webinstall.py

@@ -386,17 +386,28 @@ class ServerJobs(unittest.TestCase):
     def test_dead_servers_leftovers_swept(self):
         dead = subprocess.Popen([sys.executable, "-c", "pass"])
         dead.wait()
-        # Downloads and title staging (unzipped titles) are both swept.
-        for prefix in (self.server.WEB_TMP_PREFIX, self.server.frame_titles.TMP_PREFIX):
-            gone = tempfile.mkdtemp(prefix=f"{prefix}{dead.pid}-")
-            live = tempfile.mkdtemp(prefix=f"{prefix}{os.getpid()}-")
-            try:
-                self.server.sweep_tmp()
-                self.assertFalse(os.path.exists(gone), prefix)
-                self.assertTrue(os.path.exists(live), prefix)
-            finally:
-                shutil.rmtree(gone, ignore_errors=True)
-                shutil.rmtree(live, ignore_errors=True)
+        s = self.server
+        with tempfile.TemporaryDirectory() as cache, \
+                mock.patch.object(s.frame_host, "cache_dir", lambda *parts: Path(cache).joinpath(*parts)):
+            # Downloads, title staging, patched VR APKs, files staged for the
+            # assistant, and app-index downloads (in the cache folder).
+            places = s._tmp_places()
+            self.assertEqual({p for _, p in places}, {s.WEB_TMP_PREFIX, s.frame_titles.TMP_PREFIX,
+                                                      s.frame_android.TMP_PREFIX, s.frame_agent.TMP_PREFIX,
+                                                      s.apk_fdroid.TMP_PREFIX})
+            for folder, prefix in places:
+                folder.mkdir(parents=True, exist_ok=True)
+                gone = tempfile.mkdtemp(prefix=f"{prefix}{dead.pid}-", dir=folder)
+                live = tempfile.mkdtemp(prefix=f"{prefix}{os.getpid()}-", dir=folder)
+                try:
+                    s.sweep_tmp()
+                    self.assertFalse(os.path.exists(gone), prefix)
+                    self.assertTrue(os.path.exists(live), prefix)
+                    s.sweep_tmp(own=True)  # on the way out: this server's own go too
+                    self.assertFalse(os.path.exists(live), prefix)
+                finally:
+                    shutil.rmtree(gone, ignore_errors=True)
+                    shutil.rmtree(live, ignore_errors=True)
 
     def test_temp_dir_failure_ends_the_job(self):
         job, dispatch = self.run_job(mkdtemp_error=OSError("disk full"))

ui/apk_sources/fdroid.py

@@ -27,6 +27,7 @@ from frame_catalog import _IndexReader, _reduce_index, _sha256
 
 KIND = 'fdroid'
 CACHE_VERSION = 2
+TMP_PREFIX = '.download-'  # in the cache folder, then the server's PID, so server.sweep_tmp can clear a stopped run's
 _LOCK = threading.RLock()  # settings only; never held while downloading
 _load_locks = {}
 _refreshing = {}  # source id -> background refresh thread
@@ -530,7 +531,7 @@ def _load(source, force=False):
             return found[:2]
         cache.parent.mkdir(parents=True, exist_ok=True)
         try:
-            with tempfile.TemporaryDirectory(dir=str(cache.parent)) as tmp:
+            with tempfile.TemporaryDirectory(prefix=f'{TMP_PREFIX}{os.getpid()}-', dir=str(cache.parent)) as tmp:
                 jar, raw = Path(tmp) / 'index.jar', Path(tmp) / 'index.json'
                 v2 = True
                 try:

ui/frame_agent.py

@@ -9,6 +9,8 @@ import subprocess
 import threading
 import time
 
+TMP_PREFIX = 'frame-agent-'  # then the server's PID, so server.sweep_tmp can clear a stopped run's
+
 
 class Approvals:
     def __init__(self):
@@ -109,7 +111,7 @@ def call(server, body):
     if name == 'send_file':
         # Stage the reviewed bytes before the existing transfer helper reads them.
         import tempfile
-        with tempfile.TemporaryDirectory(prefix='frame-agent-') as tmp:
+        with tempfile.TemporaryDirectory(prefix=f'{TMP_PREFIX}{os.getpid()}-') as tmp:
             source = Path(action['arguments']['path'])
             with source.open('rb') as stream:
                 data = stream.read(16 * 1024**2 + 1)

ui/frame_android.py

@@ -23,6 +23,7 @@ from frame_apk_sign import repack
 
 ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
 FRAME = os.environ.get('FRAME_ALIAS', 'frame')
+TMP_PREFIX = 'frame-vr-'  # then the server's PID, so server.sweep_tmp can clear a stopped run's patched APK
 APPS_DIR = 'Applications/Android'          # relative to the Frame's $HOME
 COMPAT = '.local/share/Steam/steamapps/compatdata'
 SHADERS = '.local/share/Steam/steamapps/shadercache'
@@ -200,7 +201,7 @@ def install(apk_path, flatscreen=None, name=None, source=None, icon_png=None, xr
                 info['xr_layer_missing'] = True
         with _install_lock:
             if add or info['repairable']:
-                with tempfile.TemporaryDirectory(prefix='frame-vr-') as tmp:
+                with tempfile.TemporaryDirectory(prefix=f'{TMP_PREFIX}{os.getpid()}-') as tmp:
                     patched = os.path.join(tmp, 'app.apk')
                     try:
                         info['patched'] = patch(apk_path, patched, add)['patched']

ui/frame_link.py

@@ -32,12 +32,14 @@ import queue
 import re
 import socket
 import subprocess
+import sys
 import threading
 import time
 
 import frame_devices
 import frame_host
 import frame_network
+import frame_telemetry
 
 PROBE_TIMEOUT = 4      # seconds for a TCP answer on port 22
 RESOLVE_GRACE = 6      # ...after however long the name lookup took, up to this much
@@ -136,6 +138,115 @@ def probe(host, port, timeout=PROBE_TIMEOUT, update=None):
     return last or {"state": "timeout", "detail": "No answer"}
 
 
+def _ip_kind(text):
+    """ipv4, ipv6, ipv6 link-local or tailscale for an IP address (zone allowed), else None."""
+    try:
+        ip = ipaddress.ip_address((text or "").strip("[]").split("%")[0])
+    except ValueError:
+        return None
+    if frame_network.is_tailscale(str(ip)):
+        return "tailscale"
+    return "ipv4" if ip.version == 4 else "ipv6 link-local" if ip.is_link_local else "ipv6"
+
+
+def address_kind(host, ip=None):
+    """What sort of address a probe row is, for diagnostics, never the address itself:
+    ".local", "ipv4", "ipv6", "ipv6 link-local", "tailscale" or "hostname", plus what a
+    name resolved to (".local->ipv6 link-local") when the probe got that far."""
+    h = (host or "").lower().rstrip(".")
+    kind = _ip_kind(h) or (".local" if h.endswith(".local") else
+                           "tailscale" if frame_network.is_tailscale(h) else "hostname")
+    got = _ip_kind(ip) if ip and not _ip_kind(h) else None
+    return f"{kind}->{got}" if got and got != kind else kind
+
+
+def probes_summary(probes):
+    """Each address tried, as its kind and how the probe went: "alias .local->ipv4 timeout"."""
+    out = []
+    for row in probes or ():
+        lead = "alias " if row.get("label") == "from ~/.ssh/config" else ""
+        out.append(f"{lead}{address_kind(row.get('host'), row.get('ip'))} {row.get('state') or '?'}")
+    return "; ".join(out)
+
+
+# Exactly the tokens the scrubbers write (here and frame_telemetry.scrub), nothing else in <...>.
+PLACEHOLDER = re.compile(r"(<(?:host|user|email|ip|mac|steamid|hex|token|ssh-key|pem|url|redacted)>)")
+
+
+def hide_hosts(text, hosts, keep=()):
+    """text with each of `hosts` (the headset's own addresses and names) replaced by <host>,
+    longest first and whatever the case, so a bare name like "steamdeck" that the scrubber
+    can't recognise goes too."""
+    keep = {k.lower() for k in keep if k} | KEYWORDS  # a headset called "host" mustn't eat ssh's wording
+    names = sorted({h for h in hosts if h and h.lower() not in keep}, key=len, reverse=True)
+    parts = PLACEHOLDER.split(text)  # never inside a scrubber's own <token> already there
+    for i in range(0, len(parts), 2):
+        for h in names:
+            parts[i] = re.sub(r"(?<![\w.:-])%s(?![\w-]|[:.%%]\w)" % re.escape(h), "<host>", parts[i], flags=re.I)
+    return "".join(parts)
+
+
+# ssh names the host it was going to after these words ("Could not resolve hostname X",
+# "connect to host X port 22", "Timed out talking to X"): whatever follows goes, known or not.
+OPERAND = re.compile(r"(?i)\b(hostname|host|to(?:\s+host)?)\s+(?!<)([^\s:,;'\"()|]+)")
+PLAIN_WORDS = {"answer", "the", "a", "an", "this", "it", "its", "be", "connect", "find", "work", "try"}
+KEYWORDS = {"host", "hostname", "to", "port"} | PLAIN_WORDS
+
+
+def hide_operands(text):
+    def one(m):
+        word = m.group(2).rstrip(".")
+        dots = m.group(2)[len(word):]
+        return m.group(0) if word.lower() in PLAIN_WORDS else f"{m.group(1)} <host>{dots}"
+    return OPERAND.sub(one, text)
+
+
+def scrub_failure(text, hosts=()):
+    """Free text about a failed attempt, for the log: the attempt's own names, whole and
+    longest first (case-insensitively, never ssh's own words), then anything ssh names as a
+    host, then the shared scrubber (addresses, paths, user names)."""
+    return frame_telemetry.scrub(hide_operands(hide_hosts(str(text or ""), hosts)), 600)
+
+
+def failure_category(message, raw=""):
+    """The telemetry error category (frame_unreachable, frame_auth, ...) for a failure: a fixed
+    word, never its text."""
+    return frame_telemetry.categorize(f"{message or ''}\n{raw or ''}")[0]
+
+
+_logged = {}            # failure line -> {"at": when last written, "repeats": since then}
+LOG_REPEAT_EVERY = 300  # the same failure, retried every 30 s, goes in the log at most this often
+LOG_REMEMBER = 32       # different failures remembered for that
+
+
+def log_failure(stage, message, raw="", probes=(), hosts=()):
+    """One failed connection attempt to stderr (the app's server.log), scrubbed when written,
+    with the hosts of that attempt (so a later switch of headset can't let them through)."""
+    hosts = list(hosts) + [r.get(k) for r in probes or () for k in ("host", "ip")]
+    bits = [f"frame_link: {stage} failed: {scrub_failure(message, hosts)}"]
+    last = [ln.strip() for ln in (raw or "").splitlines() if ln.strip()][-1:]
+    if last and last[0] != message:
+        bits.append(f"ssh said: {scrub_failure(last[0][:300], hosts)}")
+    tried = probes_summary(probes)
+    if tried:
+        bits.append(f"addresses: {tried}")
+    line = " | ".join(bits)[:900]
+    t = time.monotonic()
+    seen = _logged.get(line)
+    if seen and t - seen["at"] < LOG_REPEAT_EVERY:
+        seen["repeats"] += 1
+        return
+    more = f" (and {seen['repeats']} more times)" if seen and seen["repeats"] else ""
+    _logged.pop(line, None)
+    _logged[line] = {"at": t, "repeats": 0}
+    while len(_logged) > LOG_REMEMBER:
+        _logged.pop(next(iter(_logged)))  # the least recently written
+    try:
+        print(line + more, file=sys.stderr, flush=True)
+    except (OSError, ValueError, AttributeError):
+        pass  # no stderr (a closed pipe): the page still shows the failure
+
+
 def ssh_target(host, ip):
     """Where ssh should go for an address whose probe answered from `ip`: that IP, so ssh
     doesn't look the name up again and try an address that didn't answer."""
@@ -188,6 +299,8 @@ class Link:
         self.route_lock = threading.Lock()
         self.routed = None              # the device id every ssh command points at
         self.routed_device = None
+        self.last_failure = None        # {"stage", "category", "at"}: for report diagnostics, no free text
+        self.attempt_device = None      # the headset the current attempt is for
 
     # ---- publishing ----
     def publish(self, **fields):
@@ -436,7 +549,9 @@ class Link:
                 if reasons:
                     self.connect(reasons)
             except Exception as e:  # keep the loop alive whatever happens; say what went wrong
-                self.publish(phase="failed", error={"stage": "network", "message": f"{type(e).__name__}: {e}",
+                message = f"{type(e).__name__}: {e}"
+                self.note_failure("network", message, str(e))
+                self.publish(phase="failed", error={"stage": "network", "message": message,
                                                     "raw": str(e)}, retry_at=now() + RETRY[-1])
             finally:
                 with self.cond:
@@ -512,6 +627,7 @@ class Link:
             self.cond.notify_all()
         ok = False
         try:
+            self.attempt_device = device  # its names, for scrubbing this attempt's log lines
             ok = self.attempt(device)
         finally:
             self.finish(gen, ok, device)
@@ -540,6 +656,7 @@ class Link:
                                   now() + RETRY[min(self.fails, len(RETRY)) - 1])
                 if not self.state["error"]:
                     self.state["error"] = {"stage": "find", "message": "Couldn't connect", "raw": ""}
+                    self.note_failure("find", "Couldn't connect", "", self.state["probes"])
             self.version += 1
             self.cond.notify_all()
 
@@ -562,13 +679,26 @@ class Link:
         self.stage(sid, "failed", message)
         with self.cond:
             self.state["error"] = {"stage": sid, "message": message, "raw": raw}
+            probes = copy.deepcopy(self.state["probes"])
+        self.note_failure(sid, message, raw, probes)
+
+    def note_failure(self, stage, message, raw="", probes=()):
+        """Keep a failure for report diagnostics as fixed values only (its stage and error
+        category, decided now), and write it to the log scrubbed with this attempt's hosts."""
+        self.last_failure = {"stage": stage, "category": failure_category(message, raw), "at": now()}
+        hosts = []
+        for d in (self.attempt_device, self.routed_device):  # the headset tried, and where commands go
+            d = d or {}
+            hosts += [a.get("host") for a in d.get("addresses") or ()]
+            hosts += [d.get("frozen_host"), d.get("alias"), d.get("name")]
+        log_failure(stage, message, raw, probes, hosts)
 
     def attempt(self, device):
         if device.get("none"):
             self.fail("find", "No headset is set up. Add one on the Devices tab.")
             return False
         if not device.get("transient") and not device["addresses"]:
-            self.fail("find", f"{device['name']} has no addresses. Add one on the Devices tab.")
+            self.fail("find", "The active headset has no addresses. Add one on the Devices tab.")
             return False
         # 1. this computer's network
         self.stage("network", "active")

ui/frame_report.py

@@ -13,12 +13,18 @@ frame_contact.py's `contact_consent` events; `contacts` lists them.
 """
 import os
 import platform
+import re
+import shutil
+import subprocess
 import sys
+import threading
 import time
 import uuid
 
 import frame_contact
+import frame_devices
 import frame_host
+import frame_link
 import frame_telemetry
 
 KINDS = ('bug', 'idea', 'question', 'other')
@@ -28,6 +34,7 @@ LOG_LINES = 60
 ACTIVITY_LINES = 25
 
 frame = {}  # the Frame's last known SteamOS build, set by server.status()
+link = None  # the connector (frame_link.Link), set by server.main; None on the Frame itself
 
 
 def u16(s):
@@ -59,9 +66,174 @@ def _log_tail():
     return list(reversed(keep[-LOG_LINES:]))
 
 
+def ssh_path_kind(path):
+    """What sort of ssh a path is, never the path itself (it can hold a user name)."""
+    if not path:
+        return "not found"
+    p = str(path).replace("\\", "/").lower()
+    for marks, kind in ((("/system32/openssh/", "/sysnative/openssh/"), "Windows OpenSSH (System32)"),
+                        (("/program files/openssh",), "OpenSSH in Program Files"),
+                        (("/git/",), "Git for Windows"), (("msys", "cygwin"), "MSYS2/Cygwin"),
+                        (("/opt/homebrew/", "/usr/local/", "linuxbrew"), "Homebrew or /usr/local"),
+                        (("/nix/",), "Nix")):
+        if any(m in p for m in marks):
+            return kind
+    if p in ("/usr/bin/ssh", "/bin/ssh"):
+        return "system OpenSSH"
+    return "other"
+
+
+def _ssh_on_path():
+    """Every ssh on PATH, in the order they're found; the first is the one the app runs."""
+    names = ("ssh.exe", "ssh") if frame_host.WINDOWS else ("ssh",)
+    found, seen = [], set()
+    for d in os.get_exec_path():
+        for name in names:
+            cand = os.path.join(d, name)
+            key = os.path.normcase(os.path.abspath(cand))
+            if key not in seen and os.path.isfile(cand):
+                seen.add(key)
+                found.append(cand)
+                break
+    return found
+
+
+# Only a real banner at the very start ("OpenSSH_9.9p1, LibreSSL 3.3.6",
+# "OpenSSH_for_Windows_9.5p1, LibreSSL 3.8.2"): rebuilt from fixed names and its numbers.
+BANNER_RE = re.compile(r"OpenSSH_(for_Windows_)?(\d+)\.(\d+)(p\d+)?(?=[,\s]|$)")
+LIBRARY_RE = re.compile(r",?\s*(LibreSSL|OpenSSL) (\d+\.\d+\.\d+[a-z]?)(?=[,\s]|$)")
+
+
+def parse_ssh_version(said):
+    """"OpenSSH 9.9p1, LibreSSL 3.3.6"-style text from `ssh -V`'s output, or "unknown"."""
+    said = (said or "").lstrip()
+    m = BANNER_RE.match(said)
+    if not m:
+        return "unknown"
+    out = f"OpenSSH{' for Windows' if m.group(1) else ''} {m.group(2)}.{m.group(3)}{m.group(4) or ''}"
+    lib = LIBRARY_RE.match(said, m.end())
+    return out + (f", {lib.group(1)} {lib.group(2)}" if lib else "")
+
+
+def ssh_version(path):
+    """The version from `ssh -V` (it prints to stderr), nothing else it says."""
+    try:
+        r = frame_host.run_ssh([path, "-V"], capture_output=True, stdin=subprocess.DEVNULL, text=True,
+                               errors="replace", timeout=5)
+    except (OSError, subprocess.SubprocessError) as e:
+        return f"couldn't run it ({type(e).__name__})"
+    return parse_ssh_version(r.stderr or r.stdout)
+
+
+def _ssh_check():
+    path = shutil.which("ssh")
+    if not path:
+        return "SSH: no ssh on PATH"
+    others = [ssh_path_kind(p) for p in _ssh_on_path()
+              if os.path.normcase(os.path.abspath(p)) != os.path.normcase(os.path.abspath(path))]
+    others = [k for i, k in enumerate(others) if k not in others[:i]]
+    return f"SSH: {ssh_path_kind(path)}, {ssh_version(path)}" + (f"; also on PATH: {', '.join(others)}" if others else "")
+
+
+_ssh = {"thread": None, "line": None}
+_ssh_lock = threading.Lock()
+SSH_WAIT = 0.3  # how long a report preview waits for the ssh check (PATH can hold slow network drives)
+
+
+def start_ssh_check():
+    """Look for ssh once, in the background (server.main starts it), so a report never waits
+    on PATH folders on slow or mapped drives."""
+    def run():
+        try:
+            line = _ssh_check()
+        except Exception as e:  # a report must still go out
+            line = f"SSH: couldn't check ({type(e).__name__})"
+        _ssh["line"] = line
+    with _ssh_lock:
+        if _ssh["thread"] is None:
+            _ssh["thread"] = threading.Thread(target=run, name="report-ssh-check", daemon=True)
+            _ssh["thread"].start()
+        return _ssh["thread"]
+
+
+def ssh_line():
+    start_ssh_check().join(SSH_WAIT)
+    return _ssh["line"] or "SSH: still being checked"
+
+
+def config_line(alias):
+    """Whether ~/.ssh/config has the managed block for the alias, and a hand-written Host for it."""
+    try:
+        text = frame_devices.ssh_config().read_text(encoding="utf-8", errors="replace")
+    except FileNotFoundError:
+        return "~/.ssh/config: missing"
+    except OSError as e:
+        return f"~/.ssh/config: can't read it ({type(e).__name__})"
+    blocks = [b["alias"] for b in frame_devices.parse_blocks(text)]
+    outside, inside = [], None
+    for line in text.splitlines():
+        m = frame_devices.BLOCK_RE.fullmatch(line.strip())
+        if m:
+            inside = m.group(1)
+        elif inside and line.strip() == frame_devices.end_mark(inside):
+            inside = None
+        elif not inside:
+            outside.append(line)
+    own = any(alias in re.split(r"[\s=]+", ln.strip())[1:] for ln in outside
+              if re.match(r"(?i)\s*host[\s=]", ln))
+    return (f"~/.ssh/config: managed block for the active alias {'yes' if alias in blocks else 'no'} "
+            f"({len(blocks)} managed in all); hand-written Host for it {'yes' if own else 'no'}")
+
+
+def alias_kind(alias):
+    """`default ("frame")` or `custom`: a name someone chose can say who they are."""
+    return 'default ("frame")' if alias == "frame" else "custom"
+
+
+def connection_lines():
+    """A short summary of the connector in fixed words only: states, stages, error categories,
+    kinds of address, counts. No text from errors or ssh, no custom alias, never an address."""
+    if link is None:
+        return ["Connection: no connector (this server doesn't reach a headset over SSH)"]
+    snap = link.snapshot()
+    active = link.active_device()
+    alias = active.get("alias") or "?"
+    phase, err, via = snap.get("phase") or "idle", snap.get("error"), snap.get("via")
+    head = f"Connection: {phase}"
+    if phase == "connected" and via:
+        rtt = via.get("rtt_ms")
+        head += f" via {frame_link.address_kind(via.get('host'), via.get('ip'))}" + (f" ({rtt:g} ms)" if rtt is not None else "")
+    elif err:
+        head += f" at {err.get('stage')}"
+    head += f", attempt {snap.get('attempt') or 0}" + (f" ({snap['reason']})" if snap.get("reason") else "")
+    lines = [head]
+    kind = ("none set up" if active.get("none") else "a bare ssh alias" if active.get("transient")
+            else f"saved, {len(active.get('addresses') or [])} address(es)")
+    lines.append(f"Headsets: {len(link.reg.devices())} saved; active alias {alias_kind(alias)} ({kind})")
+    if err:
+        lines.append(f"Error: {err.get('stage')}, {frame_link.failure_category(err.get('message'), err.get('raw'))}")
+    last = link.last_failure
+    if last:
+        ago = max(0, int(frame_link.now() - last.get("at", 0)))
+        lines.append(f"Last failure: {last.get('stage')}, {last.get('category')}, {ago // 60} min {ago % 60} s ago")
+    lines.append(f"Addresses tried: {frame_link.probes_summary(snap.get('probes')) or 'none yet'}")
+    net = snap.get("network")
+    if net:
+        ts = net.get("tailscale") or {}
+        lines.append(f"Network: gateway {'yes' if net.get('gateway') else 'no'}, Tailscale "
+                     f"{'on' if ts.get('up') else 'off' if ts.get('installed') else 'not installed'}")
+    for part in (ssh_line, lambda: config_line(alias)):
+        try:
+            lines.append(part())
+        except Exception as e:  # a report must still go out
+            lines.append(f"({type(e).__name__} while checking SSH)")
+    return lines
+
+
 def diagnostics(activity=(), include_logs=False, limit=DIAG_MAX):
     """What a report includes, scrubbed and at most `limit` UTF-16 units. Always the versions
-    and builds; recent activity and the server log only when asked for, since they can name
+    and builds, and a connection summary (connection_lines: kinds of address and states, never
+    the addresses, so "the app can't find the headset" can be told apart); recent activity and the server log only when asked for, since they can name
     files. Sections are filled in order of use, newest lines first, so trimming drops the oldest."""
     t = frame_telemetry.state()
     levels = ', '.join(f"{name} {'on' if on else 'off'}" for name, on in
@@ -74,7 +246,11 @@ def diagnostics(activity=(), include_logs=False, limit=DIAG_MAX):
         f"Analytics: {levels}",
         f"Report time: {time.strftime('%Y-%m-%d %H:%M %Z')}",
     ]
-    out = frame_telemetry.scrub('\n'.join(env), limit=limit)
+    try:
+        conn = connection_lines()
+    except Exception as e:  # never stop a report over its diagnostics
+        conn = [f"Connection: summary unavailable ({type(e).__name__})"]
+    out = frame_telemetry.scrub('\n'.join(env) + '\n\n' + '\n'.join(conn), limit=limit)
     if not include_logs:
         return cut(out, limit)
     sections = [('Recent activity (newest first):', [str(a)[:300] for a in list(activity)[:ACTIVITY_LINES] if isinstance(a, str)]),

ui/frame_telemetry.py

@@ -235,9 +235,16 @@ def scrub(text, limit=2000):
     home = str(Path.home())
     if len(home) > 3:
         t = t.replace(home, '~')
-    t = re.sub(r'(/Users/|/home/|[A-Za-z]:\\Users\\)[^/\\\s]+', r'\1<user>', t)
+    # A home folder's whole name ("C:\Users\Jane Doe", "/Users/O'Brien"), up to the next separator.
+    t = re.sub(r'''(?i)(/Users/|/home/|[A-Za-z]:[\\/]+Users[\\/]+)[^\\/\n"]+''', r'\1<user>', t)
+    # ssh's "user@host: ..." and "user@host's password:", the whole field: the user even with
+    # spaces or a DOMAIN\ prefix, the host even a full domain name. Before the email rule, which
+    # would otherwise take only the last word of the user.
+    t = re.sub(r'''(?m)(?:^|(?<=: )|(?<=\| ))[^@\n:|"<]{1,64}@[\w.\[\]%:<>-]+?(?=:(?:\s|$)|'s\s)''',
+               '<user>@<host>', t)
     for pattern, repl in SCRUBS:
         t = pattern.sub(repl, t)
+    t = re.sub(r'(?<![\w.+\\<-])[\w.+\\-]+@(?=[A-Za-z\[<])', '<user>@', t)  # any other word@host
     t = IPV6_RE.sub(_ipv6, t)
     for name in _user_names():
         t = re.sub(r'\b%s\b' % re.escape(name), '<user>', t)

ui/index.html

@@ -1272,7 +1272,7 @@
     <label class="field">Your email address<input type="email" id="bugContact" maxlength="254" placeholder="you@example.com" disabled></label>
     <p class="hint" id="bugReplaces" role="status" hidden></p>
     <label class="popt"><input type="checkbox" id="bugDiag" checked><b>Include diagnostics</b>
-      <span class="sub">Frame Control's version, your OS and the Frame's SteamOS build.</span></label>
+      <span class="sub">Frame Control's version, your OS, the Frame's SteamOS build, and a connection summary in fixed words: how connecting went, the kinds of address tried, your ssh version and whether ~/.ssh/config has the headset's entry. No error text, no custom alias name, and never the addresses themselves.</span></label>
     <label class="popt"><input type="checkbox" id="bugLogs"><b>Also include recent activity and the server log</b>
       <span class="sub">Often shows what went wrong, but can contain file and app names. Check it below before sending.</span></label>
     <details id="bugDiagBox"><summary>Show exactly what's included</summary><div class="sentlog" id="bugDiagText">Loading…</div></details>

ui/server.py

@@ -45,6 +45,7 @@ import frame_agent  # noqa: E402
 import frame_assistant  # noqa: E402
 import frame_android  # noqa: E402
 from apk_sources import search as apk_search, SourceError  # noqa: E402
+from apk_sources import fdroid as apk_fdroid  # noqa: E402
 import frame_apk_versions  # noqa: E402
 import frame_catalog  # noqa: E402
 import frame_devices  # noqa: E402
@@ -1935,23 +1936,36 @@ def _pid_alive(pid):
     return True
 
 
-def sweep_tmp():
-    """Delete download and title staging folders left by a server killed mid-install.
+def _tmp_places():
+    """Where each kind of staging folder goes, and its name before the server's PID."""
+    tmp = Path(tempfile.gettempdir())
+    return [(tmp, WEB_TMP_PREFIX), (tmp, frame_titles.TMP_PREFIX), (tmp, frame_android.TMP_PREFIX),
+            (tmp, frame_agent.TMP_PREFIX), (frame_host.cache_dir("apk-sources"), apk_fdroid.TMP_PREFIX)]
 
-    Folders carry the server's PID, so only a dead server's are taken.
+
+def sweep_tmp(own=False):
+    """Delete staging folders (downloads, unzipped titles, patched APKs, staged files,
+    app-index downloads) left by a server that stopped mid-way.
+
+    Folders carry the server's PID, so only a dead server's are taken; own=True (on
+    the way out, see main) takes this server's too.
     """
-    for prefix in (WEB_TMP_PREFIX, frame_titles.TMP_PREFIX):
-        for d in Path(tempfile.gettempdir()).glob(f"{prefix}*"):
-            _sweep_one(prefix, d)
+    for folder, prefix in _tmp_places():
+        try:
+            found = list(folder.glob(f"{prefix}*"))
+        except OSError:
+            continue
+        for d in found:
+            _sweep_one(prefix, d, own)
 
 
-def _sweep_one(prefix, d):
+def _sweep_one(prefix, d, own=False):
     m = re.fullmatch(re.escape(prefix) + r"(\d+)-.*", d.name)
     if not m:
         return
     pid = int(m[1])
     try:
-        if pid != os.getpid() and not _pid_alive(pid) and d.is_dir():
+        if (own if pid == os.getpid() else not _pid_alive(pid)) and d.is_dir():
             shutil.rmtree(d, ignore_errors=True)
     except OSError:
         pass
@@ -2723,6 +2737,8 @@ def main():
         LINK = frame_link.Link(frame_devices.Registry(), env_alias=FRAME if FRAME_FROM_ENV else None,
                                mux_base=MUX_BASE, control=CONTROL, apply=route, explain=unreachable)
         LINK.work_lock, LINK.work = _work_lock, lambda: _work[0]
+        frame_report.link = LINK  # its connection summary goes in every report's diagnostics
+        frame_report.start_ssh_check()  # ...with which ssh this is, found once in the background
         LINK.start()
     if not frame_host.WINDOWS:
         signal.signal(signal.SIGTERM, lambda *_: (_ for _ in ()).throw(KeyboardInterrupt))
@@ -2755,6 +2771,22 @@ def main():
             if proc.poll() is None:
                 proc.terminate()
         _purge_titles(now=float("inf"))  # unconfirmed title uploads
+        # Staging folders of work still running (a patched APK mid-copy, an index
+        # download): leaving below skips the cleanup their TemporaryDirectory would
+        # get at interpreter exit. sweep_tmp at the next start catches any missed.
+        sweep_tmp(own=True)
+    # Stopped as asked, and everything above is cleaned up. Leave now, without
+    # Python's interpreter teardown: daemon threads are still running (app index
+    # downloads, the stdin watcher, telemetry, the headset link, request handlers)
+    # and none can be stopped promptly. Tearing the interpreter down under them
+    # occasionally crashed the process (SIGSEGV, seen on Python 3.13 on Linux):
+    # OpenSSL's exit cleanup freed state those threads were using. That teardown
+    # also runs atexit handlers and weakref finalizers; nothing here registers
+    # atexit work, the only finalizers are TemporaryDirectory cleanups (swept
+    # above), and the OS frees the one-server lock with the process.
+    sys.stdout.flush()
+    sys.stderr.flush()
+    os._exit(0)
 
 
 if __name__ == "__main__":