argsbarg 6.3.0 → 6.3.2

package/CHANGELOG.md

@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [6.3.2] - 2026-08-07
+
+
+## [6.3.1] - 2026-08-07
+
+
 ## [6.3.0] - 2026-08-07
 
 ### Added
@@ -14,10 +20,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **Cursor `stop` hook** — `.cursor/hooks.json` runs `just test` after agent edits to `justfile` or `*.{ts,tsx,js,jsx}` (excluding `node_modules/`, `dist/`, `.cursor/`); test failures auto-submit up to 20 follow-ups. Shipped in copy templates and argsbarg repo root (Cursor-only; not in `AGENTS.md`).
 - **`configure` lifecycle hooks** — `program.configure.afterRefresh` and `program.configure.beforeRemoveAll` for app-specific agent artifact setup/teardown around `configure --refresh` and `configure --remove-all`.
 
+### Fixed
+
+- **`userHome()`** — resolves home from `TEST_USER_HOME` (tests) or platform defaults (`/Users/$USER`, `/home/$USER`, `USERPROFILE`). Never reads `$HOME`, fixing skills installing under Homebrew's `post_install` sandbox.
+
 ### Changed
 
-- **Breaking: `configure --sync` → `configure --refresh`** — renames the non-interactive agent-artifact refresh flag (skills, MCP, config bootstrap). `just sync-artifacts` → `just refresh-artifacts`. No `--sync` alias.
-- **Copy-template justfiles** — `install-local` uses `brew install --force`; uninstall/untap recipes prefix `NONINTERACTIVE=1` so agents and CI skip Homebrew confirm prompts (including post-uninstall untap). `install-production` unchanged.
+- **Breaking: `configure --sync` → `configure --refresh`** — renames the non-interactive agent-artifact refresh flag (skills, MCP, config bootstrap). No `--sync` alias. Copy-template justfiles no longer ship a `refresh-artifacts` recipe; run `configure --refresh --yes` directly.
+- **Copy-template justfiles** — `install-local` depends on `uninstall` then `build` (`brew reinstall || brew install --force`). Dropped `uninstall-artifacts`, `uninstall-formula`, `uninstall-release`, and `uninstall-release-tap` (use `uninstall` + `uninstall-config`). Brew recipes prefix `HOMEBREW_NO_ASK=1`.
 
 ## [6.2.2] - 2026-08-07
 
@@ -915,7 +925,9 @@ const cli = { ... } satisfies CliProgram;  // or : CliProgram
 - Migrate schemas: rename every `children` property to **`commands`**; move positional definitions to **`CliPositional`** objects on `positionals` and strip `positional` / `argMin` / `argMax` from flag definitions under `options` (flags only carry `name`, `description`, `kind`, and optional `shortName`).
 - Imports: use `CliPositional` where needed; replace `CliOptionDef` with `CliOption` or `CliPositional` as appropriate.
 
-[Unreleased]: https://github.com/bdombro/bun-argsbarg/compare/v6.3.0...HEAD
+[Unreleased]: https://github.com/bdombro/bun-argsbarg/compare/v6.3.2...HEAD
+[6.3.2]: https://github.com/bdombro/bun-argsbarg/releases/tag/v6.3.2
+[6.3.1]: https://github.com/bdombro/bun-argsbarg/releases/tag/v6.3.1
 [6.3.0]: https://github.com/bdombro/bun-argsbarg/releases/tag/v6.3.0
 [6.2.2]: https://github.com/bdombro/bun-argsbarg/releases/tag/v6.2.2
 [6.2.1]: https://github.com/bdombro/bun-argsbarg/releases/tag/v6.2.1

package/docs/configure.md

@@ -32,10 +32,10 @@ To remove app config only (keep skills/MCP), run `configure --remove-config --ye
 
 ```bash
 just build
