refactor: home directory comes from a HostProcessHomeDirectory reference

[juliusmarminge]

56 places called NodeOS.homedir() directly. Tests couldn't override the home directory that way, and the dependency was hidden from the R channel. @t3tools/shared/hostProcess already provides the platform, environment, hostname and working directory as Context.References, but not the home directory.

• New reference: HostProcessHomeDirectory, defaulting to NodeOS.homedir().
• Converted: every call reachable from Effect code now yields it. That covers 40 calls across apps/server, apps/desktop, provider-core, provider-cursor, provider-grok, provider-opencode and provider-acp, including the usage readers this stack moved.
• Plain helpers: they now take home from their Effect caller instead of reading the global. This includes expandHomePath(value, home), resolveWorktreesDirectory, sanitizeAcpStderrExcerpt and niriCaptureConfigPath.
• Now Effect functions: mergeProviderInstanceEnvironment (it expands ~) and claudeAccountConfigPath.
• Tests: ones that mocked os.homedir now provide the reference.

Fallbacks are unchanged (HOME/USERPROFILE before the reference), so there is no behavior change.

Still calling homedir(), on purpose:

• plain Node scripts: scripts/dev-runner.ts and apps/server/scripts/*;
• desktop bootstrap code that runs before any Effect runtime: main.ts and compileCache.ts;
• the SSH device script, which ships as a string to another machine;
• fixture-only tests.

🤖 Generated with Claude Code (Claude Opus 5.5, Claude Code harness)

[macroscopeapp]

Approvability

Verdict: Not approved

Macroscope's review found this PR not approvable — This is a cross-cutting production refactor that changes shared home-directory and Effect dependencies across provider, desktop, workspace, authentication, credential, and usage flows. Although the default home remains unchanged, the breadth and sensitive path-resolution impact warrant human review.

^{Adjust the Minimum Blocking Severity for this repo — including turning it Off — in Settings. You can add or adjust custom eligibility rules. Learn more.}

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: Path: .coderabbit.config.ts
• Review profile: CHILL
• Plan: Team
• Run ID: 7506d410-47c1-423f-9814-3c68bdfa49bf

---

📥 Commits

Reviewing files that changed from the base of the PR and between c85dc64 and bad2dd3.

---

📒 Files selected for processing (74)

• apps/desktop/src/app/DesktopApp.ts
• apps/desktop/src/app/DesktopPreReadyPlatform.ts
• apps/desktop/src/ipc/methods/window.ts
• apps/desktop/src/snapShot/CaptureShortcutConfig.test.ts
• apps/desktop/src/snapShot/CaptureShortcutConfig.ts
• apps/desktop/src/snapShot/DesktopSnapShot.ts
• apps/desktop/src/snapShot/HyprlandSnapShot.test.ts
• apps/desktop/src/snapShot/HyprlandSnapShot.ts
• apps/server/src/assets/AssetAccess.test.ts
• apps/server/src/assets/AssetAccess.ts
• apps/server/src/cli/app.test.ts
• apps/server/src/orchestration-v2/Adapters/ClaudeAdapterV2.ts
• apps/server/src/orchestration-v2/Adapters/CodexAdapterV2.ts
• apps/server/src/orchestration-v2/Adapters/GrokAdapterV2.test.ts
• apps/server/src/orchestration-v2/workflowScriptQuery.ts
• apps/server/src/os-jank.ts
• apps/server/src/project/AgentSessionScanner.ts
• apps/server/src/provider/CodexProvider.ts
• apps/server/src/provider/Drivers/AntigravityDriver.ts
• apps/server/src/provider/Drivers/AntigravitySkills.test.ts
• apps/server/src/provider/Drivers/AntigravitySkills.ts
• apps/server/src/provider/Drivers/AntigravityUsage.ts
• apps/server/src/provider/Drivers/ClaudeDriver.ts
• apps/server/src/provider/Drivers/ClaudeHome.ts
• apps/server/src/provider/Drivers/ClaudeSkills.ts
• apps/server/src/provider/Drivers/CodexDriver.ts
• apps/server/src/provider/Drivers/CodexHomeLayout.ts
• apps/server/src/provider/Drivers/CodexManagedProvider.ts
• apps/server/src/provider/Drivers/claudeUsage.ts
• apps/server/src/provider/ProviderInstanceRegistry.test.ts
• apps/server/src/provider/antigravityAuthSupport.ts
• apps/server/src/provider/claudeResetCredits.ts
• apps/server/src/provider/providerInstallation.ts
• apps/server/src/review/ReviewService.ts
• apps/server/src/sourceControl/SourceControlRepositoryService.ts
• apps/server/src/storageCleanup.ts
• apps/server/src/telemetry/Identify.ts
• apps/server/src/terminal/Manager.ts
• apps/server/src/textGeneration/CodexTextGeneration.ts
• apps/server/src/usage/UsageService.ts
• apps/server/src/vcs/GitVcsDriverCore.ts
• apps/server/src/workspace/WorkspaceEntries.ts
• apps/server/src/workspace/WorkspacePaths.ts
• apps/server/src/worktreesDirectory.ts
• packages/provider-acp-registry/src/server/adapter.ts
• packages/provider-acp-registry/src/server/driver.ts
• packages/provider-acp/src/server/AcpSessionRuntime.ts
• packages/provider-acp/src/server/stderr.test.ts
• packages/provider-acp/src/server/stderr.ts
• packages/provider-core/src/server/instanceEnvironment.test.ts
• packages/provider-core/src/server/instanceEnvironment.ts
• packages/provider-core/src/server/pathExpansion.test.ts
• packages/provider-core/src/server/pathExpansion.ts
• packages/provider-cursor/src/server/CursorUsageAccounts.ts
• packages/provider-cursor/src/server/adapter.ts
• packages/provider-cursor/src/server/driver.ts
• packages/provider-cursor/src/server/skills.ts
• packages/provider-cursor/src/server/textGeneration.ts
• packages/provider-cursor/src/server/usageLimits.ts
• packages/provider-grok/src/server/adapter.ts
• packages/provider-grok/src/server/driver.ts
• packages/provider-grok/src/server/usage.ts
• packages/provider-grok/src/server/usageLimits.ts
• packages/provider-grok/src/server/xaiAcpExtension.test.ts
• packages/provider-grok/src/server/xaiAcpExtension.ts
• packages/provider-muse/src/server/driver.ts
• packages/provider-opencode/src/server/adapter.ts
• packages/provider-opencode/src/server/driver.ts
• packages/provider-opencode/src/server/usage.ts
• packages/provider-opencode/src/server/usageLimits.ts
• packages/provider-pi/src/server/adapter.ts
• packages/provider-pi/src/server/driver.ts
• packages/shared/src/hostProcess.ts
• packages/source-control-forgejo/src/server/ForgejoCli.ts

---

Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 6 remain after this review.

---

---

📝 Walkthrough

Walkthrough

The change adds HostProcessHomeDirectory and routes home-relative path resolution through it. Desktop, server, and provider code now uses the injected home directory. Provider environment merging now runs within Effect flows, with tests updated for explicit home values.

Changes

Host home directory and path resolution

Layer / File(s)	Summary
Shared home and path contracts packages/shared/src/hostProcess.ts, packages/provider-core/src/server/pathExpansion.ts, packages/provider-core/src/server/instanceEnvironment.ts	Adds the host home service. Tilde expansion and provider environment merging use the supplied home directory.
Desktop home-dependent paths apps/desktop/src/app/*, apps/desktop/src/ipc/methods/window.ts, apps/desktop/src/snapShot/*	Desktop startup, extension lookup, Niri paths, and Hyprland paths use the host home directory.
Server path resolution apps/server/src/assets/*, apps/server/src/workspace/*, apps/server/src/worktreesDirectory.ts, apps/server/src/terminal/Manager.ts, apps/server/src/usage/UsageService.ts	Server path expansion and worktree, workspace, terminal, usage, asset, and session flows receive the host home directory.
Provider home paths apps/server/src/provider/*, apps/server/src/orchestration-v2/*, packages/provider-cursor/*, packages/provider-grok/*, packages/provider-opencode/*, packages/source-control-forgejo/*	Provider configuration, binary paths, usage roots, credential paths, and plan paths use the host home directory.
Effect-based environment wiring packages/provider-*/src/server/{adapter,driver}.ts, apps/server/src/provider/providerInstallation.ts, apps/server/src/usage/UsageService.ts	Provider environment merging is yielded as an Effect before adapters, drivers, installation, and usage readers consume the result.

