fix(windows): launch commands on the interactive desktop

This commit is contained in:
cabbage committed 2026-10-27 18:35:29 +00:00
1 parent 30e7bb8545
commit 8d28925e44
20 files changed
+1036 -28

No files matched your search

+2
View File
@@ -79,6 +79,8 @@ Flags precede positional arguments, including the verbs after `storage` and
historical output, resumable follow, JSON-RPC, pagination, and structured errors.
- [Troubleshooting](references/troubleshooting.md): transport failures, queued
work, Windows identity/session/GUI issues, PowerShell policy, quotas, and recovery.
- [Windows GUI and desktop workflows](references/windows-gui.md): interactive
defaults, application lifetime, real-window probes, and missing-dialog diagnosis.
An optional Python 3 helper, [scripts/request_id.py](scripts/request_id.py),
prints a canonical UUIDv7 using only the standard library. It performs no RPC.
@@ -19,6 +19,7 @@ initial evidence; do not restart services or resubmit work merely to inspect it.
| Socket permission denied | Run as the existing socket owner through the deployment route; inspect directory traversal and mount permissions. Do not chmod the control socket world-accessible. |
| Client missing or NOT_FOUND | List all client pages; verify the exact registered ID and server instance. A hostname assumption or wrong Compose project can select different state. Retention can also remove command history. |
| Disconnected / OFFLINE / UNAVAILABLE | Separate server recovery from client connectivity. Inspect SCM, WSS hostname/path, proxy WebSocket upgrade, certificate/time/CA, DNS, reconnect logs, and pending instance conflicts. Missing optional HTTP health is not proof of a stopped daemon. |
| Repeated `signal command ...: command is not running` | An older client disconnects on a late signal instead of persisting its rejection. Upgrade the client while retaining config/spool/history; corrected builds acknowledge the signal without disconnecting. Do not wipe state or reissue the original command. |
| QUEUED persists | Check connection, supported shell, queue/running capacity, acceptance events, and queue expiry. Queuing does not promise execution, and queue TTL is not a runtime timeout. |
| CLI deadline / broken stream | Work may still run. Query the captured issue and resume history via the API. For uncertain admission, retry only with the same request ID and payload. |
| CLI exit 0 but task failed | Inspect remote terminal lifecycle, rejection/detail, and output. A successful follow stream is not a successful process. |
@@ -60,6 +61,14 @@ follow the effective token. A single-owner laptop may have a split admin token,
but do not assume it. If a UI does not appear, verify both token/session and
window station/desktop; a process listing alone is insufficient.
Builds containing the interactive-desktop fix explicitly target
`winsta0\default` for active-user, active-user-elevated, and active-system.
They verify the launcher's actual desktop/access, use a headless command console,
and request normal GUI startup visibility. Session 0 routes remain
noninteractive. See [Windows GUI workflows](windows-gui.md) for a bundled
visible-window probe, `/wait` examples, and limits involving locks, focus,
privileges, shell policy, and applications that hand off to an existing process.
### Opening folders and Explorer exit code 1
For shell folder opening, use `start "" "%USERPROFILE%"` through `--shell cmd`.
+119
View File
@@ -0,0 +1,119 @@
# 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](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:
```sh
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:
```sh
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](troubleshooting.md#opening-folders-and-explorer-exit-code-1).
## Verify a real window
The bundled [windows_gui_probe.ps1](../scripts/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:
```sh
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
1. Verify selected session, effective SID/context, requested elevation, and
launch rejection. Matching user/session alone does not prove correct desktop
placement. A `launcher preparation failed` desktop/access message identifies
a pre-launch failure; correct the account/session/access prerequisites rather
than granting broad desktop permissions or silently changing identities.
2. 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.
3. 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.
4. 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.
5. 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](https://learn.microsoft.com/en-us/windows/win32/api/processthreadsapi/nf-processthreadsapi-createprocessasuserw),
[console allocation semantics](https://github.com/microsoft/terminal/blob/main/doc/specs/%237335%20-%20Console%20Allocation%20Policy.md),
[foreground restrictions](https://learn.microsoft.com/en-us/windows/win32/api/winuser/nf-winuser-setforegroundwindow).
+106
View File
@@ -0,0 +1,106 @@
# Self-contained diagnostic: real window/desktop visibility, or console TERM.
# Uses Windows PowerShell 5.1 / .NET already present; installs nothing.
param(
[ValidateRange(1, 25)][int]$Seconds = 8,
[switch]$ConsoleOnly
)
$ErrorActionPreference = 'Stop'
Add-Type -TypeDefinition @'
using System;
using System.ComponentModel;
using System.Runtime.InteropServices;
using System.Text;
using System.Threading;
namespace RVBoxDesktopProbe {
public static class Native {
[StructLayout(LayoutKind.Sequential)] public struct StartupInfo {
public uint cb; public IntPtr reserved, desktop, title;
public uint x,y,xSize,ySize,xChars,yChars,fill,flags;
public ushort showWindow,reservedBytes;
public IntPtr reservedData,input,output,error;
}
[DllImport("kernel32.dll")] public static extern void GetStartupInfoW(out StartupInfo value);
[DllImport("kernel32.dll")] public static extern uint GetCurrentThreadId();
[DllImport("kernel32.dll")] public static extern IntPtr GetConsoleWindow();
[DllImport("kernel32.dll")] public static extern uint GetConsoleCP();
[DllImport("user32.dll")] public static extern IntPtr GetProcessWindowStation();
[DllImport("user32.dll")] public static extern IntPtr GetThreadDesktop(uint thread);
[DllImport("user32.dll")] public static extern bool IsWindowVisible(IntPtr window);
[DllImport("user32.dll", SetLastError=true)] public static extern IntPtr OpenInputDesktop(uint flags, bool inherit, uint access);
[DllImport("user32.dll")] public static extern bool CloseDesktop(IntPtr desktop);
[DllImport("user32.dll", CharSet=CharSet.Unicode, SetLastError=true)]
static extern bool GetUserObjectInformationW(IntPtr handle,int index,StringBuilder value,uint size,out uint needed);
public static string Name(IntPtr handle) {
var value = new StringBuilder(256); uint needed;
if (handle == IntPtr.Zero || !GetUserObjectInformationW(handle,2,value,512,out needed))
throw new Win32Exception(Marshal.GetLastWin32Error());
return value.ToString();
}
delegate bool Handler(uint code);
[DllImport("kernel32.dll",SetLastError=true)] static extern bool SetConsoleCtrlHandler(Handler handler,bool add);
public static bool WaitForBreak(int milliseconds) {
using (var received = new ManualResetEvent(false)) {
Handler handler = delegate(uint code) { if (code != 1) return false; received.Set(); return true; };
if (!SetConsoleCtrlHandler(handler,true)) throw new Win32Exception(Marshal.GetLastWin32Error());
try {
Console.WriteLine("RVBOX_CONSOLE_READY"); Console.Out.Flush();
bool seen = received.WaitOne(milliseconds);
Console.WriteLine(seen ? "RVBOX_CTRL_BREAK_OBSERVED" : "RVBOX_CTRL_BREAK_TIMEOUT"); Console.Out.Flush();
return seen;
} finally { SetConsoleCtrlHandler(handler,false); GC.KeepAlive(handler); }
}
}
}
}
'@
if ($ConsoleOnly) {
if ([RVBoxDesktopProbe.Native]::WaitForBreak($Seconds * 1000)) { exit 0 }
exit 2
}
Add-Type -AssemblyName System.Windows.Forms
$startup = New-Object RVBoxDesktopProbe.Native+StartupInfo
[RVBoxDesktopProbe.Native]::GetStartupInfoW([ref]$startup)
$state = [ordered]@{
session_id = [Diagnostics.Process]::GetCurrentProcess().SessionId
user_sid = [Security.Principal.WindowsIdentity]::GetCurrent().User.Value
window_station = [RVBoxDesktopProbe.Native]::Name([RVBoxDesktopProbe.Native]::GetProcessWindowStation())
desktop = [RVBoxDesktopProbe.Native]::Name([RVBoxDesktopProbe.Native]::GetThreadDesktop([RVBoxDesktopProbe.Native]::GetCurrentThreadId()))
input_desktop = ''
input_desktop_error = 0
window_observed = $false
has_console = ([RVBoxDesktopProbe.Native]::GetConsoleCP() -ne 0)
console_window_visible = [RVBoxDesktopProbe.Native]::IsWindowVisible([RVBoxDesktopProbe.Native]::GetConsoleWindow())
startup_use_show_window = (($startup.flags -band 1) -ne 0)
startup_show_window = $startup.showWindow
}
$inputDesktop = [RVBoxDesktopProbe.Native]::OpenInputDesktop(0, $false, 1)
if ($inputDesktop -ne [IntPtr]::Zero) {
try { $state.input_desktop = [RVBoxDesktopProbe.Native]::Name($inputDesktop) }
finally { [void][RVBoxDesktopProbe.Native]::CloseDesktop($inputDesktop) }
} else { $state.input_desktop_error = [Runtime.InteropServices.Marshal]::GetLastWin32Error() }
$form = New-Object System.Windows.Forms.Form
$form.Text = 'RVBox interactive desktop test'
$form.Width = 540; $form.Height = 170
$form.StartPosition = 'CenterScreen'
$label = New-Object System.Windows.Forms.Label
$label.AutoSize = $false; $label.Dock = 'Fill'; $label.TextAlign = 'MiddleCenter'
$label.Text = "RVBox launched this window on your desktop.`r`nIt closes automatically after $Seconds seconds."
$form.Controls.Add($label)
$form.Add_Shown({
if ([RVBoxDesktopProbe.Native]::IsWindowVisible($form.Handle)) { $state.window_observed = $true }
})
$timer = New-Object System.Windows.Forms.Timer
$timer.Interval = 100
$elapsed = [Diagnostics.Stopwatch]::StartNew()
$timer.Add_Tick({
if ([RVBoxDesktopProbe.Native]::IsWindowVisible($form.Handle)) { $state.window_observed = $true }
if ($elapsed.Elapsed.TotalSeconds -ge $Seconds) { $form.Close() }
})
$timer.Start()
try { [System.Windows.Forms.Application]::Run($form) }
finally { $timer.Stop(); $timer.Dispose(); $form.Dispose() }
$state | ConvertTo-Json -Compress
if (-not $state.window_observed -or $state.session_id -eq 0 -or
$state.window_station -ine 'WinSta0' -or $state.desktop -ine 'Default' -or
$state.input_desktop -ine 'Default' -or $state.console_window_visible) { exit 2 }
exit 0