-just install-local    # same formula as production; temporary file:// URL during brew install (`just install` is an alias)
+just install-local    # uninstall, then build + brew install (`just install` is an alias)
 ```
 
-Dev flow matches release: formula `install` copies the binary and generates completions; `post_install` runs `<key> configure --refresh --yes` for skills/MCP. Use `just reinstall-local` to swap the binary into Cellar during tight edit cycles (skips completions and `post_install`). Use `just refresh-artifacts` to refresh agent artifacts without touching the binary.
+Dev flow matches release: `install-local` runs `uninstall` first (keg + untap; formula hook runs `configure --remove-all`), then stages the dev formula and installs. `post_install` runs `<key> configure --refresh --yes` for skills/MCP. Use `just reinstall-local` to swap the binary into Cellar during tight edit cycles (skips completions and `post_install`). Run `<key> configure --refresh --yes` (or `just run configure --refresh --yes`) to refresh agent artifacts without touching the binary.
 
 ## Quick reference
 

package/docs/distribution-homebrew.md

@@ -116,7 +116,7 @@ ArgsBarg provides an optimized workflow for developers to build, package, and te
 # 1. Build the local release binary
 just build
 
-# 2. Stage and install the formula locally (bypasses GitHub, uses file://)
+# 2. Uninstall any existing formula/tap, stage and install locally (bypasses GitHub, uses file://)
 just install-local
 
 # 3. Swap updated binaries quickly during tight edit cycles
@@ -130,9 +130,10 @@ just uninstall
 
 To ensure you test the exact formula that will be shipped to production, `just install-local` runs:
 
-1.  `bun scripts/dev-formula.ts install` — Safely backs up your production formula and writes a temporary local dev formula using a `file://` URL pointing to your build directory.
-2.  `brew install --formula <tap>/{key}` — Installs the package locally using Homebrew.
-3.  `bun scripts/dev-formula.ts reset` — Automatically restores your production formula on disk.
+1.  `just uninstall` — Remove any existing keg and untap (formula `uninstall` hook runs `configure --remove-all`).
+2.  `bun scripts/dev-formula.ts install` — Safely backs up your production formula and writes a temporary local dev formula using a `file://` URL pointing to your build directory.
+3.  `brew reinstall || brew install --force` — Installs the package locally using Homebrew.
+4.  `bun scripts/dev-formula.ts reset` — Automatically restores your production formula on disk.
 
 ---
 

package/examples/full-example/justfile

@@ -66,17 +66,12 @@ http:
 # Alias for backward compatibility
 install: install-local
 
-# Refresh skills and MCP without reinstalling the formula
-refresh-artifacts:
-    just run configure --refresh --yes
-
 # Dev install: build, stage dev formula, brew install, restore release formula
-install-local: build
-    @NONINTERACTIVE=1 brew untap {{tap}} 2>/dev/null || true
+install-local: uninstall build
     mkdir -p {{tap_parent}}
     ln -sfn '{{justfile_directory()}}' {{tap_path}}
     bun scripts/dev-formula.ts install
-    brew install --force --formula {{tap}}/{{cli_key}}
+    HOMEBREW_NO_ASK=1 brew reinstall --formula {{tap}}/{{cli_key}} || HOMEBREW_NO_ASK=1 brew install --force --formula {{tap}}/{{cli_key}}
     bun scripts/dev-formula.ts reset
     @echo ""
     @echo "Next: {{cli_key}} configure"
@@ -121,10 +116,10 @@ release *ARGS:
 
 # Install release formula from tap and run formula test
 test-release:
-    NONINTERACTIVE=1 brew untap {{tap}} 2>/dev/null || true
+    HOMEBREW_NO_ASK=1 brew untap {{tap}} 2>/dev/null || true
     mkdir -p {{tap_parent}}
     ln -sfn '{{justfile_directory()}}' {{tap_path}}
-    NONINTERACTIVE=1 brew uninstall --formula {{tap}}/{{cli_key}} 2>/dev/null || true
+    HOMEBREW_NO_ASK=1 brew uninstall --formula {{tap}}/{{cli_key}} 2>/dev/null || true
     brew install --formula {{tap}}/{{cli_key}}
     brew test {{cli_key}}
 
@@ -132,28 +127,12 @@ test-release:
 typecheck:
     bun run tsc --noEmit
 
-# Undo just install-local: agent artifacts first, then formula
-uninstall: uninstall-artifacts uninstall-formula
-
-# Remove agent artifacts only (skills, MCP)
-uninstall-artifacts:
-    just run configure --remove-all --yes
+# Undo dev/Homebrew install (formula uninstall hook runs configure --remove-all)
+uninstall:
+    @HOMEBREW_NO_ASK=1 brew uninstall --formula {{tap}}/{{cli_key}} 2>/dev/null || true
+    @HOMEBREW_NO_ASK=1 brew uninstall --formula {{tap}}/{{cli_key}}-local 2>/dev/null || true
+    @HOMEBREW_NO_ASK=1 brew untap {{tap}} 2>/dev/null || true
 
 # Remove app config file only
 uninstall-config:
     just run configure --remove-config --yes
