fix(doctor): address code review feedback on PR aaddrick#324

Address all three review issues from @aaddrick:

Issue 1 (severity mismatch): Implement _kvm_active/_kvm_issue pattern
to vary severity of KVM-specific tool checks (QEMU, socat, virtiofsd).
When KVM is not the active/intended backend, missing KVM tools show as
plain info lines instead of warnings. bubblewrap always warns since it
is an independent backend.

Issue 2 (duplicate reporting): Remove the separate Backend override
info line. Instead, make the Cowork isolation detection honor
COWORK_VM_BACKEND the same way the daemon does, appending [override]
to the label. Also warn on invalid override values.

Issue 3 (colon convention): Keep :- (with colon) as-is. Audited all
21 parameter expansions in production code: 100% use :- consistently.
The colon correctly treats empty string same as unset, matching the
JS side (process.env.COWORK_VM_BACKEND || null).

Also fix TROUBLESHOOTING.md to clarify that --doctor now detects
virtiofsd at /usr/libexec/ automatically, but the symlink is still
needed for the KVM backend at runtime (spawns by PATH only).

Co-Authored-By: Claude <claude@anthropic.com>

Author: 2 people

docs/TROUBLESHOOTING.md

@@ -97,9 +97,12 @@ See [CONFIGURATION.md](CONFIGURATION.md#cowork-backend) for how to make this per
 
 ### 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.
+On Fedora and RHEL, `virtiofsd` installs to `/usr/libexec/virtiofsd` which is
+outside `$PATH`. The `--doctor` check detects it there automatically and will
+show `[PASS]`, but the KVM backend spawns `virtiofsd` by name at runtime and
+resolves it through `$PATH` only.
 
-**Fix:** Create a symlink:
+**Fix:** Create a symlink so the KVM backend can find it at runtime:
 
 ```bash
 sudo ln -s /usr/libexec/virtiofsd /usr/local/bin/virtiofsd

scripts/launcher-common.sh

@@ -483,11 +483,6 @@ 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
@@ -510,6 +505,19 @@ print(len(servers))
 		_info 'Fix: sudo modprobe vhost_vsock'
 	fi
 
+	# KVM-specific tools (QEMU, socat, virtiofsd) are only
+	# actionable when the KVM backend is active or intended.
+	# Show them as [WARN] with fix hints when KVM is relevant,
+	# or as plain [INFO] lines when it is not.
+	local _kvm_active=false _kvm_issue=_info
+	if [[ -n "${COWORK_VM_BACKEND:-}" ]]; then
+		[[ "${COWORK_VM_BACKEND,,}" == 'kvm' ]] \
+			&& _kvm_active=true
+	elif [[ -e /dev/kvm && -r /dev/kvm && -w /dev/kvm ]]; then
+		_kvm_active=true
+	fi
+	$_kvm_active && _kvm_issue=_warn
+
 	# Check required tools: label, binary, pkg-hint name
 	local _tool_label _tool_bin _tool_pkg
 	for _tool_label in \
@@ -525,21 +533,32 @@ print(len(servers))
 
 		if command -v "$_tool_bin" &>/dev/null; then
 			_pass "$_tool_label: found"
-		elif [[ $_tool_bin == 'virtiofsd' ]]; then
+			continue
+		fi
+
+		# virtiofsd: also check non-PATH locations
+		if [[ $_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"
+				continue
+			fi
+		fi
+
+		# Not found — severity depends on backend relevance
+		if [[ $_tool_bin == 'bwrap' ]]; then
+			_warn "$_tool_label: not found"
+			_info \
+				"Fix: $(_cowork_pkg_hint \
+					"$_distro_id" "$_tool_pkg")"
+		else
+			"$_kvm_issue" "$_tool_label: not found"
+			if $_kvm_active; then
 				_info \
 					"Fix: $(_cowork_pkg_hint \
 						"$_distro_id" "$_tool_pkg")"
 			fi
-		else
-			_warn "$_tool_label: not found"
-			_info \
-				"Fix: $(_cowork_pkg_hint "$_distro_id" "$_tool_pkg")"
 		fi
 	done
 
@@ -556,16 +575,32 @@ print(len(servers))
 	fi
 
 	# Determine active backend (matches daemon's detectBackend())
-	local cowork_backend='none (host-direct, no isolation)'
-	if [[ -e /dev/kvm ]] \
-		&& [[ -r /dev/kvm && -w /dev/kvm ]] \
-		&& command -v qemu-system-x86_64 &>/dev/null \
-		&& [[ -e /dev/vhost-vsock ]] \
-		&& [[ -f $vm_image ]]; then
-		cowork_backend='KVM (full VM isolation)'
-	elif command -v bwrap &>/dev/null \
-		&& bwrap --ro-bind / / true &>/dev/null; then
-		cowork_backend='bubblewrap (namespace sandbox)'
+	# When COWORK_VM_BACKEND is set, the daemon skips auto-detection
+	# and uses the override directly — mirror that here.
+	local cowork_backend
+	if [[ -n "${COWORK_VM_BACKEND:-}" ]]; then
+		case "${COWORK_VM_BACKEND,,}" in
+			kvm)   cowork_backend='KVM (full VM isolation) [override]' ;;
+			bwrap) cowork_backend='bubblewrap (namespace sandbox) [override]' ;;
+			host)  cowork_backend='none (host-direct, no isolation) [override]' ;;
+			*)
+			_warn "Unknown COWORK_VM_BACKEND: '${COWORK_VM_BACKEND}'"
+			_info 'Valid values: kvm, bwrap, host'
+			cowork_backend="unknown override: '${COWORK_VM_BACKEND}'"
+			;;
+		esac
+	else
+		cowork_backend='none (host-direct, no isolation)'
+		if [[ -e /dev/kvm ]] \
+			&& [[ -r /dev/kvm && -w /dev/kvm ]] \
+			&& command -v qemu-system-x86_64 &>/dev/null \
+			&& [[ -e /dev/vhost-vsock ]] \
+			&& [[ -f $vm_image ]]; then
+			cowork_backend='KVM (full VM isolation)'
+		elif command -v bwrap &>/dev/null \
+			&& bwrap --ro-bind / / true &>/dev/null; then
+			cowork_backend='bubblewrap (namespace sandbox)'
+		fi
 	fi
 	_info "Cowork isolation: $cowork_backend"