bug: openshell CLI fails on Windows — HOME environment variable not set

[jeffmaury]

Agent Diagnostic

Loaded skill: create-github-issue. Ran codebase-wide grep for HOME env var usage.

Findings: The CLI (and core path resolution) unconditionally reads HOME, which does not exist on Windows (Windows uses USERPROFILE, HOMEDRIVE/HOMEPATH). Key call sites:

File	Line(s)	Usage
crates/openshell-core/src/paths.rs	23, 41, 59	xdg_config_dir(), xdg_state_dir(), xdg_data_dir() — all error with "HOME is not set"
crates/openshell-cli/src/run.rs	738	std::env::var_os("HOME") fallback for XDG_STATE_HOME
crates/openshell-cli/src/run.rs	4354-4355	gcloud ADC file resolution — errors with "HOME is not set"
crates/openshell-cli/src/ssh.rs	1457-1459	SSH config path — errors with "HOME is not set"
crates/openshell-core/src/config.rs	164, 219	Podman/Docker socket candidates
crates/openshell-providers/src/providers/opencode.rs	21-28	opencode_config_path() fallback
crates/openshell-server/src/compute/vm.rs	238	Driver search directory
crates/openshell-driver-vm/src/driver.rs	3232	macOS podman socket path

No USERPROFILE, HOMEDRIVE, or HOMEPATH handling exists anywhere in the codebase. The entire XDG path-resolution layer assumes a Unix-like HOME.

Description

Actual behavior: Running openshell on Windows fails immediately because std::env::var("HOME") returns an error. The HOME environment variable is not set by default on Windows — Windows uses USERPROFILE (e.g., C:\Users\<name>) instead.

Expected behavior: The CLI should resolve the user's home directory on all supported platforms, falling back to USERPROFILE on Windows (or using Rust's dirs::home_dir() / std::env::home_dir()).

Reproduction Steps

1. Install OpenShell on Windows
2. Run any openshell CLI command (e.g., openshell --help or openshell sandbox create)
3. Observe error: "HOME is not set"

Environment

• OS: Windows 11 Pro 10.0.26100
• Docker: N/A (crash occurs before Docker interaction)
• OpenShell: main branch (commit 7e0cce4)

Logs

Error: HOME is not set

[jeffmaury]

🏗️ build-plan

Implementation Plan

Issue type: fix
Complexity: Low-Medium
Confidence: High — well-understood problem, mechanical replacement, zero new supply-chain risk

Summary

Every home-directory lookup in the codebase reads HOME directly via std::env::var("HOME") or std::env::var_os("HOME"). Windows does not set HOME; it uses USERPROFILE (or HOMEDRIVE+HOMEPATH). The fix introduces a single home_dir() helper in openshell-core::paths backed by the home crate (already a transitive dependency via etcetera, kube, russh, etc.), then replaces all direct HOME lookups with calls to this helper.

Scope

Core helper (new code):

• Cargo.toml (root workspace): Add home = "0.5" to [workspace.dependencies]
• crates/openshell-core/Cargo.toml: Add home = { workspace = true } to [dependencies]
• crates/openshell-core/src/paths.rs: Add pub fn home_dir() -> Result<PathBuf> using home::home_dir(). Update xdg_config_dir(), xdg_state_dir(), xdg_data_dir() to call it instead of reading HOME directly.

Tier 1 — Blocking on Windows (must fix):

• crates/openshell-cli/src/run.rs:738: Replace std::env::var_os("HOME") with home_dir().ok()
• crates/openshell-cli/src/run.rs:4354-4355: Replace std::env::var("HOME") in gcloud ADC resolution
• crates/openshell-cli/src/ssh.rs:1457-1459: Replace std::env::var("HOME") in user_ssh_config_path()
• crates/openshell-core/src/config.rs:164: Replace std::env::var_os("HOME") in podman_socket_candidates()
• crates/openshell-core/src/config.rs:219: Replace std::env::var_os("HOME") in docker_socket_candidates()
• crates/openshell-providers/src/providers/opencode.rs:25: Replace std::env::var("HOME") fallback

Tier 2 — Not reachable on Windows (platform-gated, fix for consistency):

• crates/openshell-server/src/compute/vm.rs:238: Replace std::env::var_os("HOME") (VM driver is Linux/macOS only)
• crates/openshell-driver-vm/src/driver.rs:3232: #[cfg(target_os = "macos")] block — add home dep, use home::home_dir()
• crates/openshell-driver-podman/src/config.rs:230: #[cfg(target_os = "macos")] block — add home dep, use home::home_dir()

Implementation Steps

1. Add home crate dependency and home_dir() helper — Add workspace dep, add to openshell-core, create home_dir() function, update xdg_config_dir(), xdg_state_dir(), xdg_data_dir()
2. Update openshell-core::config — Replace HOME lookups in podman_socket_candidates() and docker_socket_candidates()
3. Update openshell-cli — Replace HOME lookups in run.rs (XDG fallback + gcloud ADC) and ssh.rs (user_ssh_config_path())
4. Update openshell-providers — Replace HOME lookup in opencode.rs config path fallback
5. Update Tier 2 driver crates — Add home dep to openshell-driver-vm and openshell-driver-podman, replace macOS-gated HOME lookups and openshell-server VM driver lookup

Test Plan

• Unit tests: Add test for home_dir() in paths.rs verifying it returns Ok on all platforms. Existing tests for xdg_config_dir, openshell_config_dir, openshell_state_dir continue to pass. SSH config test (ssh.rs:1665) continues to work because home::home_dir() respects HOME when set explicitly.
• Integration tests: N/A — mechanical replacement, no new inter-component interaction
• E2E tests: N/A — no changes under e2e/, existing suite covers exercised paths

Risks & Open Questions

• XDG on Windows: On Windows, $HOME/.config resolves to C:\Users\<user>\.config, which is unconventional (Windows uses %APPDATA%). This is a pre-existing design choice — the fix only unblocks HOME resolution, not the directory layout. Changing to %APPDATA% would be a separate, larger-scope decision.
• home crate stability: Maintained by the Rust project itself (rust-lang/cargo), zero non-windows-sys dependencies, already a transitive dependency. Risk is negligible.
• openshell-driver-podman::default_socket_path() panic: Line 230 uses .expect("HOME must be set on macOS"). After the fix, the panic message improves but the panic risk remains for edge cases. Converting to Result is out of scope for this bug fix.

Documentation Impact

• None expected — internal implementation fix with no user-facing API or config changes

LSM Compatibility

• No concerns — does not interact with /proc, process identity, binary execution, or inter-process visibility

---

Revision 1 — initial plan

[jeffmaury]

🏗️ build-from-issue-agent

Implementation Complete

PR: #2031

What was built

Added a cross-platform home_dir() helper in openshell-core::paths using the home crate, and replaced all 13 direct std::env::var("HOME") lookups across 7 crates. The CLI will now resolve the home directory correctly on Windows via USERPROFILE.

Tests

• Unit: 1 test added (home_dir_returns_ok)
• Integration: N/A
• E2E: N/A

Docs updated

• None needed