-
-# Remove formula and untap
-uninstall-formula:
-    @NONINTERACTIVE=1 brew uninstall --formula {{tap}}/{{cli_key}} 2>/dev/null || true
-    @NONINTERACTIVE=1 brew uninstall --formula {{tap}}/{{cli_key}}-local 2>/dev/null || true
-    @NONINTERACTIVE=1 brew untap {{tap}} 2>/dev/null || true
-
-# Remove release formula (does not untap)
-uninstall-release:
-    @NONINTERACTIVE=1 brew uninstall --formula {{tap}}/{{cli_key}} 2>/dev/null || true
-
-# Remove release formula and untap
-uninstall-release-tap:
-    @NONINTERACTIVE=1 brew uninstall --formula {{tap}}/{{cli_key}} 2>/dev/null || true
-    @NONINTERACTIVE=1 brew untap {{tap}} 2>/dev/null || true

package/examples/full-example-json/justfile

@@ -76,17 +76,12 @@ http:
 # Alias for backward compatibility
 install: install-local
 
-# Refresh skills and MCP without reinstalling the formula
-refresh-artifacts:
-    just run configure --refresh --yes
-
 # Dev install: build, stage dev formula, brew install, restore release formula
-install-local: build
-    @NONINTERACTIVE=1 brew untap {{tap}} 2>/dev/null || true
+install-local: uninstall build
     mkdir -p {{tap_parent}}
     ln -sfn '{{justfile_directory()}}' {{tap_path}}
     bun scripts/dev-formula.ts install
-    brew install --force --formula {{tap}}/{{cli_key}}
+    HOMEBREW_NO_ASK=1 brew reinstall --formula {{tap}}/{{cli_key}} || HOMEBREW_NO_ASK=1 brew install --force --formula {{tap}}/{{cli_key}}
     bun scripts/dev-formula.ts reset
     @echo ""
     @echo "Next: {{cli_key}} configure"
@@ -133,10 +128,10 @@ release *ARGS:
 
 # Install release formula from tap and run formula test
 test-release:
-    NONINTERACTIVE=1 brew untap {{tap}} 2>/dev/null || true
+    HOMEBREW_NO_ASK=1 brew untap {{tap}} 2>/dev/null || true
     mkdir -p {{tap_parent}}
     ln -sfn '{{justfile_directory()}}' {{tap_path}}
-    NONINTERACTIVE=1 brew uninstall --formula {{tap}}/{{cli_key}} 2>/dev/null || true
+    HOMEBREW_NO_ASK=1 brew uninstall --formula {{tap}}/{{cli_key}} 2>/dev/null || true
     brew install --formula {{tap}}/{{cli_key}}
     brew test {{cli_key}}
 
@@ -144,28 +139,12 @@ test-release:
 typecheck:
     bun run tsc --noEmit
 
-# Undo just install-local: agent artifacts first, then formula
-uninstall: uninstall-artifacts uninstall-formula
-
-# Remove agent artifacts only (skills, MCP)
-uninstall-artifacts:
-    just run configure --remove-all --yes
+# Undo dev/Homebrew install (formula uninstall hook runs configure --remove-all)
+uninstall:
+    @HOMEBREW_NO_ASK=1 brew uninstall --formula {{tap}}/{{cli_key}} 2>/dev/null || true
+    @HOMEBREW_NO_ASK=1 brew uninstall --formula {{tap}}/{{cli_key}}-local 2>/dev/null || true
+    @HOMEBREW_NO_ASK=1 brew untap {{tap}} 2>/dev/null || true
 
 # Remove app config file only
 uninstall-config:
     just run configure --remove-config --yes
-
-# Remove formula and untap
-uninstall-formula:
-    @NONINTERACTIVE=1 brew uninstall --formula {{tap}}/{{cli_key}} 2>/dev/null || true
-    @NONINTERACTIVE=1 brew uninstall --formula {{tap}}/{{cli_key}}-local 2>/dev/null || true
-    @NONINTERACTIVE=1 brew untap {{tap}} 2>/dev/null || true
-
-# Remove release formula (does not untap)
-uninstall-release:
-    @NONINTERACTIVE=1 brew uninstall --formula {{tap}}/{{cli_key}} 2>/dev/null || true
-
-# Remove release formula and untap
-uninstall-release-tap:
-    @NONINTERACTIVE=1 brew uninstall --formula {{tap}}/{{cli_key}} 2>/dev/null || true
-    @NONINTERACTIVE=1 brew untap {{tap}} 2>/dev/null || true

package/index.d.ts

