docs: document desktop rescue UX

.agents/skills/crabbox/SKILL.md

@@ -100,6 +100,11 @@ Use native `crabbox vnc --id <id-or-slug> --open` as the fallback printed by
 and passwords. `desktop key` accepts both `--id <lease> <keys>` and positional
 `<lease> <keys>` forms for shortcuts.
 
+When desktop/WebVNC hangs, trust the inline rescue output first: `problem: VNC
+bridge disconnected`, `problem: browser not launched`, `problem: input stack
+dead`, or similar will be followed by exact `rescue:` commands such as
+`crabbox webvnc status/reset` or `crabbox desktop doctor`.
+
 ## Run Inspection Workflow
 
 Use the CLI for durable run inspection; do not expect extra OpenClaw plugin

CHANGELOG.md

@@ -6,6 +6,7 @@
 
 - Added mediated egress commands and browser wiring so Linux desktop leases can proxy selected app traffic through the operator machine via the coordinator bridge.
 - Added WebVNC portal clipboard controls for sending local clipboard text into the remote session and copying remote clipboard text back to the local browser.
+- Added rescue-first desktop/WebVNC failure output that names the failing layer and prints exact `rescue:` or native VNC fallback commands when bridges, viewers, browser launches, VNC targets, or input stacks hang.
 - Added lease sharing for individual users or the owning org, including `crabbox share`, `crabbox unshare`, API access checks, and a portal share control on lease detail pages.
 
 ### Fixed

docs/commands/desktop.md

@@ -48,6 +48,14 @@ clipboard tool, browser binary, `ffmpeg`, screen size, screenshot capture, and
 WebVNC bridge/viewer state. Failures include a one-line repair suggestion so
 you can tell session bugs from WebVNC/browser-portal bugs.
 
+Desktop launch and input failures now surface the failing layer directly in the
+CLI output. For example, a missing visible browser reports `problem: browser not
+launched`, a dead input path reports `problem: input stack dead`, and a broken
+portal path reports `problem: VNC bridge disconnected` or `problem: WebVNC
+daemon not running`. The same output includes exact `rescue:` commands such as
+`crabbox desktop doctor --id <lease>` or `crabbox webvnc reset --id <lease>
+--open`.
+
 Input helpers also operate on the selected lease over SSH without repo sync.
 Use them instead of hand-written `xdotool` snippets. `desktop type` uses raw
 `xdotool type` only for simple alphanumeric text; text with emails, passwords,

docs/commands/webvnc.md

@@ -89,6 +89,14 @@ webvnc: https://crabbox.openclaw.ai/portal/leases/cbx_.../vnc#password=...
 fallback: crabbox vnc --provider aws --target linux --network tailscale --id cbx_... --open
 ```
 
+When a layer is unhealthy, the CLI prints `problem:`, optional `detail:`, and
+one or more exact `rescue:` commands in the command output, not only in docs.
+Common problems include `VNC bridge disconnected`, `WebVNC daemon not running`,
+`WebVNC viewer already active`, and `VNC target unreachable`. If the browser
+portal path looks unhealthy but the target VNC service is reachable, the output
+also prints the native `crabbox vnc ... --open` fallback command with the same
+provider/target/network flags.
+
 Use `crabbox webvnc reset --id <lease> --open` when the portal is stuck on a
 stale bridge/viewer/session. Reset closes only that lease's coordinator
 WebVNC sockets, stops only that lease's local daemon pid after verifying it is
@@ -108,8 +116,9 @@ flow redirects first, the page may still prompt for the VNC password; use the
 password printed by the command. If an old browser tab is retrying with a stale
 fragment, close it before opening the new bridge URL.
 
-The portal page may show `waiting for bridge` until the local command has
-connected. If you opened the portal first, start:
+The portal page may show `WebVNC daemon not running` or `waiting for VNC
+bridge` until the local command has connected. If you opened the portal first,
+start:
 
 ```sh
 crabbox webvnc --id <lease-id-or-slug>
@@ -182,14 +191,15 @@ The lease is reachable over SSH, but the desktop service is not ready or was not
 provisioned. Create the lease with `--desktop`, or wait for bootstrap to finish
 and retry.
 
-The portal keeps saying `waiting for bridge`
+The portal keeps saying `WebVNC daemon not running` or `waiting for VNC bridge`
 
 The browser can reach the coordinator, but no local bridge is currently paired
-with that lease. Start or restart `crabbox webvnc --id <lease>` locally and keep
-the process running. If the command is still running, wait for the portal retry
-or reload the browser tab.
+with that lease. Start or restart `crabbox webvnc daemon start --id <lease>
+--open`, or run `crabbox webvnc reset --id <lease> --open` when stale tabs or
+session state are likely. If the command is still running, wait for the portal
+retry or reload the browser tab.
 
-Another viewer is active
+`WebVNC viewer already active`
 
 Close old WebVNC tabs first. If the portal still reports a stale viewer, run:
 

docs/features/interactive-desktop-vnc.md

@@ -133,6 +133,14 @@ lease's desktop session, VNC service, input tooling, browser binary, ffmpeg,
 screen geometry, and screenshot capture, then separately reports WebVNC
 bridge/viewer status with one-line repair suggestions.
 
+Failure output is designed for rescue-first debugging. When a desktop command
+cannot prove the expected state, Crabbox prints the failed layer as
+`problem: browser not launched`, `problem: input stack dead`, `problem: VNC
+bridge disconnected`, `problem: WebVNC daemon not running`, or similar, followed
+by an exact `rescue:` command. WebVNC status/reset also prints the exact native
+`crabbox vnc ... --open` fallback when the native viewer is the better next
+step.
+
 Use first-class input helpers instead of hand-rolled `xdotool`:
 
 ```sh
@@ -173,6 +181,9 @@ Managed VNC is tunnel-first:
 - `crabbox webvnc reset` closes only the selected lease's WebVNC sockets,
   stops only that lease's verified local WebVNC daemon, restarts the target
   desktop/VNC services, then prints the fresh portal URL.
+- WebVNC and desktop commands print rescue commands inline when the bridge,
+  viewer, browser launch, VNC target, or input stack fails, so operators do not
+  need to dig through troubleshooting docs during a demo.
 
 Crabbox does not bind managed VNC directly to a public IP or Tailscale 100.x
 address. Static hosts can expose direct `host:5900` only when the operator has