Skip to content

PasteFerry (隔空贴): clipboard and file sync across macOS, Windows and Linux. Direct-first, end-to-end encrypted. Optional official access: no server to host. Independent self-hosting remains available.

docs: record 2.9.0 installation and cross-platform validation

baiyuze6e997c17dca5
diff --git a/design/2.9.0-installation-validation-2026-11-04.md b/design/2.9.0-installation-validation-2026-11-04.md
new file mode 100644
index 0000000..e5b6be7
--- /dev/null
+++ b/design/2.9.0-installation-validation-2026-11-04.md
@@ -0,0 +1,163 @@
+# PasteFerry 2.9.0 installation validation — 2026-11-04
+
+Tested application source: `53ee171d357b1a1b257c88e99e9301e2ff44ef17` on
+`codex/pasteferry-2.9.0`.
+
+**Release remains paused.** These results cover the candidate packages below.
+They do not authorize publishing the candidate or updating production download
+links. The public website, latest GitHub release, Homebrew cask and signed update
+manifest remain on 2.8.3. The existing 2.9.0 GitHub release is a draft. The pairing
+fix described below has not been merged into `main`.
+
+## Build provenance and environments
+
+[GitHub Actions run 41775262355](https://github.com/baiyuze/pasteferry/actions/runs/41775262355)
+completed successfully for the tested source commit. All nine jobs passed:
+UI analysis/tests, Go dependency security, Android, NAT traversal laboratory,
+Linux arm64, macOS core, Windows, server and Linux amd64.
+
+| Platform | Package used for installed tests | Runtime environment |
+| --- | --- | --- |
+| Windows x64 | `PasteFerry-Setup.exe`, downloaded from that CI run | Windows 11 Pro, build 26200, Parallels VM, logged-in desktop user |
+| Linux amd64 | `PasteFerry-linux-amd64.deb`, downloaded from that CI run | Ubuntu 24.04.5 LTS, kernel 6.8, Parallels VM; isolated X11 display via Xvfb |
+| macOS Intel | `PasteFerry-mac-intel.dmg`, built locally from the same clean commit using `scripts/package.sh` | macOS 15.7.3, Intel host; actual `/Applications/PasteFerry.app` installation |
+
+Windows and Linux packages were produced in CI, downloaded and installed. Mac
+DMGs were built locally with the existing signing identity. The final Mac build
+was made after temporary QA helper sources were removed from the checkout.
+Mac and Linux About views showed UI/backend 2.9.0 and build `53ee171d`. Windows
+installed GUI settings and the daemon/CLI reported 2.9.0.
+
+The native QA helper is outside the repository. It invokes the installed
+daemon's RPC API and reads the operating system clipboard. Clipboard source
+writes use native platform APIs; Windows uses the logged-in user's
+PowerShell/WinForms clipboard. Test helpers are not bundled in the application.
+
+## Installed application results
+
+| Area | Procedure and assertion | Result |
+| --- | --- | --- |
+| Upgrade installation | Install over 2.8.3; verify existing configuration bytes; then install the fixed candidate packages | Passed on all three platforms |
+| Device pairing | Pair every platform combination through installed daemon RPC; require each client to see both other devices online | Passed, three pairings |
+| Text clipboard | Three rounds with each OS as the source, including Chinese, newlines and emoji; compare destination OS clipboards and history | Passed, all six directed OS pairs |
+| Final Mac build recheck | After installing the final clean Mac DMG, copy text from each of the three platforms again | Passed on both destinations for every source |
+| PNG clipboard | Copy a native image from each platform; decode received PNGs and compare RGBA pixels | Passed, all six directions |
+| File/folder clipboard | Copy generated fixtures with Unicode names, an empty file and a nested 1 MiB payload; compare received file SHA-256 manifests | Passed, all six directions |
+| Send Files | Send a file and nested directory in each directed OS pair; require sender and receiver completion and exact file hashes | Passed, six transfers |
+| Read-only JSON CLI | Repeat the five read-only query forms three times per platform; compare configuration before and after | Passed; configuration unchanged |
+| Rejected CLI mutation | Attempt JSON `config set`; require nonzero exit, structured error and unchanged configuration | Passed on all three platforms |
+| History actions | Favorite, Unicode alias, full text detail and copy-back through installed daemon RPC; verify actual clipboard | Passed on all three platforms |
+| Quick paste | Check installed session version, registered `alt+v`, no hotkey error and paste capability; check again after daemon recovery | Passed on all three platforms |
+| GUI | Launch installed applications; inspect history/settings and online indicators; inspect Mac/Linux About views | Passed within the views exercised |
+| Background restart | Restart installed daemon; verify new process, same device identity, paired peer IDs, config and retained history; reconnect all three clients | Passed on all three platforms |
+| Linux supervision | Kill supervised daemon child; require a replacement child, peer reconnection and quick-paste reconnection | Passed |
+
+These are checks of concrete workflows. They are not a claim that every GUI
+control, file size, clipboard format or operating system version was tested.
+History actions and file sending were exercised through the installed daemon
+API; not every corresponding GUI button was clicked.
+
+The Windows silent installer initially encountered a running resident process.
+Stopping that process and rerunning with `/FORCECLOSEAPPLICATIONS` succeeded.
+The final fixed-package installer log reports successful installation and no
+restart requirement. One initial Send Files attempt correctly rejected a
+nonexistent destination (`dest_unavailable`); after creating the fixture receive
+directories, all six transfers completed.
+
+## Official signaling and relay checks
+
+An additional isolated `envcheck` executable built from the candidate source
+exercised the transport path with generated fixtures. It is a transport test,
+separate from the installed GUI/clipboard tests above.
+
+| Pair | Required path | Checks | Result |
+| --- | --- | --- | --- |
+| Mac ↔ Linux | Official signaling, direct connection | Multilingual text, image, 1 MiB file, both directions, peer checksum acknowledgments | Passed |
+| Windows ↔ Linux | Official signaling, direct connection | Same checks | Passed |
+| Mac ↔ Windows | Forced official relay | Same checks | Passed |
+
+The final relay run established the relay path after approximately 26 seconds.
+The VM and host tests share one physical machine/network. This does not cover
+every real-world firewall or carrier network. The CI NAT laboratory provides
+additional automated network coverage.
+
+## Issue found during repeated testing
+
+An earlier CI run, [41769590793](https://github.com/baiyuze/pasteferry/actions/runs/41769590793),
+failed `TestAddFriendViaServer` in both Linux jobs. Ten local repetitions could
+pass, while a longer 50-repetition Linux run reproduced the failure.
+
+A delayed pairing-purpose reply from a preceding device-pairing attempt could
+mark a pending attempt as already evaluated. A later friend/device purpose
+mismatch was then ignored. Commit `53ee171d` changes `evaluateIntent` to verify
+that the pending entry is still current, accept later mismatches even after an
+earlier matching reply, and close the purpose notification channel only once.
+
+The deterministic regression test
+`TestPairingRejectsFriendIntentAfterEarlierDeviceIntent` failed before the fix
+and passed afterward. Verification included:
+
+- Targeted macOS race tests, 20 repetitions.
+- The complete macOS peers package.
+- Linux targeted friend-pairing and deterministic regression tests, 100 repetitions.
+- The complete nine-job CI run for the fixed source commit.
+- The installed cross-platform workflows and recovery checks listed above.
+
+## Final package verification
+
+The local `release/` directory contains 14 packages plus `SHA256SUMS`. It combines
+the fixed CI Windows/Linux/Android artifacts with the locally built clean Mac
+DMGs and server packages. It has not been uploaded as a new release.
+
+All three final Mac DMGs were mounted and checked for version 2.9.0,
+`codesign --verify --deep --strict`, and the intended architectures of the GUI,
+CLI, daemon and picker:
+
+| DMG | Architectures |
+| --- | --- |
+| `PasteFerry-mac-intel.dmg` | x86_64 |
+| `PasteFerry-mac-apple-silicon.dmg` | arm64 |
+| `PasteFerry.dmg` | x86_64 and arm64 |
+
+The app, CLI, daemon and picker use the original certificate with SHA-1
+fingerprint `0D0DA1D5F1EEF4E7EDC2281416AFAF2A4470DA97`.
+The build could not apply Finder's preferred DMG window layout; mounting and
+installation worked. This is a packaging presentation limitation.
+
+## Coverage limits
+
+- No Apple Silicon Mac was available for a native arm64 installation/runtime
+ test. Its package architectures and signatures were checked.
+- Linux arm64 built and passed its native CI tests. No local arm64 Linux VM
+ installation was performed.
+- Linux installed GUI/clipboard tests used X11/Xvfb. An interactive Wayland
+ desktop regression was not performed.
+- Android CI build, compatibility tests and API checks passed. The downloaded
+ APK was not installed on an Android device during this validation.
+- Quick-paste session/hotkey readiness and reconnection were verified; this
+ does not assert automatic pasting into every possible foreground application.
+- Production auto-update application was not performed, because release and
+ update publication are explicitly paused.
+
+## Environment restoration and evidence
+
+QA data was isolated from the user's retained data. Windows and Mac original
+data directories were held intact, then restored; Linux's normal data directory
+was left in place while tests used separate XDG directories. Original device
+identity, config and database hashes were checked at the restoration swap.
+Original startup entries were retained/restored. The 2.8.3 applications/packages
+were restored after testing.
+
+Mac's saved clipboard snapshot was restored. The Windows snapshot was taken
+during this extended validation and may already contain an earlier QA item; it
+is not evidence of preserving the user's clipboard from before the entire
+conversation.
+
+Local private evidence is retained under
+`~/Library/Caches/PasteFerryInstallQA20261104/validation-results-53ee171/`.
+It includes package verification, restart/quick-paste results, build logs,
+transport logs, installation/restoration evidence and screenshots. Screenshots
+and user data are not committed to the repository.
+
+The tested code commit remains `53ee171d`; adding this report does not change
+the application binaries covered by the validation.