Priority: ➖ Normal

Estimated code review effort: 4 (Complex) | ~45 minutes

Change: Refactor

---

Merge Risk: ⚪ Minimal · up to bad2d

This refactor routes home-directory lookups through an overridable reference with no intended behavior change. No concrete merge-blocking risk was found.

Pre-merge checks | 3 | 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Description check		The description clearly explains the problem and implementation, but it omits the required Scope and approval and Verification sections. It does not provide issue or maintainer approval information, f…	Add a Scope and approval section with the triaged issue or explicit maintainer approval, or explain why this focused refactor qualifies for an exemption. Add a Verification section with the focused tests or manual checks performed, their ob…

✅ Passed checks (3 passed)

Check name	Status	Explanation
Linked Issues check		Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check		Check skipped because no linked issues were found for this pull request.
Title check		The title clearly and concisely describes the main change: introducing HostProcessHomeDirectory as the source of the home directory.

---

Full details: Description check

Explanation

The description clearly explains the problem and implementation, but it omits the required Scope and approval and Verification sections. It does not provide issue or maintainer approval information, focused test commands, observed results, or unchecked items.

Resolution

Add a Scope and approval section with the triaged issue or explicit maintainer approval, or explain why this focused refactor qualifies for an exemption. Add a Verification section with the focused tests or manual checks performed, their observed results, and any checks not run.

