Windows Tauri

6. Unix-only APIs and native crates must still build on Windows

The dev box cannot cross-compile the Windows bundle — git2, font-kit, portable-pty, and crypto crates all pull native code, so only windows-build.yml on a Windows runner catches a break. Two recurring traps:

• A #[cfg(unix)] API used unconditionally fails to compile on Windows (E0599). AgentClient::connect_env (unix socket) needed a Windows arm (connect_named_pipe / connect_pageant) and the shared loop extracted into a generic helper (#52, #54). When an API has no Windows form, cfg-gate it and provide a Windows path or a clean error — do not leave the call unconditional.
• A cfg-split command warns on Windows even when it compiles. set_native_menu (src-tauri/src/modules/menu.rs) keeps its NativeMenuModel structs and its app param only for the #[cfg(target_os = "macos")] arm; on Windows they are dead code / an unused variable, so windows-check.yml's cargo check -D warnings fails the PR (#190 shipped the warning, #191 added the gate). Guard the mac-only bits: #[cfg_attr(not(target_os = "macos"), allow(dead_code))] on the types, #[cfg_attr(not(target_os = "macos"), allow(unused_variables))] on the fn. Prefer these cfg-scoped allows over an _-prefix, which would also hide the value from the macOS arm that needs it.
• A new native crate may need a Windows toolchain. aws-lc-sys needs NASM; switching russh to its ring backend removed that so cargo build works on a stock Windows MSVC setup (#75). Before adding a crate with a -sys dependency, check its Windows build requirements.

windows-check.yml now compiles the Windows target on every PR with warnings-as-errors, so a broken cfg-gate or a Windows-only warning fails the PR automatically — no manual step. For anything cargo check cannot prove (bundling, native-crate link, runtime), still kick windows-build.yml (workflow_dispatch) and confirm it is green before merging.

7. No Windows backend: skip, do not crash or spin

Some capabilities have no Windows implementation and must degrade cleanly, not error or busy-loop:

• pty foreground process: portable-pty exposes none on Windows, so detecting that claude/codex is running (for image auto-attach) is mac/Linux only (#75).
• process cwd: no /proc, no lsof, so read_process_cwd returns None. The frontend must not keep polling pty_cwd every 1.2s per terminal into a dead backend — guard the poll off on Windows (#105), or drive cwd from OSC 7 shell integration instead (#115).

Rule: when a feature's backend is a no-op on Windows, gate the frontend caller too, so it does not fire pointless IPC or show a broken control.

8. Frontend: gate on IS_WINDOWS, not just IS_MAC

Platform branches written as "mac vs everything else" silently break Windows. Terminal paste was suppressed on all platforms and the smart-paste shortcut was IS_MAC-only, so Windows had no paste at all (#75). Window decorations are native on Windows and need a custom TitleBar (#67). Use IS_WINDOWS from src/lib/platform.ts and give Windows its own explicit branch.

9. Window creation deadlocks in a sync command

WebviewWindowBuilder::build() (and WindowBuilder/WebviewBuilder) deadlocks on Windows when called from a synchronous #[tauri::command] or event handler. WebView2 dispatches window creation as a message to the main event loop and blocks on the reply; a sync command runs on that same thread, so it waits on itself (upstream wry#583, called out in the Tauri builder docs). macOS/WKWebView has no such constraint, so this never reproduces in dev on the mac — only on a user's Windows machine.

The symptom is nasty and non-obvious: the OS window shell appears painted only with the builder's background_color (a blank dark rectangle — the webview never initializes), decorations(false) means no native frame and the React TitleBar never renders so there is no close button, and the wedged event loop kills every subsequent IPC-based shortcut app-wide. That was #208: a user pressing Ctrl+N (wired to the open_new_window command) got an unclosable blank window and a dead app.

The fix is what the Tauri docs prescribe — make the command async so it runs off the main thread — plus spawn_blocking so the blocking main-thread round-trips (build(), inner_size(), scale_factor()) stay off the shared async worker pool, matching how every other async command here handles blocking work:

#[tauri::command]
async fn open_new_window(app: tauri::AppHandle) -> Result<(), String> {
    tauri::async_runtime::spawn_blocking(move || modules::menu::create_new_window(&app))
        .await
        .map_err(|e| e.to_string())?
        .map_err(|e| e.to_string())
}

Any command that builds a window or webview must follow this shape. Note that async commands can now run concurrently, so window-label allocation (next_window_label) can race across two rapid invocations — benign here (one window opens, the duplicate build() errors), but worth knowing if label collisions ever matter.

Release checklist (Windows)

The release is two-phase: scripts/release.sh runs on the mac (build, notarize, latest.json, gh release create with the v* tag), and the tag push triggers windows-build.yml, which builds on Windows, uploads .exe/.msi, and merges the windows-x86_64 platform into latest.json.

• Windows CI is green. windows-check.yml gates compilation per PR, but windows-build.yml is the only thing that bundles and links the actual Windows binary; a red build means the release ships no working Windows binary.
• The tagged commit still has a populated CHANGELOG-NEXT.md. windows-build.yml re-patches latest.json's notes from the changelog at the tagged commit. If the changelog was already archived/emptied, notes (macOS included) get wiped (#43). Do not point the tag at a master HEAD whose changelog was cleared.
• Do not hand-patch latest.json before CI finishes — tauri-action rewrites it mid-run and would clobber your patch. Patch only after CI, via node scripts/patchManifestNotes.mjs <manifest> <changelog> then gh release upload --clobber.
• Functional-test on a real Windows host. CI proves it compiles and bundles, not that it works. The recurring gap in this repo's PRs is the unchecked "Windows real verification" box. Use the CI artifact from the branch to smoke-test paste, launcher, terminal cwd, and the updater dialog.

How to actually verify on Windows

• Dev never shows console-flash / spawn-cost bugs — a debug build owns a console. Reproduce these only in a release build (or the CI artifact).
• No Windows box? The per-PR windows-check.yml already gates compilation (warnings included); to test behavior, push the branch and run windows-build.yml via workflow_dispatch, then download the artifact.
• Keep platform logic in pure functions parameterized by windows: bool (see pr/mod.rs) so the Windows path has real unit tests that run on the mac, instead of #[cfg(windows)] code that is never executed until a user hits it.