@@ -909,6 +909,11 @@ export interface PackMcpBundleOpts {
  * Requires the compiled binary to exist.
  */
 export declare function packMcpBundle(program: CliProgram, opts?: PackMcpBundleOpts): string;
+/**
+ * Resolves the user home directory without depending on `$HOME`.
+ * This is helpful for when homebrew post-install hooks run with a temporary `$HOME`.
+ */
+export declare function userHome(): string;
 /** JSON-safe command node (no handlers). */
 export interface CliSchemaExport {
 	key: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "argsbarg",
-  "version": "6.3.0",
+  "version": "6.3.2",
   "main": "./src/index.ts",
   "module": "./src/index.ts",
   "dependencies": {

package/src/builtins/config.test.ts

@@ -30,8 +30,8 @@ describe("builtins/config", () => {
   /** Tests that config get redacts sensitive values. */
   test("config get redacts sensitive values", async () => {
     const dir = mkdtempSync(join(tmpdir(), "cfg-builtin-"));
-    const prevHome = process.env.HOME;
-    process.env.HOME = dir;
+    const prevTestHome = process.env.TEST_USER_HOME;
+    process.env.TEST_USER_HOME = dir;
     const prev = process.env.API_TOKEN;
     delete process.env.API_TOKEN;
     try {
@@ -43,8 +43,8 @@ describe("builtins/config", () => {
       expect(result.exitCode).toBe(0);
       expect(result.stdout.trim()).toBe("REDACTED");
     } finally {
-      if (prevHome === undefined) delete process.env.HOME;
-      else process.env.HOME = prevHome;
+      if (prevTestHome === undefined) delete process.env.TEST_USER_HOME;
+      else process.env.TEST_USER_HOME = prevTestHome;
       if (prev !== undefined) process.env.API_TOKEN = prev;
       rmSync(dir, { recursive: true, force: true });
     }
@@ -53,8 +53,8 @@ describe("builtins/config", () => {
   /** Tests that config get --json redacts sensitive as { set: true }. */
   test("config get --json redacts sensitive as { set: true }", async () => {
     const dir = mkdtempSync(join(tmpdir(), "cfg-builtin-"));
-    const prevHome = process.env.HOME;
-    process.env.HOME = dir;
+    const prevTestHome = process.env.TEST_USER_HOME;
+    process.env.TEST_USER_HOME = dir;
     const prev = process.env.API_TOKEN;
     delete process.env.API_TOKEN;
     try {
@@ -66,8 +66,8 @@ describe("builtins/config", () => {
       expect(result.exitCode).toBe(0);
       expect(JSON.parse(result.stdout)).toEqual({ set: true });
     } finally {
-      if (prevHome === undefined) delete process.env.HOME;
-      else process.env.HOME = prevHome;
+      if (prevTestHome === undefined) delete process.env.TEST_USER_HOME;
+      else process.env.TEST_USER_HOME = prevTestHome;
       if (prev !== undefined) process.env.API_TOKEN = prev;
       rmSync(dir, { recursive: true, force: true });
     }
@@ -76,8 +76,8 @@ describe("builtins/config", () => {
   /** Tests that config set writes and resolves without required exit. */
   test("config set writes and resolves without required exit", async () => {
     const dir = mkdtempSync(join(tmpdir(), "cfg-builtin-"));
-    const prevHome = process.env.HOME;
-    process.env.HOME = dir;
+    const prevTestHome = process.env.TEST_USER_HOME;
+    process.env.TEST_USER_HOME = dir;
     const prev = process.env.API_TOKEN;
     delete process.env.API_TOKEN;
     try {
@@ -88,8 +88,8 @@ describe("builtins/config", () => {
       const get = await new Cli(program).invoke(["configure", "get", "port"]);
       expect(get.stdout.trim()).toBe("9090");
     } finally {
-      if (prevHome === undefined) delete process.env.HOME;
-      else process.env.HOME = prevHome;
+      if (prevTestHome === undefined) delete process.env.TEST_USER_HOME;
+      else process.env.TEST_USER_HOME = prevTestHome;
       if (prev !== undefined) process.env.API_TOKEN = prev;
       rmSync(dir, { recursive: true, force: true });
     }
@@ -97,8 +97,8 @@ describe("builtins/config", () => {
 
   test("config set --from-env stores binding without literal", async () => {
     const dir = mkdtempSync(join(tmpdir(), "cfg-from-env-"));
-    const prevHome = process.env.HOME;
-    process.env.HOME = dir;
+    const prevTestHome = process.env.TEST_USER_HOME;
+    process.env.TEST_USER_HOME = dir;
     const prev = process.env.API_TOKEN;
     process.env.API_TOKEN = "from-env";
     try {
@@ -114,8 +114,8 @@ describe("builtins/config", () => {
       expect(onDisk.apiToken).toBeUndefined();
       expect(readBindings(onDisk).apiToken).toBe("env");
     } finally {
-      if (prevHome === undefined) delete process.env.HOME;
-      else process.env.HOME = prevHome;
+      if (prevTestHome === undefined) delete process.env.TEST_USER_HOME;
+      else process.env.TEST_USER_HOME = prevTestHome;
       if (prev === undefined) delete process.env.API_TOKEN;
       else process.env.API_TOKEN = prev;
       rmSync(dir, { recursive: true, force: true });

package/src/config/context.test.ts

@@ -29,8 +29,8 @@ describe("config/context", () => {
   /** Tests that AppConfigSnapshot get, require, read, set. */
   test("AppConfigSnapshot get, require, read, set", () => {
     const dir = mkdtempSync(join(tmpdir(), "ctx-test-"));
-    const prevHome = process.env.HOME;
-    process.env.HOME = dir;
+    const prevTestHome = process.env.TEST_USER_HOME;
+    process.env.TEST_USER_HOME = dir;
     const prevToken = process.env.API_TOKEN;
     delete process.env.API_TOKEN;
     try {
@@ -48,8 +48,8 @@ describe("config/context", () => {
       expect(ctx.get("note")).toBe("updated");
       expect(ctx.read().note).toBe("updated");
     } finally {
-      if (prevHome === undefined) delete process.env.HOME;
-      else process.env.HOME = prevHome;
+      if (prevTestHome === undefined) delete process.env.TEST_USER_HOME;
+      else process.env.TEST_USER_HOME = prevTestHome;
       if (prevToken === undefined) delete process.env.API_TOKEN;
       else process.env.API_TOKEN = prevToken;
       rmSync(dir, { recursive: true, force: true });
@@ -82,8 +82,8 @@ describe("config/context", () => {
 
   test("AppConfigSnapshot unsafe read/write", () => {
     const dir = mkdtempSync(join(tmpdir(), "ctx-unsafe-"));
-    const prevHome = process.env.HOME;
-    process.env.HOME = dir;
+    const prevTestHome = process.env.TEST_USER_HOME;
+    process.env.TEST_USER_HOME = dir;
     const prevToken = process.env.API_TOKEN;
     delete process.env.API_TOKEN;
     try {
@@ -95,8 +95,8 @@ describe("config/context", () => {
       ctx.setUnsafe("note", "raw");
       expect(ctx.getUnsafe("note")).toBe("raw");
     } finally {
-      if (prevHome === undefined) delete process.env.HOME;
-      else process.env.HOME = prevHome;
+      if (prevTestHome === undefined) delete process.env.TEST_USER_HOME;
+      else process.env.TEST_USER_HOME = prevTestHome;
       if (prevToken === undefined) delete process.env.API_TOKEN;
       else process.env.API_TOKEN = prevToken;
       rmSync(dir, { recursive: true, force: true });
@@ -105,8 +105,8 @@ describe("config/context", () => {
 
   test("EmptyAppConfigSnapshot unsafe read/write", () => {
     const dir = mkdtempSync(join(tmpdir(), "ctx-empty-unsafe-"));
-    const prevHome = process.env.HOME;
-    process.env.HOME = dir;
+    const prevTestHome = process.env.TEST_USER_HOME;
+    process.env.TEST_USER_HOME = dir;
     try {
       const programWithoutConfig: CliProgram = {
         key: "rawapp",
@@ -119,8 +119,8 @@ describe("config/context", () => {
       expect(empty.getUnsafe("custom")).toBe(42);
       expect(empty.readUnsafe().custom).toBe(42);
     } finally {
-      if (prevHome === undefined) delete process.env.HOME;
-      else process.env.HOME = prevHome;
+      if (prevTestHome === undefined) delete process.env.TEST_USER_HOME;
+      else process.env.TEST_USER_HOME = prevTestHome;
       rmSync(dir, { recursive: true, force: true });
     }
   });

package/src/config/file.test.ts

@@ -37,13 +37,13 @@ const program: CliProgram = {
 
 function withHome<T>(fn: (home: string) => T): T {
   const home = mkdtempSync(join(tmpdir(), "cfg-test-"));
-  const prevHome = process.env.HOME;
-  process.env.HOME = home;
+  const prevTestHome = process.env.TEST_USER_HOME;
+  process.env.TEST_USER_HOME = home;
   try {
     return fn(home);
   } finally {
-    if (prevHome === undefined) delete process.env.HOME;
-    else process.env.HOME = prevHome;
+    if (prevTestHome === undefined) delete process.env.TEST_USER_HOME;
+    else process.env.TEST_USER_HOME = prevTestHome;
     rmSync(home, { recursive: true, force: true });
   }
 }

package/src/configure/artifacts/binary-placement.test.ts

@@ -84,14 +84,14 @@ describe("isAppInstalled", () => {
   /** Tests that false when not on PATH and no local copy. */
   test("false when not on PATH and no local copy", () => {
     const home = mkdtempSync(join(tmpdir(), "argsbarg-placement-home-"));
-    const prevHome = process.env.HOME;
-    process.env.HOME = home;
+    const prevTestHome = process.env.TEST_USER_HOME;
+    process.env.TEST_USER_HOME = home;
     process.env.PATH = tmp;
     try {
       expect(isAppInstalled(program)).toBe(false);
     } finally {
-      if (prevHome === undefined) delete process.env.HOME;
-      else process.env.HOME = prevHome;
+      if (prevTestHome === undefined) delete process.env.TEST_USER_HOME;
+      else process.env.TEST_USER_HOME = prevTestHome;
       rmSync(home, { recursive: true, force: true });
     }
   });

package/src/configure/artifacts/mcp-codex.test.ts

@@ -9,17 +9,17 @@ import { join } from "node:path";
 import { codexMcpHasServer, readCodexMcpEntry, resolveCodexConfigPath } from "./mcp-codex.ts";
 
 let home: string;
-let prevHome: string | undefined;
+let prevTestHome: string | undefined;
 
 beforeEach(() => {
   home = mkdtempSync(join(tmpdir(), "argsbarg-codex-"));
-  prevHome = process.env.HOME;
-  process.env.HOME = home;
+  prevTestHome = process.env.TEST_USER_HOME;
+  process.env.TEST_USER_HOME = home;
 });
 
 afterEach(() => {
-  if (prevHome === undefined) delete process.env.HOME;
-  else process.env.HOME = prevHome;
+  if (prevTestHome === undefined) delete process.env.TEST_USER_HOME;
+  else process.env.TEST_USER_HOME = prevTestHome;
   rmSync(home, { recursive: true, force: true });
 });
 

package/src/configure/artifacts/mcp-openclaw.test.ts

@@ -9,17 +9,17 @@ import { join } from "node:path";
 import { openclawMcpHasServer, resolveOpenclawConfigPath } from "./mcp-openclaw.ts";
 
 let home: string;
-let prevHome: string | undefined;
+let prevTestHome: string | undefined;
 
 beforeEach(() => {
   home = mkdtempSync(join(tmpdir(), "argsbarg-openclaw-"));
-  prevHome = process.env.HOME;
-  process.env.HOME = home;
+  prevTestHome = process.env.TEST_USER_HOME;
+  process.env.TEST_USER_HOME = home;
 });
 
 afterEach(() => {
-  if (prevHome === undefined) delete process.env.HOME;
-  else process.env.HOME = prevHome;
+  if (prevTestHome === undefined) delete process.env.TEST_USER_HOME;
+  else process.env.TEST_USER_HOME = prevTestHome;
   rmSync(home, { recursive: true, force: true });
 });
 

package/src/configure/artifacts/mcp-opencode.test.ts

@@ -26,20 +26,20 @@ const fixture: CliProgram = {
 };
 
 let home: string;
-let prevHome: string | undefined;
+let prevTestHome: string | undefined;
 let prevXdg: string | undefined;
 
 beforeEach(() => {
   home = mkdtempSync(join(tmpdir(), "argsbarg-opencode-"));
-  prevHome = process.env.HOME;
+  prevTestHome = process.env.TEST_USER_HOME;
   prevXdg = process.env.XDG_CONFIG_HOME;
-  process.env.HOME = home;
+  process.env.TEST_USER_HOME = home;
   delete process.env.XDG_CONFIG_HOME;
 });
 
 afterEach(() => {
-  if (prevHome === undefined) delete process.env.HOME;
-  else process.env.HOME = prevHome;
+  if (prevTestHome === undefined) delete process.env.TEST_USER_HOME;
+  else process.env.TEST_USER_HOME = prevTestHome;
   if (prevXdg === undefined) delete process.env.XDG_CONFIG_HOME;
   else process.env.XDG_CONFIG_HOME = prevXdg;
   rmSync(home, { recursive: true, force: true });

package/src/configure/artifacts/status.test.ts

@@ -12,17 +12,17 @@ import { printInstallStatus } from "./status.ts";
 import { resolveInstallTargetPreview } from "./target-scope.ts";
 
 let home: string;
-let prevHome: string | undefined;
+let prevTestHome: string | undefined;
 
 beforeEach(() => {
   home = mkdtempSync(join(tmpdir(), "argsbarg-status-"));
-  prevHome = process.env.HOME;
-  process.env.HOME = home;
+  prevTestHome = process.env.TEST_USER_HOME;
+  process.env.TEST_USER_HOME = home;
 });
 
 afterEach(() => {
-  if (prevHome === undefined) delete process.env.HOME;
-  else process.env.HOME = prevHome;
+  if (prevTestHome === undefined) delete process.env.TEST_USER_HOME;
+  else process.env.TEST_USER_HOME = prevTestHome;
   rmSync(home, { recursive: true, force: true });
 });
 

package/src/configure/configure.test.ts

@@ -33,20 +33,20 @@ const fixture: CliProgram = {
 };
 
 let home: string;
-let prevHome: string | undefined;
+let prevTestHome: string | undefined;
 let prevXdg: string | undefined;
 
 beforeEach(() => {
   home = mkdtempSync(join(tmpdir(), "argsbarg-configure-"));
-  prevHome = process.env.HOME;
+  prevTestHome = process.env.TEST_USER_HOME;
   prevXdg = process.env.XDG_CONFIG_HOME;
-  process.env.HOME = home;
+  process.env.TEST_USER_HOME = home;
   delete process.env.XDG_CONFIG_HOME;
 });
 
 afterEach(() => {
-  if (prevHome === undefined) delete process.env.HOME;
-  else process.env.HOME = prevHome;
+  if (prevTestHome === undefined) delete process.env.TEST_USER_HOME;
+  else process.env.TEST_USER_HOME = prevTestHome;
   if (prevXdg === undefined) delete process.env.XDG_CONFIG_HOME;
   else process.env.XDG_CONFIG_HOME = prevXdg;
   rmSync(home, { recursive: true, force: true });

package/src/core/parse.test.ts

@@ -1212,20 +1212,20 @@ test("cliSkillInstall writes project agent skill files", () => {
   }
 });
 
-/** CliSkillInstall global uses HOME agents skills directory. */
-test("cliSkillInstall global uses HOME agents skills directory", () => {
+/** CliSkillInstall global uses TEST_USER_HOME agents skills directory. */
+test("cliSkillInstall global uses TEST_USER_HOME agents skills directory", () => {
   const home = mkdtempSync(join(tmpdir(), "argsbarg-home-"));
-  const prevHome = process.env.HOME;
-  process.env.HOME = home;
+  const prevTestHome = process.env.TEST_USER_HOME;
+  process.env.TEST_USER_HOME = home;
   try {
     const files = cliSkillInstall(nestedMcpFixture, { global: true, rimraf: true });
     expect(files.some((f) => f.includes(join(home, ".agents", "skills", "nested.ts")))).toBe(true);
     expect(existsSync(join(home, ".agents", "skills", "nested.ts", "SKILL.md"))).toBe(true);
   } finally {
-    if (prevHome === undefined) {
-      delete process.env.HOME;
+    if (prevTestHome === undefined) {
+      delete process.env.TEST_USER_HOME;
     } else {
-      process.env.HOME = prevHome;
+      process.env.TEST_USER_HOME = prevTestHome;
     }
     rmSync(home, { recursive: true, force: true });
   }

package/src/index.ts

@@ -84,6 +84,7 @@ export type { EcsLogEvent, LogEnrichContext } from "./log/ecs.ts";
 export { ECS_VERSION, formatEcsLine } from "./log/ecs.ts";
 export type { McpBundlePaths, PackMcpBundleOpts } from "./mcp/bundle.ts";
 export { defaultMcpBundlePaths, generateMcpManifest, packMcpBundle } from "./mcp/bundle.ts";
+export { userHome } from "./paths/host.ts";
 export { Cli, type CliInvokeKind, type CliInvokeResult } from "./runtime/cli.ts";
 export { cliErrWithHelp } from "./runtime/cli-errors.ts";
 export { isInteractiveTty } from "./utils.ts";

package/src/paths/host.test.ts

@@ -0,0 +1,58 @@
+/*
+Tests for paths/host module behavior.
+*/
+
+import { afterEach, describe, expect, test } from "bun:test";
+import { existsSync, mkdtempSync, rmSync } from "node:fs";
+import { tmpdir, userInfo } from "node:os";
+import { join } from "node:path";
+import { userHome } from "./host.ts";
+
+describe("userHome", () => {
+  let prevTestHome: string | undefined;
+
+  afterEach(() => {
+    if (prevTestHome === undefined) delete process.env.TEST_USER_HOME;
+    else process.env.TEST_USER_HOME = prevTestHome;
+  });
+
+  test("uses TEST_USER_HOME when set", () => {
+    const home = mkdtempSync(join(tmpdir(), "argsbarg-test-home-"));
+    prevTestHome = process.env.TEST_USER_HOME;
+    process.env.TEST_USER_HOME = home;
+    try {
+      expect(userHome()).toBe(home);
+    } finally {
+      rmSync(home, { recursive: true, force: true });
+    }
+  });
+
+  test("ignores sandboxed HOME (Homebrew post_install)", () => {
+    prevTestHome = process.env.TEST_USER_HOME;
+    delete process.env.TEST_USER_HOME;
+    const prevHome = process.env.HOME;
+    process.env.HOME = "/private/tmp/sqsp-workspaces-postinstall-20260807-fake";
+    try {
+      const resolved = userHome();
+      expect(resolved).not.toBe(process.env.HOME);
+      if (process.platform === "darwin" && process.env.USER) {
+        expect(resolved).toBe(`/Users/${process.env.USER}`);
+        expect(existsSync(resolved)).toBe(true);
+      } else {
+        expect(resolved).toBe(userInfo().homedir);
+      }
+    } finally {
+      if (prevHome === undefined) delete process.env.HOME;
+      else process.env.HOME = prevHome;
+    }
+  });
+
+  test("resolves macOS default home when TEST_USER_HOME unset", () => {
+    prevTestHome = process.env.TEST_USER_HOME;
+    delete process.env.TEST_USER_HOME;
+    if (process.platform !== "darwin" || !process.env.USER) return;
+    const expected = `/Users/${process.env.USER}`;
+    if (!existsSync(expected)) return;
+    expect(userHome()).toBe(expected);
+  });
+});

package/src/paths/host.ts

@@ -2,12 +2,21 @@
 Shared host path primitives for install, config, and skill modules.
 */
 
-import { homedir } from "node:os";
+import { existsSync } from "node:fs";
+import { userInfo } from "node:os";
 import { join } from "node:path";
 
-/** Resolves the user home directory (`$HOME` when set). */
+/**
+ * Resolves the user home directory without depending on `$HOME`.
+ * This is helpful for when homebrew post-install hooks run with a temporary `$HOME`.
+ */
 export function userHome(): string {
-  return process.env.HOME ?? homedir();
+  const user = process.env.USER ?? process.env.LOGNAME;
+  return (
+    [process.env.TEST_USER_HOME, user && `/Users/${user}`, user && `/home/${user}`, process.env.USERPROFILE].find(
+      (p) => p && existsSync(p),
+    ) ?? userInfo().homedir
+  );
 }
 
 /** Expands a leading `~` or `~/` in a path using {@link userHome}. */

package/src/test/integration/config.test.ts

@@ -13,8 +13,8 @@ import { mcpRequest, testProgram } from "../fixtures.ts";
 /** Tests that bootstrapAppConfig prefers host env over config file. */
 test("bootstrapAppConfig prefers host env over config file", () => {
   const dir = mkdtempSync(join(tmpdir(), "argsbarg-env-"));
-  const prevHome = process.env.HOME;
-  process.env.HOME = dir;
+  const prevTestHome = process.env.TEST_USER_HOME;
+  process.env.TEST_USER_HOME = dir;
   process.env.FOO = "original";
   try {
     const p = testProgram({
@@ -36,8 +36,8 @@ test("bootstrapAppConfig prefers host env over config file", () => {
     expect(process.env.FOO).toBe("original");
     expect(process.env.BAR).toBe("bar");
   } finally {
-    if (prevHome === undefined) delete process.env.HOME;
-    else process.env.HOME = prevHome;
+    if (prevTestHome === undefined) delete process.env.TEST_USER_HOME;
+    else process.env.TEST_USER_HOME = prevTestHome;
     delete process.env.FOO;
     delete process.env.BAR;
     rmSync(dir, { recursive: true, force: true });
@@ -106,7 +106,7 @@ test("MCP config file loads and exports vars for tool handlers", async () => {
     ],
     {
       script: "src/test/mcp-integration-fixture.ts",
-      env: { HOME: dir, ARGS_TEST_SECRET: "present" },
+      env: { TEST_USER_HOME: dir, ARGS_TEST_SECRET: "present" },
     },
   );
   const res = responses.get(15) as {
@@ -148,7 +148,7 @@ const program = {
 await new Cli(program).run(process.argv.slice(2));
 `,
   );
-  const env = { ...process.env, HOME: dir } as Record<string, string | undefined>;
+  const env = { ...process.env, TEST_USER_HOME: dir } as Record<string, string | undefined>;
   delete env.DOCS_SKIP_RUN_TOKEN;
   try {
     const proc = Bun.spawn(["bun", "run", mainPath, "docs", "cli"], {