fix(doctor): detect virtiofsd outside PATH + document COWORK_VM_BACKEND

On Fedora/RHEL, virtiofsd installs to /usr/libexec/virtiofsd which is
outside $PATH. On Debian/Ubuntu, it may be at /usr/lib/qemu/virtiofsd.
The --doctor check uses `command -v` and reports a false warning.

This commit:

- Adds _doctor_find_virtiofsd() helper that probes common non-PATH
  locations (/usr/libexec/virtiofsd, /usr/lib/qemu/virtiofsd)
- Shows the found path in --doctor output when not in PATH
- Documents the COWORK_VM_BACKEND environment variable in
  docs/CONFIGURATION.md (host|bwrap|kvm backend override)
- Adds Cowork troubleshooting section to docs/TROUBLESHOOTING.md
  covering VM timeout, virtiofsd PATH, and Fedora tmpfs /tmp issues
- Shows COWORK_VM_BACKEND override in --doctor Cowork section

Tested on Fedora 43 (GNOME/Wayland) with virtiofsd at /usr/libexec/.

Fixes aaddrick#293

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: 2 people

docs/CONFIGURATION.md

@@ -15,6 +15,7 @@ Model Context Protocol settings are stored in:
 |----------|---------|-------------|
 | `CLAUDE_USE_WAYLAND` | unset | Set to `1` to use native Wayland instead of XWayland. Note: Global hotkeys won't work in native Wayland mode. |
 | `CLAUDE_MENU_BAR` | unset (`auto`) | Controls menu bar behavior: `auto` (hidden, Alt toggles), `visible` / `1` (always shown), `hidden` / `0` (always hidden, Alt disabled). See [Menu Bar](#menu-bar) below. |
+| `COWORK_VM_BACKEND` | unset (auto-detect) | Force a specific Cowork isolation backend: `kvm` (full VM), `bwrap` (bubblewrap namespace sandbox), or `host` (no isolation). See [Cowork Backend](#cowork-backend) below. |
 
 ### Wayland Support
 
@@ -48,6 +49,42 @@ CLAUDE_MENU_BAR=visible claude-desktop
 export CLAUDE_MENU_BAR=visible
 ```
 
+### Cowork Backend
+
+Cowork mode auto-detects the best available isolation backend:
+
+| Priority | Backend | Isolation | Detection |
+|----------|---------|-----------|-----------|
+| 1 | KVM | Full QEMU/KVM VM | `/dev/kvm` (r/w) + `qemu-system-x86_64` + `/dev/vhost-vsock` |
+| 2 | bubblewrap | Namespace sandbox | `bwrap` installed and functional |
+| 3 | host | None (direct execution) | Always available |
+
+To override auto-detection:
+
+```bash
+# Force bubblewrap (recommended if KVM times out)
+COWORK_VM_BACKEND=bwrap claude-desktop
+
+# Force host mode (no isolation)
+COWORK_VM_BACKEND=host claude-desktop
+
+# Make permanent via desktop entry override
+mkdir -p ~/.local/share/applications/
+cat > ~/.local/share/applications/claude-desktop.desktop << 'EOF'
+[Desktop Entry]
+Name=Claude
+Exec=env COWORK_VM_BACKEND=bwrap /usr/bin/claude-desktop %u
+Icon=claude-desktop
+Type=Application
+Terminal=false
+Categories=Office;Utility;
+MimeType=x-scheme-handler/claude;
+StartupWMClass=Claude
+EOF
+```
+
+Run `claude-desktop --doctor` to see which backend is selected and which dependencies are available.
+
 ## Application Logs
 
 Runtime logs are available at:

docs/TROUBLESHOOTING.md

@@ -80,6 +80,46 @@ If the global hotkey (Ctrl+Alt+Space) doesn't work, ensure you're not running in
 
 See [CONFIGURATION.md](CONFIGURATION.md) for more details on the `CLAUDE_USE_WAYLAND` environment variable.
 
+### Cowork: "VM connection timeout after 60 seconds"
+
+If Cowork fails with a VM timeout, the KVM backend is selected but the guest VM cannot connect back to the host via vsock within the timeout window. Common causes:
+
+1. **First-boot initialization** — the guest VM may take longer than 60 seconds on first launch
+2. **vsock driver issues** — the guest initrd may lack the `vmw_vsock_virtio_transport` kernel module
+
+**Fix:** Force the bubblewrap backend, which provides namespace-level isolation without a VM:
+
+```bash
+COWORK_VM_BACKEND=bwrap claude-desktop
+```
+
+See [CONFIGURATION.md](CONFIGURATION.md#cowork-backend) for how to make this permanent.
+
+### Cowork: virtiofsd not found (Fedora/RHEL)
+
+On Fedora and RHEL, `virtiofsd` installs to `/usr/libexec/virtiofsd` which is outside `$PATH`. The `--doctor` check may report `[WARN] virtiofsd: not found` even though the package is installed.
+
+**Fix:** Create a symlink:
+
+```bash
+sudo ln -s /usr/libexec/virtiofsd /usr/local/bin/virtiofsd
+```
+
+On Debian/Ubuntu, the same issue can occur with `/usr/lib/qemu/virtiofsd`.
+
+### Cowork: cross-device link error on Fedora tmpfs /tmp
+
+On Fedora, `/tmp` is a tmpfs by default. VM bundle downloads may fail with `EXDEV: cross-device link not permitted` when moving files from `/tmp` to `~/.config/Claude/`.
+
+**Fix:** Set `TMPDIR` to a directory on the same filesystem:
+
+```bash
+mkdir -p ~/.config/Claude/tmp
+TMPDIR=~/.config/Claude/tmp claude-desktop
+```
+
+Or add `TMPDIR=%h/.config/Claude/tmp` to the `Exec=` line in your `.desktop` file.
+
 ### AppImage Sandbox Warning
 
 AppImages run with `--no-sandbox` due to electron's chrome-sandbox requiring root privileges for unprivileged namespace creation. This is a known limitation of AppImage format with Electron applications.

scripts/launcher-common.sh

@@ -232,6 +232,21 @@ _cowork_pkg_hint() {
 	printf '%s' "$pkg_cmd $pkg"
 }
 
+# Probe common non-PATH locations for virtiofsd
+# On Fedora/RHEL: /usr/libexec/virtiofsd
+# On Debian/Ubuntu: /usr/lib/qemu/virtiofsd
+# Returns 0 if found, 1 if not; prints path on stdout
+_doctor_find_virtiofsd() {
+	local path
+	for path in /usr/libexec/virtiofsd /usr/lib/qemu/virtiofsd; do
+		if [[ -x $path ]]; then
+			printf '%s' "$path"
+			return 0
+		fi
+	done
+	return 1
+}
+
 _pass() { echo -e "${_green}[PASS]${_reset} $1"; }
 _fail() {
 	echo -e "${_red}[FAIL]${_reset} $1"
@@ -468,6 +483,11 @@ print(len(servers))
 	local _distro_id
 	_distro_id=$(_cowork_distro_id)
 
+	# COWORK_VM_BACKEND override
+	if [[ -n "${COWORK_VM_BACKEND:-}" ]]; then
+		_info "Backend override: COWORK_VM_BACKEND=${COWORK_VM_BACKEND}"
+	fi
+
 	# KVM access
 	if [[ -e /dev/kvm ]]; then
 		if [[ -r /dev/kvm && -w /dev/kvm ]]; then
@@ -505,6 +525,17 @@ print(len(servers))
 
 		if command -v "$_tool_bin" &>/dev/null; then
 			_pass "$_tool_label: found"
+		elif [[ $_tool_bin == 'virtiofsd' ]]; then
+			local _vfsd_path
+			_vfsd_path=$(_doctor_find_virtiofsd) || true
+			if [[ -n $_vfsd_path ]]; then
+				_pass "$_tool_label: found ($_vfsd_path, not in PATH)"
+			else
+				_warn "$_tool_label: not found"
+				_info \
+					"Fix: $(_cowork_pkg_hint \
+						"$_distro_id" "$_tool_pkg")"
+			fi
 		else
 			_warn "$_tool_label: not found"
 			_info \