github kernalix7/winpodx v0.4.0rc1

latest releases: v0.12.1, REL-v0.12.1, v0.12.0...
pre-release6 months ago

[0.4.0] - 2026-05-03

A significant stability + UX release focused on the install / migrate paths. Container recreates are no longer triggered by dockur's :latest push cadence (image is SHA-pinned), every PowerShell console flash on app launch and agent autostart has been eliminated, fresh installs honestly wait for Windows to be ready, and multi-session activation is now hands-free via apply-fixes / migrate. SELinux-enforcing systems (Fedora) work out of the box. RTM-suffixed pods (0.3.0-RTM1) migrate cleanly. The winpodx app refresh discovery race is closed in three layers. Contributing policy + lifecycle docs added.

Fixed

  • Discovery error classification + GUI dialog no longer mislabels session-disconnect failures as "Pod Not Running". Pre-this-fix the classifier mapped any error message containing "no result file" or "auth" to DiscoveryError(kind="pod_not_running"). That over-fired on session-side errors where the pod was very much running -- specifically ERRINFO_LOGOFF_BY_USER (0x0001000C) and ERRINFO_RPC_INITIATED_DISCONNECT (0x00010001). Both surface a "no result file written" outer message because the script never finished writing -- but they mean the FreeRDP RemoteApp session was terminated mid-call by the guest, common during multi-session activation's TermService cycle. The GUI then offered a "Start Pod" button on a perfectly running pod (kernalix7 hit this 2026-05-03 right after a fresh install). Fix: _classify_channel_error() now distinguishes three states explicitly -- transport-layer failure (connection refused / connect_transport_failed / agent unavailable) → pod_not_running; session-layer disconnect (LOGOFF / RPC_INITIATED_DISCONNECT) → new session_disconnected kind; everything else → script_failed. The GUI handler shows a "Discovery Session Disconnected" dialog with a Retry button for the new kind, instead of a misleading "Pod Not Running" / "Start Pod" prompt.
  • winpodx pod start no longer fails with lsetxattr: operation not permitted on Fedora / SELinux-enforcing systems. Three bugs chained: (1) bundle_dir() used any() for its marker check (scripts/, config/, data/) — only one had to exist for a directory to qualify as a winpodx bundle, so a stale /usr/share/winpodx/config/ skeleton (left behind after an RPM uninstall because agent_token.txt was untracked) hijacked path resolution even on a curl-only install. (2) _find_oem_dir() returned the bundle path directly; on RPM/wheel installs that's /usr/share/winpodx/config/oem/ (root-owned), and the compose template mounted it with :Z for SELinux relabeling — which fails with lsetxattr: operation not permitted because rootless Podman can't relabel root-owned files. (3) stage_token_to_oem() wrote agent_token.txt into the bundle OEM dir, so on RPM installs the runtime token landed under /usr/share/winpodx/ (untracked by RPM, survives rpm -e) — feeding back into bug 1. Fixes: _find_oem_dir() now copies the bundle OEM tree into ~/.config/winpodx/oem/ (user-owned, :Z-relabel-able) and returns that path; the agent token writes there too via the same indirection. bundle_dir() marker check changed from any() to all() so partial leftovers no longer match. (Thanks @pgarciaq — PR #95, fixes #93.)
  • install.bat now spawns the agent directly at end-of-script, not just registers it for future logons. HKCU\Run only fires once per user logon, and the autologon User session has already logged in by the time install.bat (FirstLogonCommands) executes -- so all our HKCU\Run registration was setting up was the next session's agent. The current session that install.bat runs in had no agent at all until the user (or some host RDP probe) opened a new session. install.sh's wait-ready phase 3 timed out at /health on every fresh install (kernalix7 reported OK Windows ready (17:57) with the agent-missing warning, then migrate's apply chain failed with FreeRDP rc=12 LOGOFF_BY_USER and rc=1 RPC_INITIATED_DISCONNECT errors -- consistent with running against a Windows that was healthy but had no agent). Fix: install.bat ends with a PowerShell Start-Process block that spawns the agent in this session via wscript.exe + hidden-launcher.vbs (or direct PS fallback if the wrapper didn't survive copy, with the same setup.log diagnostic as the HKCU\Run registration). Agent /health is up by the time install.bat returns -> phase 3 succeeds within seconds -> migrate's apply chain runs against a healthy agent -> no FreeRDP-fallback cascades. The HKCU\Run registration stays in place so future user logons (re-RDP after host restart, multi-session app launches) also get the agent. OEM bundle 20 -> 21.
  • check_rdp_port now does a real RDP handshake instead of just TCP-accept. dockur's QEMU slirp accepts TCP forwards on the host's mapped RDP port the moment the QEMU process launches -- before the Windows guest's TermService is anywhere near up. Pre-this-fix the helper just did socket.create_connection, so a fresh install in mid-ISO-download (or any pod that booted QEMU but hadn't brought Windows to the RDP listener yet) would report "RDP port open" the instant the container started. install.sh's wait-ready skipped past phase 2 in 0 seconds, hit phase 3 (which after PR #91 returns True with a warning when /health misses), and then ran migrate's apply chain against a Windows that wasn't there -- surfacing as a cascade of FreeRDP rc=147 / "Connection reset by peer" failures. User caught this 2026-05-02 21:53 on a fresh install where the [container] log showed Windows ISO at 7% downloaded while the host had already moved on. Fix: check_rdp_port now sends a minimal X.224 Connection Request (TPKT-wrapped) and reads back 2 bytes. A real RDP server responds with a TPKT (first byte 0x03, second byte 0x00); QEMU-forwarding-with-no-guest gets us the SYN-ACK from slirp's TCP stack but the recv times out / returns EOF. Distinguishable in ~1 second. New helper check_tcp_port exposes the old TCP-accept-only behavior for the one place that legitimately wants it (the VNC liveness check inside recover_rdp_if_needed -- VNC doesn't speak RDP, so the X.224 probe would naturally fail there).
  • wait_for_windows_responsive no longer deadlocks install.sh phase 3 when agent /health doesn't come up. Pre-this-fix the helper required BOTH an open RDP port AND agent.ps1 /health to respond before returning. Any path that left the agent dead -- HKCU\Run mis-registered, autologon mid-cycle, agent token mismatch, port-mapping blip, install.bat staging hiccup -- caused the helper to spin out the full caller-supplied timeout (often 3600 s on install.sh's winpodx pod wait-ready --timeout 3600). User reported sitting at [3/3] Waiting for Windows activation... for 30+ minutes 2026-05-02 on a fresh install where the desktop was visible via VNC. Now: stage 1 (RDP port) is required as before; stage 2 (agent /health) is best-effort, capped at min(timeout, 60s). If /health responds, return True with the agent path live. If it doesn't, return True anyway (Windows IS responsive -- host code falls back to FreeRDP RemoteApp via transport.dispatch) plus a warning log pointing at C:\winpodx\setup.log for diagnostics. Only RDP-port-never-opens returns False. Same transport.dispatch agent-first preference everywhere else, just no longer blocking on it during boot probe.
  • install.bat staging gained per-file verification + structured fallback so the "Cannot find script file" wscript dialog can no longer block fresh install. Pre-OEM-v20 install.bat copied the 5 launcher files to C:\Users\Public\winpodx\launchers\ with 2>nul suppressing any error and registered HKCU\Run\WinpodxAgent / WinpodxMedia via reg add pointing at those paths unconditionally. If the copy silently failed (network share blip mid-Sysprep, AV interference, anything), the registry entries pointed at non-existent files; on the next user logon, wscript.exe popped a "Cannot find script file" dialog that blocked the session indefinitely (kernalix7 hit this on a fresh install 2026-05-02 ~19:58). The reg add itself was also fragile: cmd-parsing of \"escaped quotes\" inside /d "..." survives but reg.exe stores literal backslash-quote pairs, and CommandLineToArgvW at logon evaluates them differently than a real quoted argument. Three-way fix: (1) per-file copy verification — each copy /Y is followed by an if exist check with the result logged to C:\winpodx\setup.log (launcher OK: / launcher FAILED: per file). (2) HKCU\Run registration moved to a single PowerShell block via Set-ItemProperty — clean .NET string storage, no cmd-quoting hell. (3) Existence-gated fallback — if hidden-launcher.vbs didn't survive copy (LAUNCHERS_OK unset), HKCU\Run is registered with the legacy direct powershell.exe -WindowStyle Hidden -File ... form. That fallback flashes a brief PS console (~50 ms) but at least starts the agent; without it the user got a blocking dialog and never saw the desktop. The same setup.log records which path was chosen so apply-fixes can probe it later. OEM bundle 19 → 20.
  • VBS files now ASCII-only — Windows Script Host no longer fails to parse them on non-en-US Windows installs. config/oem/hidden-launcher.vbs and config/oem/launch_uwp.vbs had em-dash characters in their leading comments. wscript.exe reads .vbs files with the system default codepage (e.g., CP-949 on Korean Windows). The em-dash UTF-8 byte sequence (0xE2 0x80 0x94) decodes as a multi-byte sequence ending mid-statement → "Windows Script Host" error dialog at HKCU\Run firing time → install hangs at Sysprep. Same root cause as PR #88 fixed for .ps1 files; this PR completes the audit by ASCII-ifying the .vbs files. The full set of script files (5 PS + 2 VBS) is now strict ASCII.
  • agent-respawn.ps1 legacy fallback removed. The old code had a Test-Path hidden-launcher.vbs check with an else-branch that fell back to Start-Process powershell.exe -WindowStyle Hidden -File agent.ps1 — i.e., the same broken pattern PR #58 fixed for HKCU\Run\WinpodxAgent. Post-OEM-v13 the wrapper is always staged (install.bat + _apply_vbs_launchers both push it), so the fallback only fires on filesystem corruption or a manual delete — but when it did fire, it surfaced a console flash on every apply-fixes cycle. Replaced with exit 1 if the wrapper is missing: HKCU\Run will refire (via wscript+hidden-launcher.vbs) on the next user logon and bring the agent back without the flash. No path that produces a flash remains.
  • **apply-fixes no longer cycles TermService
  • First-boot app discovery is now consistent — no more "menu populated last install, missing UWPs this install" stochasticism. Three race conditions converged on a flaky winpodx app refresh at install.sh time, and they fired independently so any one of them produced an empty / partial result while the others might pass: (1) Sysprep-just-finished AppX deployment was still running when discovery enumerated UWPs, returning a partial Get-AppxPackage view; (2) Start Menu indexer hadn't propagated all .lnk files yet; (3) install.sh runs migrate (which can cycle TermService for multi-session activation) immediately before app refresh, so the agent could be mid-respawn when discovery's /exec fired. Three layers now collapse the variance:
    • Guest-side readiness gate (scripts/windows/discover_apps.ps1): waits for AppXSvc.Status -eq 'Running' AND ProgramData Start Menu .lnk count > 0 across 3 consecutive 1 s samples (catches the StartPending → Running blip), bounded at 60 s. Logs "stable, proceeding" / "budget exceeded, proceeding with potentially partial state" to stderr so guest-side timing is visible in the apply-fixes / refresh output.
    • Host-side transport readiness (core.discovery.discover_apps): before invoking the script, polls agent /health and RDP port up to 30 s. Without it, discovery firing into a freshly-killed agent (post-multi-session-activation TermService cycle) bails with channel-failure cascade on a perfectly-good pod.
    • Host-side retry-on-empty: if the first pass returns suspiciously few apps (< 5 total OR 0 UWP — both impossible on a stock Win11 install), waits 8 s and retries once. Picks the larger result so retry never regresses.
    • Default discovery timeout bumped 120 s → 180 s to absorb the new readiness gate. Retry-on-empty is bounded (one retry max) so a stripped-down image with genuinely few apps doesn't loop.
  • apply-fixes no longer cycles TermService (and kills the agent) when rdprrap is already patched but the activation marker is stale. PR #81 made _apply_multi_session self-heal by spawning rdprrap-activate.ps1 whenever the .activation_status marker said anything other than enabled. That correctly triggered for pods with no marker (pre-OEM-v15) or a not-activated / installer-failed marker. But it also triggered for pods like kernalix7's where the marker said installer-failed from a partial OEM-time apply — yet ServiceDll had successfully been flipped to termwrap.dll anyway and multi-session was working. Re-firing activation in that state cycled TermService unnecessarily, killed the agent's RDP session, and (because HKCU\Run only fires at user logon) left the agent dead until the user opened an app. Repeat apply-fixes calls (each install.sh --main upgrade re-runs migrate's apply chain) re-killed the agent each time. Fix: before spawning the detached activator, also probe HKLM\SYSTEM\CurrentControlSet\Services\TermService\Parameters\ServiceDll. If it already matches termwrap, write enabled to the marker and return — this reconciles the stale marker so subsequent apply-fixes calls hit the fast path, and importantly does not cycle TermService.
  • HKCU\Run\WinpodxMedia no longer flashes a black PS console on every app launch. Pre-OEM-v19 install.bat registered media_monitor.ps1 (USB auto-mapping background process) with bare powershell.exe -WindowStyle Hidden ... — -WindowStyle Hidden is honored after conhost briefly allocates a console for the child, so a ~50ms black flash slipped through. With multi-session enabled, every app launch creates a new RDP session that re-fires HKCU\Run from scratch, so the user saw the flash on every single launch — visible-but-unreadable, classic Hidden-flag race. Fix: install.bat now registers the entry as wscript.exe hidden-launcher.vbs powershell.exe ... media_monitor.ps1 (same wscript+SW_HIDE wrapper that PR #58 applied to WinpodxAgent). Migrate path: _apply_vbs_launchers rewrites HKCU\Run\WinpodxMedia if an unwrapped entry exists, so existing pods get the fix on next winpodx pod apply-fixes (or winpodx migrate). Takes effect from the next RDP session/app launch — the current session's already-running media_monitor stays alive but doesn't re-spawn, so doesn't flash again. OEM bundle 18 → 19.
  • cfg.pod.image now defaults to a SHA-pinned dockur image; migrate aligns existing pods. Before this fix, cfg.pod.image defaulted to docker.io/dockurr/windows:latest (or ghcr.io/dockur/windows:latest for installs ≤ v0.3.0). Every podman-compose up re-resolved the tag against whatever dockur had pushed since. When the resolved digest changed (frequent — dockur's release cadence is daily-ish), podman-compose treated the spec as different and recreated the container. kernalix7 caught this on 2026-05-02 mid-bug: dockur had pushed a :latest containing a proc.sh substring failure (proc.sh: line 137: -1: substring expression < 0), and a routine install.sh --main upgrade triggered a full container rebuild + 7.5GB ISO redownload + Sysprep reset on a working pod that had nothing wrong with it. Pin: cfg.pod.image defaults to docker.io/dockurr/windows@sha256:20b398ab935465f97ec8ab06489f7a85a5ad58e74e036ce66cc3c9172e7dbea8 (queried from Docker Hub registry at release time and stored as DOCKUR_IMAGE_PIN in core.config). Migrate's "already current" + cross-version paths both call a new _ensure_canonical_image_pin step that rewrites cfg.pod.image + regenerates compose.yaml so existing pods land on the same canonical pin a fresh main install would write — one container recreate on the next pod start (~30 s, storage volume preserved → no ISO redownload, no Sysprep), then immune to dockur :latest churn going forward. Idempotent: re-running migrate on an already-pinned config short-circuits before any rewrite.
  • winpodx setup --update-image opt-in dockur version bump. New flag on the existing setup subcommand. Pulls docker.io/dockurr/windows:latest via the user's container backend, resolves the now-local image's repo-digest, writes it back to cfg.pod.image, and regenerates compose.yaml. Surfaces the new pin in the output so users can verify what they're locking to. Same recreate cost as the migrate path on next pod start (~30 s, volume preserved). The only path that ever pulls a fresh :latest — every other code path uses the bundled or persisted pin.

[0.3.1] - 2026-05-02

Maintenance release focused on making the v0.3.0-RTM1 → main migration path actually heal the multi-session activation gap, without forcing a container recreate. Also collapses the OEM-time and runtime rdprrap activation paths onto a single script.

Added

  • Nix flake. nix run github:kernalix7/winpodx, nix profile install github:kernalix7/winpodx, or inputs.winpodx.url = "github:kernalix7/winpodx". The wrapper bundles FreeRDP, podman / podman-compose, iproute2 and libnotify so the default podman backend works out of the box; docker and libvirt remain opt-in. A devShell exposes the same runtime tools plus ruff and mypy with src/ on PYTHONPATH. README (en + ko) gains a Nix install section. (Thanks @Mic92 — PR #65.)

Changed

  • paths.bundle_dir() — single resolver for shipped resource trees. Seven call sites previously hand-rolled __file__.parent.parent… walks with inconsistent fallbacks: discovery script lookup, OEM bundle version, OEM directory for compose mounts, VBS launcher migration, debloat script (CLI + GUI), data assets, and rdprrap version pin. Each one drifted independently — discovery already broke once with an off-by-one parent count (see #?), the OEM dir resolver missed wheel installs, the data-asset lookup couldn't find the icon under Nix. Replaced with a single bundle_dir() resolver in winpodx.utils.paths that searches $WINPODX_BUNDLE_DIR env var → source checkout → sys.prefix/share/winpodx → ~/.local/bin/winpodx-app. Each candidate must contain at least one of scripts/, config/, data/ to qualify, falling back to the source-checkout guess for stable error messages. Tests for affected helpers now monkeypatch bundle_dir directly rather than juggling HOME + sys.prefix + __file__. (Thanks @Mic92 — PR #65.)

Fixed

  • winpodx migrate no longer silently drops apply-fixes on RTM-suffixed pods (and on every cross-version upgrade past 0.1.9). Two bugs converged: (1) _version_tuple("0.3.0-RTM1") returned (0, 3) instead of (0, 3, 0) because the parser stopped at the first non-int segment (split('.') produced ['0', '3', '0-RTM1']; int('0-RTM1') raised). (2) The cross-version branch gated apply-fixes on inst_cmp < (0, 1, 9) <= cur_cmp — a 2026-Q1 back-port window that no longer makes sense now that the apply chain has grown to cover multi-session auto-activate / vbs_launchers / oem_runtime_fixes. Combined effect: a v0.3.0-RTM1 user running install.sh --main hit migrate, took the cross-version branch (because the broken tuple compare made (0,3) >= (0,3,0) false), then skipped apply-fixes (because (0,3) < (0,1,9) was also false). Their pod stayed on whatever runtime fixes RTM1 originally applied — multi-session activation included — until they ran winpodx pod apply-fixes manually. Fix: parser now extracts leading digits per segment so 0.3.0-RTM1, 0.3.0rc1, 0.3.0+dev all parse to (0, 3, 0). Cross-version gate removed; the chain is idempotent so running on a pod that's already current is a marker probe + no-op return per helper.
  • winpodx pod apply-fixes auto-activates rdprrap multi-session if it isn't already on. Multi-session is core winpodx functionality — without it the "Select a session to reconnect to" dialog appears on every multi-app launch. Pre-this-fix, the apply chain's multi_session step was a status probe only (PR #77, defensive against the inline-activation hang where mid-apply rdprrap-conf killed the agent's session and timed out /exec). PR #80 made activation safe by spawning rdprrap-activate.ps1 detached — the /exec response returns before TermService cycles — so the apply chain can now self-heal: if .activation_status reads enabled, no-op (no /exec round-trip beyond the one we're in, no disconnect, no churn); otherwise queue the detached activator. Apply chain reorders so vbs_launchers (which stages rdprrap-activate.ps1 + hidden-launcher.vbs) runs before multi_session. Cost when activation is needed: RDP sessions briefly disconnect (~10 s) while TermService cycles, then reconnect with multi-session active. This is the same one-time cost the OEM-time path pays, just deferred to migration time for pre-OEM-v17 pods.
  • winpodx pod multi-session on activates rdprrap on existing pods without a container recreate. Activation needs rdprrap-installer install plus a net stop/start TermService cycle so the patched ServiceDll is loaded — but the cycle kills every active RDP session, including the agent's own user session, so an inline /exec couldn't drive it (the agent died before the response could return). Pre-this-fix the only way an existing v0.3.0-RTM1 pod with a failed OEM-time activation could pick up the patch was to podman rm -f the container and re-Sysprep — a couple hundred MB of guest-disk churn for what is, on a working install, a 30 s registry tweak. Now: a new rdprrap-activate.ps1 script (idempotent — falls back to extracting the bundled rdprrap-*.zip from C:\OEM\ if the installer binary isn't staged, retries up to 3×, verifies the ServiceDll flip post-restart, writes the same .activation_status marker install.bat OEM v15+ writes) is staged into C:\Users\Public\winpodx\launchers\ and winpodx pod multi-session on spawns it detached via wscript+hidden-launcher.vbs (mirrors agent-respawn pattern). The /exec call returns immediately with "OK: activation queued"; the user reconnects after the brief disconnect; the agent auto-starts via HKCU\Run; subsequent winpodx pod multi-session status (now a marker probe identical to the apply-fixes status surface) confirms enabled. winpodx pod apply-fixes pushes rdprrap-activate.ps1 alongside the other VBS launchers, so existing v0.3.0-RTM1 pods get it on the next migrate without recreate. (status no longer shells out to rdprrap-conf.exe; disable still does, since disable just clears the registry patch and doesn't need TermService cycled.) install.bat's inline ~80 lines of installer-retry / TermService-cycle / ServiceDll-verify / marker logic also collapse onto the same script — install.bat now extracts the SHA-pinned bundle and delegates to rdprrap-activate.ps1 (called synchronously, without -Detached, since at OEM time the cmd.exe parent is in the local console session and TermService cycle doesn't tear it down). Single source of truth: a fix to activation behavior now benefits both OEM-time and runtime paths without drift. OEM bundle 16 → 18.
  • winpodx pod apply-fixes (and the migrate apply chain) now auto-respawns the running agent under the new wscript wrapper. The previous version of the vbs_launchers migration step staged the new wrapper into HKCU\Run but the change only took effect on the next user-session logon, so users running apply-fixes against a live pod kept seeing the autostart PS-console flash from the OLD agent instance until they manually restarted. The migration now ships a fourth helper (agent-respawn.ps1) and detaches a Start-Process wscript.exe ... agent-respawn.ps1 at the end of the apply payload. The respawn waits 3 s (giving the /exec response time to land at the host), kills the running agent.ps1 process via Win32_Process cmdline match, waits 800 ms for port 8765 to release, then starts a fresh agent under wscript+hidden-launcher.vbs. /health drops for ~3-4 s and recovers under the new wrapper. OEM bundle 13 → 14.
  • UWP launches via the new wscript / launch_uwp.ps1 path no longer silently fail. The first draft of launch_uwp.ps1 (shipped in OEM v13) tried two PowerShell forms that don't work against IApplicationActivationManager: a PS-level [InterfaceType]([Impl]::new()) cast, and dynamic method dispatch on the COM object. Both fail because the interface inherits IUnknown only, not IDispatch — PS can't auto-discover the methods, and a PS-level cast on a COM RCW doesn't carry the QueryInterface the CLR needs. Calculator, Settings, Terminal, Notepad UWP and friends were exiting 1 with the actual error logged only to %LOCALAPPDATA%\winpodx\uwp-launcher.log. Moved the activation into a small Add-Type'd C# helper class — the cast happens inside compiled C# scope where the managed cast resolves to a real COM QueryInterface. Existing pods get the fixed script via winpodx pod apply-fixes.
  • App launches no longer silently die after the CLI parent exits. Two paths could spawn a doomed FreeRDP that vanished without explanation: (1) stderr=subprocess.PIPE left the parent process holding the read end, so once the CLI exited the next stderr write SIGPIPE-killed the detached client. The launcher now writes stderr to $XDG_RUNTIME_DIR/<app>.stderr so the session outlives the parent and the tail stays inspectable; RDPSession.stderr_tail reads the last 2KB of that file lazily so existing callers keep their interface. (2) On a pure Wayland session without $DISPLAY, xfreerdp (the only client with working RAIL — sdl-freerdp lacks RAIL per FreeRDP #9078, wlfreerdp is deprecated with broken RAIL repaint) failed post-detach with "failed to open display". launch_app now refuses to spawn that combination and raises an actionable error pointing at XWayland (compositor built-in or xwayland-satellite for niri / river). (Thanks @Mic92 — PR #64.)
  • is_freerdp_pid() no longer adopts unrelated processes as live RDP sessions. The check used to look for b"freerdp" or b"xfreerdp" anywhere in /proc/<pid>/cmdline, which falsely matched scripts under paths like ~/freerdp-notes/run.sh, pytest invocations passing --deselect=test_freerdp_pid, or any tool whose arguments mentioned freerdp in passing. Stale .cproc markers tied to those PIDs never got reaped because winpodx kept thinking the unrelated process was the FreeRDP it spawned. Now parses cmdline by null bytes and compares argv[0]'s basename against the binaries find_freerdp() actually launches (xfreerdp{,3}, sdl-freerdp{,3}, plus the flatpak run com.freerdp.FreeRDP fallback). Two regression tests cover the substring-match cases that used to slip through. The downstream PID-reuse test was rewritten without bash -c "exec -a … sleep 30" so it stops failing on systems with multi-call coreutils. (Thanks @Mic92 — PR #63.)

Changed

  • Default container image switched to docker.io/dockurr/windows:latest (was ghcr.io/dockur/windows:latest). Aligns with upstream's official compose / docker run reference (the upstream README and example compose.yml both use dockurr/windows). Same image — verified by digest. Some users hit token / 4xx errors on the GitHub Container Registry path; Docker Hub serves the canonical artifact reliably. Existing installs are not auto-migrated: ~/.config/winpodx/winpodx.toml persists the resolved value, so users who already ran winpodx setup keep the old reference. To pick up the new default, either drop the image = "ghcr.io/..." line from winpodx.toml and re-run winpodx setup (regenerates compose.yaml), or edit ~/.config/winpodx/compose.yaml directly. (Thanks @Mic92 — PR #62.)
  • Zero PowerShell-window flashes — guest path goes through hidden VBS launchers and the agent transport everywhere a flash was still possible. Three fixes converge:
    • Agent autostart via hidden-launcher.vbs. HKCU\Run used to register powershell.exe -WindowStyle Hidden -File C:\OEM\agent.ps1; the Hidden flag is honored AFTER PowerShell allocates its conhost so a brief PS console flashed for ~50ms on every user logon. The new VBS wrapper is GUI-subsystem (no console of its own) and WshShell.Run with intWindowStyle=0 propagates SW_HIDE to CreateProcess so the spawned PowerShell starts windowless.
    • UWP launches via IApplicationActivationManager. The legacy /app:program:explorer.exe,cmd:shell:AppsFolder\<AUMID> invocation showed an explorer.exe RemoteApp window for ~300ms before the UWP frame appeared — that's the "PowerShell-like flash" users saw on Calculator / Settings / Terminal launches. RemoteApp now invokes wscript.exe launch_uwp.vbs <AUMID>, which calls IApplicationActivationManager::ActivateApplication directly. The UWP frame becomes the visible RemoteApp window with no transition; ~300ms faster too.
    • Remaining run_in_windows callers routed through the agent transport. core.updates, core.daemon.sync_windows_time, cli.pod.multi-session, cli.main.debloat, and the GUI Tools-page debloat handler now go through winpodx.core.windows_exec.run_via_transport, which prefers the v0.3.0 agent's /exec (CreateNoWindow=$true) and only falls back to FreeRDP RemoteApp when /health doesn't answer. Password rotation (rule #6) and the winpodx pod sync-password rescue path stay on FreeRDP intentionally — they need direct credential auth.

OEM bundle bumps to 13 (new VBS files staged into C:\Users\Public\winpodx\launchers\ so the agent can rewrite them later without admin). Migration for existing 0.3.0-RTM1 pods is automatic: the new _apply_vbs_launchers apply step pushes all three files via the agent's /exec and rewrites HKCU\Run\WinpodxAgent in one round-trip, then apply_windows_runtime_fixes chains it after multi_session. Trigger with winpodx pod apply-fixes (or winpodx migrate after upgrading) — no container recreate needed. Autostart change takes effect on the next user-session logon (or winpodx pod restart); UWP launch fix is picked up immediately by the host's next launch.

Added

  • Hybrid discovery filter — essentials always shown, system shims hidden by default. Auto-discovery on a stock Windows 11 install used to surface ~45 entries with both classes of noise: OS staples like File Explorer / Calculator / Settings missing because they aren't enumerated as Start Menu .lnk files, and system shims (LicenseManagerShellExt, WindowsPackageManagerServer, DesktopPackageMetadata, microsoft-store-server, …) cluttering the grid. The filter now ships a curated essentials allowlist (synthesizes a stub when the scan misses an essential) and a noise denylist (auto-stamps hidden = true in app.toml so the GUI grid filters them). User overrides win — toggling Hide / Show on a tile records the preference in the same TOML and survives the next discovery sweep. discover_apps.ps1 also emits the three essentials explicitly with their real Windows icons (File Explorer's icon comes from C:\Windows\explorer.exe, Calculator + Settings from their AppxManifest Square logos) so users see authentic Windows iconography rather than a generic letter avatar.
  • Win32 launch args. RDP RemoteApp builder honors a per-app args string from app.toml and forwards it as the FreeRDP cmd: field. Solves the longstanding "explorer.exe RemoteApp shows nothing" gotcha — the File Explorer essential ships args = "shell:MyComputerFolder" so launching it opens the This PC view in a normal window instead of trying to take over as the user shell. Existing apps with args = "" are unaffected.
  • Per-app .desktop descriptions. Discovery now extracts a one-line description from the guest (.lnk Comment field, exe ProductName, or UWP <VisualElements Description>) and lands it as the Comment= key in each app's .desktop file. Replaces the blanket Comment=Windows application via winpodx stamp every entry shared, so users see the actual app description in their menu / file manager tooltip. Apps without a discovered description still get the generic stamp.
  • Known-good UWP allowlist. UWP packages whose DisplayName resolves to an ms-resource: indirection that PowerShell can't expand in a non-interactive session (Calculator, Terminal, Paint, Snipping Tool, Camera, Alarms, Maps, Sound Recorder, Notepad UWP, Sticky Notes, Get Help, Your Phone, To Do, Settings) used to fall back to their dotted PackageFamilyName and get filtered out as junk by the host's UWP-dot-only check. They're now allowlisted explicitly so legitimate Microsoft.* packages aren't dropped along with the AAD/BrokerPlugin-style shims.
  • GUI Apps page "Hidden (N)" toggle. Hidden entries collapse by default; the count chip in the toolbar tells the user how many got filtered. Clicking the chip expands the grid to include them so the user can promote any that the denylist over-classified.
  • Demo screenshot in README hero. docs/images/demo.png (Windows About / Performance Monitor / PowerShell each in their own Linux window alongside the winpodx Apps grid) now ships at the top of the README so first-time visitors see what the integration looks like.

Don't miss a new winpodx release

NewReleases is sending notifications on new releases.