[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'spod wait-ready --logsoutput flows live again. v0.4.3 piped the wait-ready invocation throughteeto 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] activationlines 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.shnow prependsPYTHONUNBUFFERED=1to the wait-ready call, which forces line-buffered stdout regardless of pipe presence. Thetee-captured file contents are unchanged, so theno such containerdiscrimination 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 byinstall.sh). Previously a non-purgeuninstall.sh(which strips winpodx files but should keep the container) followed by a re-run ofinstall.shwould printExisting config found, skipping setup.and proceed straight topod wait-ready, which then exploded withError: no container with name or ID "winpodx-windows" found: no such containerbecause the container had also been wiped (either by the user picking--purgeinteractively without realising, or by some external cleanup that took winpodx's container alongside the rest). The only recovery path was a full--purgereinstall, 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 — whencfg.pod.backend in ("podman","docker"),pod_statusreports anything other than RUNNING/PAUSED/STARTING, AND a direct<backend> ps -aprobe doesn't findcfg.pod.container_namein its output — and runsensure_ready(cfg)to recreate the container from the existingcompose.yamlidempotently.install.sh'spod wait-readyfailure path now also discriminates on stderr: if the captured output containsno such containerit prints a clear "container is missing — likely from a partial uninstall" hint with the exact--purgerecovery commands instead of the generic 60-minute-timeout message that previously masked the real cause. -
winpodx rotate-passwordandwinpodx pod sync-passwordnow 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 forrun_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 explicitrotate-passwordcommand) and thesync-passwordrecovery 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-passwordis 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. Bothcore/rotation/_change_windows_passwordandcli/pod/_sync_passwordnow calldispatch(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 reachablesync-passwordno 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_MARKERrecovery contract is unchanged — it still triggers on any mid-rotation disconnect regardless of which transport ran. Supersedesdocs/TRANSPORT_ABC.mdrule #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 andnet userargv 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_FLAGSallowlist (+/-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 intoCOMMAND_LINE_VALUE_BOOL(genuine+/-nametoggles) vsCOMMAND_LINE_VALUE_OPTIONAL(only/name:valueaccepted) — 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 clearBlocked unsafe extra_flagwarning, 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/gfxvalue-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 whilecfg.install.agent_first = False(default). New modules: (1)core/install_state.py—GuestInstallStep/GuestInstallStatedataclasses andfetch_install_state(cfg)that readsC:\winpodx\install-state\*.donemarkers via the agent and falls back to a$XDG_STATE_HOME/winpodx/last_install_state.jsoncache 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), aRetryCounterclass wrappingretry_counts.jsonwith corruption-tolerant ACID updates, and the install-failure redactor (redact_log_line/redact_payload) that stripsnet user <user> <pw>argv,Authorization: Bearer ...headers,password=/token=/apikey=query-style patterns, and base64 blobs > 40 chars before they ever reach disk viawrite_install_failure. (3)core/config.pyextended withInstallConfig(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 intowinpodx pod's subcommand router with the full Phase-3 flag surface (--json,--no-color,--logs,--non-interactivefor status;--non-interactive,--yes/-y,--forcefor resume), each printing "Phase 3 implementation pending" and exiting 0. (5)docs/design/install_failure.schema.json— JSON Schema draft-07 withadditionalProperties: false, slug-shapefailed_step/error_class, capped string lengths, and a 50-linelast_log_linescap. +95 new tests acrosstest_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-sidewait-ready5-stage +install-status/install-resumeimplementations + GUI integration), 4 (default flip toagent_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 indocs/design/REVERSE_OPEN_DESIGN.md(#48). Four foundation modules land with no behaviour change for existing users: (1)paths.pytranslates UNC paths from the guest's\\tsclient\...namespace into POSIX paths under the configured share roots, with a TOCTOU-safesafe_open_uncatomic 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 withO_NOFOLLOWand validates the realpath against the allowed roots while still holding the fd, so there is no window an attacker can race); (2)config.pydefines theReverseOpenConfigschema with a baked-in dangerous-app denylist (cmd/powershell/wscript/etc.) andcfg.reverse_open.enabled = Falsedefault — this PR adds zero user-visible behaviour change; (3)mime.pyships a curated 86-entry MIME→extension mapping covering the file types the guest is most likely to hand back, with a runtime fallback toxdg.Mimefor anything outside the curated table; (4)seen_uuids.pyis 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 coveringpaths.translate_unc_to_posixtraversal 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-argsper-launch FreeRDP override + GUI Settings → Extra FreeRDP args. Diagnostic / workaround escape hatch for distro builds that ship a broken xfreerdp3. Per-launch--extra-argsis appended AFTERcfg.rdp.extra_flagsso a one-shot debug flag wins over the global default; both paths run through the same_filter_extra_flagsallowlist so the new entry point can't smuggle anything unsafe. The Settings page in the GUI now has an "Extra FreeRDP args" input bound tocfg.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-h264is the workaround for cachyos's xfreerdp3 build (WITH_VAAPI_H264_ENCODING=ONflagged experimental by FreeRDP itself), where xiyeming hit silent RemoteApp failure during RAIL post_connect — now they can setextra_flags = "-gfx-h264"in winpodx.toml or via the GUI to force RemoteFX fallback while we wait forwinpodx 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'sproc.shfires this warning unconditionally on every btrfs host based purely ondf --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)whencfg.pod.storage_pathis 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 runwinpodx setup --migrate-storage.