---

---

✨ Finishing Touches

📝 Generate docstrings

• Commit to this branch
• Create a new PR

---

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

---

---

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

---

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

Thread transfer impact

✅ Thread transfer remains within every enforced ceiling.

Provider	Metric	Main baseline	This PR	Impact	PR ceiling
Codex	Total thread wire	5.0 KiB	5.0 KiB	0 B (0.0%)	6.8 KiB	✅
Codex	Thread snapshot wire	3.8 KiB	3.8 KiB	0 B (0.0%)	4.9 KiB	✅
Codex	Live turn WebSocket wire	1.2 KiB	1.2 KiB	0 B (0.0%)	2.0 KiB	✅
Codex	Live turn WebSocket decoded	20.9 KiB	20.9 KiB	0 B (0.0%)	29.3 KiB	✅
Codex	Live turn messages	2	2	0 (0.0%)	8	✅
Claude	Total thread wire	5.0 KiB	5.0 KiB	0 B (0.0%)	6.8 KiB	✅
Claude	Thread snapshot wire	3.8 KiB	3.8 KiB	0 B (0.0%)	4.9 KiB	✅
Claude	Live turn WebSocket wire	1.2 KiB	1.2 KiB	0 B (0.0%)	2.0 KiB	✅
Claude	Live turn WebSocket decoded	21.2 KiB	21.2 KiB	0 B (0.0%)	29.3 KiB	✅
Claude	Live turn messages	1	1	0 (0.0%)	8	✅

Baseline: c85dc64 · PR result: bad2dd3 · Source CI: success

Scenario and decoded snapshot size

10 historical turns, 5 command tools per turn, 878.9 KiB retained MCP result per historical turn, and a 1.05 MiB retained result in the measured turn.

• Codex decoded thread snapshot: 108.5 KiB
• Claude decoded thread snapshot: 108.8 KiB

Updated in place by a trusted workflow. PR artifacts are strictly validated and never executed.