github kernalix7/winpodx v0.4.4

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

[0.4.4] - 2026-05-10

Patch release. Restores real-time pod wait-ready --logs output that was inadvertently buffered in v0.4.3, plus the half-uninstalled-state self-heal, the cachyos rotation/sync-password agent-first fix, the codec flag allowlist correction, the --extra-args escape hatch, the btrfs warning suppression, and dormant Phase 1 foundations for the agent-first install + reverse-open initiatives.

Fixed

  • install.sh's pod wait-ready --logs output flows live again. v0.4.3 piped the wait-ready invocation through tee to capture stderr for the half-uninstalled-state diagnostic, which had the unrelated side effect of flipping Python's stdout from line-buffered (terminal) to 4 KB-block-buffered (pipe). All [1/3] container ..., [container] ..., [2/3] RDP, [3/3] activation lines silently accumulated in the buffer and flushed in one batch when wait-ready exited — a fresh-install user saw nothing for the entire ISO download, then a wall of text at the end. install.sh now prepends PYTHONUNBUFFERED=1 to the wait-ready call, which forces line-buffered stdout regardless of pipe presence. The tee-captured file contents are unchanged, so the no such container discrimination keeps working. Reported during smoke testing on 2026-05-10.

  • Half-uninstalled state where config exists but the container is gone now self-heals on winpodx setup --non-interactive (called by install.sh). Previously a non-purge uninstall.sh (which strips winpodx files but should keep the container) followed by a re-run of install.sh would print Existing config found, skipping setup. and proceed straight to pod wait-ready, which then exploded with Error: no container with name or ID "winpodx-windows" found: no such container because the container had also been wiped (either by the user picking --purge interactively without realising, or by some external cleanup that took winpodx's container alongside the rest). The only recovery path was a full --purge reinstall, which a user shouldn't have to figure out from a stack trace. Setup now detects the missing-container state in the non-interactive existing-config branch — when cfg.pod.backend in ("podman","docker"), pod_status reports anything other than RUNNING/PAUSED/STARTING, AND a direct <backend> ps -a probe doesn't find cfg.pod.container_name in its output — and runs ensure_ready(cfg) to recreate the container from the existing compose.yaml idempotently. install.sh's pod wait-ready failure path now also discriminates on stderr: if the captured output contains no such container it prints a clear "container is missing — likely from a partial uninstall" hint with the exact --purge recovery commands instead of the generic 60-minute-timeout message that previously masked the real cause.

  • winpodx rotate-password and winpodx pod sync-password now try the in-guest agent first and fall back to FreeRDP RemoteApp on their own. On cachyos, xfreerdp3's bidirectional drive redirect is broken for the headless RAIL session winpodx uses for run_in_windows: the script runs on the guest, but the result file written to \tsclient\home\...\windows-exec\ never surfaces back to the host, so both _change_windows_password (auto-rotation + the explicit rotate-password command) and the sync-password recovery path would block until their 45 s timeout and report a channel failure. Same code paths work on openSUSE Tumbleweed where the redirect is healthy, which is why this was missed for so long. sync-password is the more critical of the two — it's the rescue command users reach for when rotation has already failed and cfg.rdp.password no longer matches Windows; if it also hangs, there's no exit. Both core/rotation/_change_windows_password and cli/pod/_sync_password now call dispatch(cfg, prefer="agent") first; if the agent isn't installed yet (TransportUnavailable) they fall back to the FreeRDP path exactly as before, and an agent auth failure (TransportAuthError) is reported without a fallback because that signals config drift, not a transient channel state. As a bonus, when the agent is reachable sync-password no longer needs to prompt for a recovery password at all — the agent uses bearer-token auth, so a user who can't remember their original install.bat password is no longer locked out. The pre-rotation _ROTATION_PENDING_MARKER recovery contract is unchanged — it still triggers on any mid-rotation disconnect regardless of which transport ran. Supersedes docs/TRANSPORT_ABC.md rule #6 ("NEVER use Transport for password rotation"); the rule's two original arguments — needing the OLD password to authenticate FreeRDP, and not exposing the NEW password to the agent process memory — both no longer hold (AgentTransport authenticates via bearer token; both transports expose the new password equally via PowerShell argv and net user argv on the guest, with one in-memory HTTP buffer on the agent path vs one on-disk script file on the FreeRDP path).

  • Removed invalid OPTIONAL-typed codec flags from the _BARE_FLAGS allowlist (+/-gfx-h264, +/-rfx, +/-nsc, +/-jpeg, +/-avc444). Hours after the v0.4.3 stack landed, xiyeming's first test of the new escape hatch (winpodx app run notepad-exe --extra-args="-gfx-h264") failed at FreeRDP's own cmdline parser with [ERROR][com.winpr.commandline]: Failed at index 15: Unexpected keyword. Root cause: FreeRDP 3.x splits flags into COMMAND_LINE_VALUE_BOOL (genuine +/-name toggles) vs COMMAND_LINE_VALUE_OPTIONAL (only /name:value accepted) — the codec flags above are all OPTIONAL, not BOOL, so bare-toggle syntax was always going to fail. The original allowlist patch shipped them as bare anyway, which let unsafe-looking input pass winpodx's filter only for FreeRDP itself to reject with a confusing log line. Now those forms are dropped at the filter layer with a clear Blocked unsafe extra_flag warning, and the GUI tooltip / CLI help text recommend the correct workaround syntax: --extra-args="/gfx:RFX" (force RemoteFX, skips H.264 negotiation entirely — already accepted by the existing /gfx value-regex). Genuine BOOL toggles (+/-gfx-progressive, +/-gfx-thin-client, +/-gfx-small-cache, +/-wallpaper, etc.) keep working as before.

Added

  • Agent-first install Phase 1 foundations — host-side state model, config schema, redactor, JSON Schema, CLI stubs. First of five phases rolling out the agent-first install architecture described in docs/design/AGENT_FIRST_INSTALL_DESIGN.md (PR #144). All foundational code; zero behaviour change while cfg.install.agent_first = False (default). New modules: (1) core/install_state.py — GuestInstallStep / GuestInstallState dataclasses and fetch_install_state(cfg) that reads C:\winpodx\install-state\*.done markers via the agent and falls back to a $XDG_STATE_HOME/winpodx/last_install_state.json cache when the agent is unreachable, never raises. (2) core/agent_install_state.py — atomic marker file primitives (atomic_write_marker, read_marker, list_completed_steps), a RetryCounter class wrapping retry_counts.json with corruption-tolerant ACID updates, and the install-failure redactor (redact_log_line / redact_payload) that strips net user <user> <pw> argv, Authorization: Bearer ... headers, password= / token= / apikey= query-style patterns, and base64 blobs > 40 chars before they ever reach disk via write_install_failure. (3) core/config.py extended with InstallConfig (agent_first, wait_ready_stage2_secs, wait_ready_stage3_secs, auto_resume, watchdog_max_respawns, watchdog_probe_debounce_count, watchdog_probe_debounce_secs) — defensive __post_init__ clamps every numeric range and coerces malformed TOML to safe defaults without raising. (4) cli/pod_install_status.py + cli/pod_install_resume.py — argparse stubs wired into winpodx pod's subcommand router with the full Phase-3 flag surface (--json, --no-color, --logs, --non-interactive for status; --non-interactive, --yes/-y, --force for resume), each printing "Phase 3 implementation pending" and exiting 0. (5) docs/design/install_failure.schema.json — JSON Schema draft-07 with additionalProperties: false, slug-shape failed_step / error_class, capped string lengths, and a 50-line last_log_lines cap. +95 new tests across test_install_config.py (17), test_install_state.py (22), test_agent_install_state.py (32 incl. a Hypothesis property test asserting the redactor's round-trip invariant — for any random string input, the output never contains a substring matching the redaction patterns), test_install_cli_stubs.py (23). Test count: 937 passed, 1 skipped (was 842 / 2). Phases 2 (install.bat refactor as state machine), 3 (host-side wait-ready 5-stage + install-status / install-resume implementations + GUI integration), 4 (default flip to agent_first = True), and 5 (legacy code path removal) are deferred.

  • Reverse-open Phase 1 foundations — src/winpodx/reverse_open/ module skeleton (paths, config, mime, seen_uuids). First of four phases rolling out the guest→host file-open path described in docs/design/REVERSE_OPEN_DESIGN.md (#48). Four foundation modules land with no behaviour change for existing users: (1) paths.py translates UNC paths from the guest's \\tsclient\... namespace into POSIX paths under the configured share roots, with a TOCTOU-safe safe_open_unc atomic context manager (rewritten from the original two-function validate-then-open API after security review caught a swap window where a symlink could be substituted between the validate call and the open call — the new shape opens with O_NOFOLLOW and validates the realpath against the allowed roots while still holding the fd, so there is no window an attacker can race); (2) config.py defines the ReverseOpenConfig schema with a baked-in dangerous-app denylist (cmd/powershell/wscript/etc.) and cfg.reverse_open.enabled = False default — this PR adds zero user-visible behaviour change; (3) mime.py ships a curated 86-entry MIME→extension mapping covering the file types the guest is most likely to hand back, with a runtime fallback to xdg.Mime for anything outside the curated table; (4) seen_uuids.py is a persistent ring buffer of recently-handled request UUIDs for replay defence — capped size with LRU eviction, atomic write via tmp+rename so a crash mid-update can't corrupt the file. +154 tests across 4 new test modules, including a hypothesis property test covering paths.translate_unc_to_posix traversal invariants (random component sequences, mixed separators, encoded .., percent-encoded null bytes — all must either resolve inside an allowed root or raise). Test count: 814 passed, 2 skipped (was 660). Phase 2 (transport), Phase 3 (host dispatcher), and Phase 4 (guest agent integration) are deferred. References #48.

  • winpodx app run --extra-args per-launch FreeRDP override + GUI Settings → Extra FreeRDP args. Diagnostic / workaround escape hatch for distro builds that ship a broken xfreerdp3. Per-launch --extra-args is appended AFTER cfg.rdp.extra_flags so a one-shot debug flag wins over the global default; both paths run through the same _filter_extra_flags allowlist so the new entry point can't smuggle anything unsafe. The Settings page in the GUI now has an "Extra FreeRDP args" input bound to cfg.rdp.extra_flags, with placeholder + tooltip listing the most useful toggles. The allowlist itself was expanded with the codec / cache / RAIL toggle pack — +/-gfx-h264, +/-gfx-progressive, +/-gfx-thin-client, +/-gfx-small-cache, +/-nsc, +/-jpeg, +/-avc444, +/-wallpaper, +/-themes, +/-decorations, +/-grab-keyboard, +/-grab-mouse, +/-mouse-relative, +/-async-update, +/-async-channels, +/-auto-reconnect, +/-bitmap-cache, +/-offscreen-cache, +/-glyph-cache — without these in the allowlist they were silently dropped before reaching xfreerdp3. Critical near-term use case: -gfx-h264 is the workaround for cachyos's xfreerdp3 build (WITH_VAAPI_H264_ENCODING=ON flagged experimental by FreeRDP itself), where xiyeming hit silent RemoteApp failure during RAIL post_connect — now they can set extra_flags = "-gfx-h264" in winpodx.toml or via the GUI to force RemoteFX fallback while we wait for winpodx app run notepad-exe --extra-args="-gfx-h264" to confirm the hypothesis.

Changed

  • Suppress dockur's cosmetic "you are using the BTRFS filesystem for /storage" warning in winpodx pod wait-ready --logs. dockur's proc.sh fires this warning unconditionally on every btrfs host based purely on df --output=fstype, without checking whether NoCoW (chattr +C) has been applied. v0.4.3 ships per-user bind-mount + auto chattr +C migration, so on a post-migration host the warning is a false positive — the actual fragmentation signal (COW (copy on write) is not disabled for disk image file ...) is gone. The streamed log line is now rewritten to (btrfs warning suppressed: NoCoW bind mount in use) when cfg.pod.storage_path is set, so install.sh output stops looking alarming. Legacy users still on the named volume (storage_path = "") keep seeing the original warning so they're prompted to run winpodx setup --migrate-storage.

Don't miss a new winpodx release

NewReleases is sending notifications on new releases.