6.5 KiB
Windows GUI and desktop workflows
Contents
- Defaults and limits
- Launch an application and retain its lifetime
- Verify a real window
- Diagnose missing dialogs
Defaults and limits
Use the established rv deployment prefix from deployment.md.
Inspect the client's version and effective execution identity; older builds
may lack these defaults. With the interactive-desktop fix, active-user,
active-user-elevated, and active-system launch the helper and shell on that
session's winsta0\default. The helper checks actual window-station/desktop
names and GUI access under its selected token before preparing user code.
Desktop ACLs are not broadened. The command console is headless and GUI startup
uses normal visibility. No extra per-request desktop/window flags are needed.
Normal requests use the active user's non-elevated token when a usable session
exists. Request --elevated only when the operation needs it, and inspect the
effective context: active-system uses SYSTEM, including its profile/network
identity; local-system/local-service in Session 0 cannot display on the user's
desktop. The tray need not be running and does not own execution.
A window can appear behind other windows, remain on Default until the user unlocks, or stay with the original session after a session switch. RVBox does not force foreground focus, switch secure desktops, or manufacture application dialogs. A program may run silently, fail initialization, or delegate to an existing process. Successful admission/process exit is not visible-task success.
The target token supplies base environment/profile identity; request environment
overrides and explicit CWD still apply. Do not assume the CWD is the user's home
or that a running Explorer's private environment is cloned. PowerShell wrappers
retain -NoLogo -NoProfile -NonInteractive -File and normal execution-policy
checks. -NonInteractive rejects host Read-Host/confirmation prompts; it does
not prohibit a native application or WinForms script from displaying its UI.
There is captured stdin/stdout/stderr, not an interactive terminal/PTY.
Launch an application and retain its lifetime
For an application RVBox should supervise until it exits:
rv run --background --shell cmd CLIENT \
'start "" /wait "C:\Program Files\Example\Example.exe"'
The empty quoted argument is cmd's window title; /wait keeps the command
alive for the launched application. Background admission avoids keeping a
CLI follow open beyond its 30-second deadline. Save the issue UUID and inspect
the application's window plus rv stat CLIENT ISSUE_UUID.
RVBox owns a non-breakaway Job, including ordinary descendants. An asynchronous
start can let the root shell exit and close its Job, terminating still-owned
children. Use /wait for supervised GUI applications. A single-instance app or
Explorer may hand off to an existing process outside that Job; /wait then
tracks only the new launcher, not the existing process or its windows. Killing
the command is not a general way to close delegated windows.
To open an existing user's folder through Explorer:
rv run --shell cmd CLIENT 'start "" "%USERPROFILE%\Pictures"'
Confirm the folder actually opened. Direct explorer.exe PATH can return 1
after successfully handing off; preserve that raw result instead of globally
treating 1 as success. See Explorer troubleshooting.
Verify a real window
The bundled windows_gui_probe.ps1 uses inbox Windows PowerShell/.NET and installs nothing. Place it at a readable target Windows path, then launch it through the same RVBox route being diagnosed:
rv run --shell cmd CLIENT \
'powershell.exe -NoLogo -NoProfile -STA -ExecutionPolicy Bypass -File "C:\Users\Public\RVBoxGUIProbe.ps1" -Seconds 8'
This deliberate diagnostic invocation sets process-only execution policy; it
does not change registry/Group Policy. Keep managed-policy failures explicit.
The script opens a small window for 1–25 seconds and emits JSON containing the
actual session/user SID, station, desktop, input desktop, observed window
visibility, console visibility, and startup show state. Require remote success,
window_observed=true, WinSta0/Default, matching intended session, input
desktop Default, and console_window_visible=false. Confirm the window on
the desktop when doing visual acceptance. Exit 2 means at least one of those
checks failed; read the JSON, including input_desktop_error for locked or
inaccessible input desktops. The SID is diagnostic output, not a stored skill
credential. The -ConsoleOnly mode instead waits for CTRL_BREAK and reports
RVBOX_CONSOLE_READY / RVBOX_CTRL_BREAK_OBSERVED; reserve it for controlled
TERM testing against the owned command.
Diagnose missing dialogs
- Verify selected session, effective SID/context, requested elevation, and
launch rejection. Matching user/session alone does not prove correct desktop
placement. A
launcher preparation faileddesktop/access message identifies a pre-launch failure; correct the account/session/access prerequisites rather than granting broad desktop permissions or silently changing identities. - Unlock and view the intended user's desktop. Run the probe through RVBox; distinguish failure to create/show a window from an unfocused/background one.
- If the probe succeeds, inspect the application's actual command line, unattended flags, elevation requirement, logs, policy/initialization errors, and single-instance handoff. For uninstallers, verify executable/registry removal independently; a completed wrapper or missing prompt proves neither.
- Check shell policy, CWD, environment and quoting. Use uploaded scripts for complex commands. Test the exact invocation locally as the same user when needed; do not silently change privileges or resubmit uncertain side effects.
- For an ordinary GUI app killed immediately, inspect
/wait, root-shell exit, Job termination and handoff. Keep request/issue IDs and failure output before retrying. Retest with the fixed client; compare actual windows, not just PIDs.
Windows references: interactive process creation, console allocation semantics, foreground restrictions.