Skip to content

The cross-harness, self-improving memory layer for AI agents. Join our community: https://discord.com/invite/zdNChS2fBu

fix(qwen): resolve user settings through QWEN_HOME (#925)

Rudy Mizrahi Celekliead9da70b4c2
diff --git a/cli/beacon/cmd/endpoint_hooks_test.go b/cli/beacon/cmd/endpoint_hooks_test.go
index d3394105..bdf31c40 100644
--- a/cli/beacon/cmd/endpoint_hooks_test.go
+++ b/cli/beacon/cmd/endpoint_hooks_test.go
@@ -54,6 +54,7 @@ func TestEndpointHooksInstallAndUninstallQwen(t *testing.T) {
home := t.TempDir()
t.Setenv("HOME", home)
t.Setenv("USERPROFILE", home)
+ t.Setenv("QWEN_HOME", "")
cfg := endpointconfig.Config{LogPath: filepath.Join(home, "runtime.jsonl"), UserMode: true}
origLevel := endpointOpts.hookLevel
diff --git a/cli/beacon/internal/endpoint/dashboard/hooks_status_test.go b/cli/beacon/internal/endpoint/dashboard/hooks_status_test.go
index 3b55710b..f80ab36f 100644
--- a/cli/beacon/internal/endpoint/dashboard/hooks_status_test.go
+++ b/cli/beacon/internal/endpoint/dashboard/hooks_status_test.go
@@ -63,6 +63,7 @@ func TestHookStatusesReportQwenWithItsSettingsPath(t *testing.T) {
home := t.TempDir()
t.Setenv("HOME", home)
t.Setenv("USERPROFILE", home)
+ t.Setenv("QWEN_HOME", "")
rows := 0
for _, status := range hookStatuses(filepath.Join(t.TempDir(), "runtime.jsonl"), true) {
diff --git a/cli/beacon/internal/endpoint/harness/qwen.go b/cli/beacon/internal/endpoint/harness/qwen.go
index a43c6135..78ccd1a9 100644
--- a/cli/beacon/internal/endpoint/harness/qwen.go
+++ b/cli/beacon/internal/endpoint/harness/qwen.go
@@ -3,7 +3,6 @@ package harness
import (
"encoding/json"
"os"
- "path/filepath"
"strings"
"github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/hooks"
@@ -34,11 +33,11 @@ func DiscoverQwen() Harness {
h.ConfigPath = settingsPath
// Qwen Code installs through npm, and a version manager, a shell alias or a per-project install
- // all hide the binary from the PATH this process inherited while ~/.qwen is still there.
- // Treating that directory as evidence keeps `endpoint discover` from reporting "not detected"
- // for a runtime the user is actively using -- the same fallback the opencode, Cursor, Pi and
- // Hermes probes make for the same reason.
- if !h.Detected && dirExists(filepath.Join(home, ".qwen")) {
+ // all hide the binary from the PATH this process inherited while Qwen's directory (~/.qwen, or
+ // QWEN_HOME when set) is still there. Treating that directory as evidence keeps `endpoint
+ // discover` from reporting "not detected" for a runtime the user is actively using -- the same fallback the
+ // opencode, Cursor, Pi and Hermes probes make for the same reason.
+ if dir, err := hooks.QwenUserDir(home); err == nil && !h.Detected && dirExists(dir) {
h.Detected = true
}
diff --git a/cli/beacon/internal/endpoint/harness/qwen_test.go b/cli/beacon/internal/endpoint/harness/qwen_test.go
index 552b91b5..d11b9949 100644
--- a/cli/beacon/internal/endpoint/harness/qwen_test.go
+++ b/cli/beacon/internal/endpoint/harness/qwen_test.go
@@ -36,6 +36,7 @@ func TestDiscoverAllIncludesQwen(t *testing.T) {
func TestDiscoverQwenDetectsConfigDirectoryWithoutAnExecutable(t *testing.T) {
home := t.TempDir()
testenv.SetHome(t, home)
+ t.Setenv("QWEN_HOME", "")
t.Setenv("PATH", t.TempDir())
if err := os.MkdirAll(filepath.Join(home, ".qwen"), 0755); err != nil {
t.Fatalf("mkdir qwen config dir: %v", err)
@@ -129,3 +130,35 @@ func TestDiscoverQwenDoesNotFallBackToTheProjectPath(t *testing.T) {
t.Fatalf("TelemetryStatus = enabled from a project settings file: %#v", h)
}
}
+
+// With QWEN_HOME set, Qwen Code's directory is that one, so it is the one whose presence counts as
+// evidence of the runtime and whose settings.json discovery reports.
+func TestDiscoverQwenHonorsQwenHome(t *testing.T) {
+ home := t.TempDir()
+ testenv.SetHome(t, home)
+ t.Setenv("PATH", t.TempDir())
+ qwenHome := filepath.Join(t.TempDir(), "qwen-moved")
+ t.Setenv("QWEN_HOME", qwenHome)
+ if err := os.MkdirAll(qwenHome, 0755); err != nil {
+ t.Fatalf("mkdir QWEN_HOME: %v", err)
+ }
+
+ h := DiscoverQwen()
+ if !h.Detected {
+ t.Fatalf("DiscoverQwen did not detect Qwen Code from its QWEN_HOME directory: %#v", h)
+ }
+ if want := filepath.Join(qwenHome, "settings.json"); h.ConfigPath != want {
+ t.Fatalf("ConfigPath = %q, want %q", h.ConfigPath, want)
+ }
+
+ // A stale ~/.qwen is not evidence of anything once QWEN_HOME points elsewhere.
+ if err := os.RemoveAll(qwenHome); err != nil {
+ t.Fatal(err)
+ }
+ if err := os.MkdirAll(filepath.Join(home, ".qwen"), 0755); err != nil {
+ t.Fatal(err)
+ }
+ if h := DiscoverQwen(); h.Detected {
+ t.Fatalf("DiscoverQwen detected Qwen Code from ~/.qwen with QWEN_HOME set elsewhere: %#v", h)
+ }
+}
diff --git a/cli/beacon/internal/endpoint/hooks/omo.go b/cli/beacon/internal/endpoint/hooks/omo.go
index 03a8741c..9e5ff71c 100644
--- a/cli/beacon/internal/endpoint/hooks/omo.go
+++ b/cli/beacon/internal/endpoint/hooks/omo.go
@@ -4,9 +4,9 @@ import (
"fmt"
"os"
"path/filepath"
- "strings"
omoextension "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/hooks/assets/omo"
+ "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/homepath"
)
// Senpi is the standalone edition of oh-my-openagent (OMO): an in-flight fork of pi-mono
@@ -198,7 +198,7 @@ func omoExtensionDir(home string, level Level) (string, error) {
switch level {
case "", LevelUser:
if agentDir := omoAgentDirOverride(); agentDir != "" {
- expanded, err := omoExpandTilde(agentDir, home)
+ expanded, err := homepath.ExpandTilde(agentDir, home)
if err != nil {
return "", err
}
@@ -218,22 +218,3 @@ func omoExtensionDir(home string, level Level) (string, error) {
return "", fmt.Errorf("unknown hook level %q", level)
}
}
-
-// omoExpandTilde resolves a leading `~` in the agent-directory override.
-//
-// Senpi expands it itself before using the value, so a Beacon install that did not would create a
-// literal `~` directory beside the working directory and report success while the runtime kept
-// reading the real home. Only a bare `~` or a `~/`-rooted path is expanded, which is the runtime's
-// own rule -- `~user/...` is left alone by both.
-func omoExpandTilde(path, home string) (string, error) {
- if path != "~" && !strings.HasPrefix(path, "~/") && !strings.HasPrefix(path, `~\`) {
- return path, nil
- }
- if home == "" {
- return "", fmt.Errorf("home directory is required to resolve %q", path)
- }
- if path == "~" {
- return home, nil
- }
- return filepath.Join(home, filepath.FromSlash(path[2:])), nil
-}
diff --git a/cli/beacon/internal/endpoint/hooks/prime.go b/cli/beacon/internal/endpoint/hooks/prime.go
index cf1a0ce0..6c707135 100644
--- a/cli/beacon/internal/endpoint/hooks/prime.go
+++ b/cli/beacon/internal/endpoint/hooks/prime.go
@@ -4,9 +4,9 @@ import (
"fmt"
"os"
"path/filepath"
- "strings"
primeextension "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/hooks/assets/prime"
+ "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/homepath"
)
// Prime Agent (Prime Intellect) is integrated the same shape as Pi, which it forked: no hooks
@@ -161,7 +161,7 @@ func primeExtensionDir(home string, level Level) (string, error) {
switch level {
case "", LevelUser:
if agentDir := os.Getenv(primeAgentDirEnv); agentDir != "" {
- expanded, err := primeExpandTilde(agentDir, home)
+ expanded, err := homepath.ExpandTilde(agentDir, home)
if err != nil {
return "", err
}
@@ -181,22 +181,3 @@ func primeExtensionDir(home string, level Level) (string, error) {
return "", fmt.Errorf("unknown hook level %q", level)
}
}
-
-// primeExpandTilde resolves a leading `~` in the agent-directory override.
-//
-// Prime Agent expands it itself before using the value, so a Beacon install that did not would
-// create a literal `~` directory beside the working directory and report success while the runtime
-// kept reading the real home. Only a bare `~` or a `~/`-rooted path is expanded, which is the
-// runtime's own rule -- `~user/...` is left alone by both.
-func primeExpandTilde(path, home string) (string, error) {
- if path != "~" && !strings.HasPrefix(path, "~/") && !strings.HasPrefix(path, `~\`) {
- return path, nil
- }
- if home == "" {
- return "", fmt.Errorf("home directory is required to resolve %s=%q", primeAgentDirEnv, path)
- }
- if path == "~" {
- return home, nil
- }
- return filepath.Join(home, filepath.FromSlash(path[2:])), nil
-}
diff --git a/cli/beacon/internal/endpoint/hooks/qwen.go b/cli/beacon/internal/endpoint/hooks/qwen.go
index eeae5890..0782fcad 100644
--- a/cli/beacon/internal/endpoint/hooks/qwen.go
+++ b/cli/beacon/internal/endpoint/hooks/qwen.go
@@ -5,6 +5,8 @@ import (
"os"
"path/filepath"
"strings"
+
+ "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/homepath"
)
// Qwen Code hook timeouts are milliseconds.
@@ -157,12 +159,37 @@ func isQwenInstalledAt(path string) bool {
return isSettingsEndpointInstalledAt(path, "qwen")
}
+// qwenHomeEnv moves Qwen Code's user directory. Qwen reads it in getGlobalQwenDir
+// (packages/core/src/config/storage.ts) and keeps settings.json directly inside it.
+const qwenHomeEnv = "QWEN_HOME"
+
+// QwenUserDir returns Qwen Code's user directory for the given home directory.
+//
+// Qwen uses QWEN_HOME whenever it is non-empty: a leading `~` is expanded against the home
+// directory and a relative path is made absolute, but nothing is trimmed and no `.qwen` is
+// appended. Otherwise it is `.qwen` under the home directory. The home directory is only needed
+// for the default and for a `~` override, so an absolute QWEN_HOME resolves without one.
+func QwenUserDir(home string) (string, error) {
+ if override := os.Getenv(qwenHomeEnv); override != "" {
+ dir, err := homepath.ExpandTilde(override, home)
+ if err != nil {
+ return "", fmt.Errorf("resolve %s: %w", qwenHomeEnv, err)
+ }
+ return filepath.Abs(dir)
+ }
+ if home == "" {
+ return "", fmt.Errorf("home directory is required to resolve Qwen Code's directory")
+ }
+ return filepath.Join(home, ".qwen"), nil
+}
+
// QwenSettingsPath returns the settings file Beacon merges into for a given install level.
//
-// Qwen Code resolves settings from `~/.qwen/settings.json` for the user and `.qwen/settings.json`
-// in the project root, with project settings taking precedence. The user level is the default here
-// for the same reason it is elsewhere: a project-level install only takes effect once the folder is
-// trusted, so it is the one that needs a caveat rather than the one to reach for first.
+// Qwen Code resolves settings from `settings.json` in its user directory (`~/.qwen`, or QWEN_HOME
+// when that is set) and `.qwen/settings.json` in the project root, with project settings taking
+// precedence. The user level is the default here for the same reason it is elsewhere: a
+// project-level install only takes effect once the folder is trusted, so it is the one that needs
+// a caveat rather than the one to reach for first.
//
// Exported because `harness` reports on the same file and must not rebuild the path itself. Two
// copies of "where the settings live" is how discovery comes to report on a file the installer does
@@ -170,13 +197,26 @@ func isQwenInstalledAt(path string) bool {
// user path into the *project* path, so discovery would read whatever repository the command ran
// from and report it as the machine's state.
func QwenSettingsPath(level Level) (string, error) {
+ if level == "" || level == LevelUser {
+ home, err := os.UserHomeDir()
+ if err != nil && os.Getenv(qwenHomeEnv) == "" {
+ return "", err
+ }
+ return QwenSettingsPathForHome(level, home)
+ }
+ return QwenSettingsPathForHome(level, "")
+}
+
+// QwenSettingsPathForHome is QwenSettingsPath for a caller that already knows the home directory,
+// as the inventory scan does.
+func QwenSettingsPathForHome(level Level, home string) (string, error) {
switch level {
case "", LevelUser:
- home, err := os.UserHomeDir()
+ dir, err := QwenUserDir(home)
if err != nil {
return "", err
}
- return filepath.Join(home, ".qwen", "settings.json"), nil
+ return filepath.Join(dir, "settings.json"), nil
case LevelProject:
cwd, err := os.Getwd()
if err != nil {
diff --git a/cli/beacon/internal/endpoint/hooks/qwen_test.go b/cli/beacon/internal/endpoint/hooks/qwen_test.go
index 23e09f7d..8986385d 100644
--- a/cli/beacon/internal/endpoint/hooks/qwen_test.go
+++ b/cli/beacon/internal/endpoint/hooks/qwen_test.go
@@ -302,6 +302,7 @@ func TestQwenDetectionDoesNotClaimAnotherRuntimesHooks(t *testing.T) {
func TestQwenSettingsPathUserAndProjectLevels(t *testing.T) {
home := t.TempDir()
testenv.SetHome(t, home)
+ t.Setenv("QWEN_HOME", "")
userPath, err := QwenSettingsPath(LevelUser)
if err != nil {
@@ -347,6 +348,7 @@ func TestQwenProjectInstallSaysItNeedsATrustedFolder(t *testing.T) {
func TestQwenHookStatusDetectsAnInstall(t *testing.T) {
home := t.TempDir()
testenv.SetHome(t, home)
+ t.Setenv("QWEN_HOME", "")
path := filepath.Join(home, ".qwen", "settings.json")
if err := os.MkdirAll(filepath.Dir(path), 0755); err != nil {
t.Fatal(err)
@@ -468,3 +470,59 @@ func TestOnlyQwenDeclaresAHookShell(t *testing.T) {
t.Fatalf("Claude settings carry a shell field:\n%s", got)
}
}
+
+// Qwen Code keeps its user directory under QWEN_HOME when that is set (getGlobalQwenDir in
+// packages/core/src/config/storage.ts): a leading `~` is expanded, a relative path is made absolute
+// and the directory is used as is, with no `.qwen` appended. An install that wrote ~/.qwen would
+// report success while Qwen kept reading the moved directory.
+func TestQwenSettingsPathHonorsQwenHome(t *testing.T) {
+ home := t.TempDir()
+ testenv.SetHome(t, home)
+ project := t.TempDir()
+ t.Chdir(project)
+ cwd, err := os.Getwd()
+ if err != nil {
+ t.Fatal(err)
+ }
+
+ moved := filepath.Join(t.TempDir(), "qwen-moved")
+ for name, tc := range map[string]struct{ value, want string }{
+ "absolute": {moved, filepath.Join(moved, "settings.json")},
+ "tilde": {"~/qwen-alt", filepath.Join(home, "qwen-alt", "settings.json")},
+ "relative": {"qwen-rel", filepath.Join(cwd, "qwen-rel", "settings.json")},
+ } {
+ t.Run(name, func(t *testing.T) {
+ t.Setenv("QWEN_HOME", tc.value)
+ got, err := QwenSettingsPath(LevelUser)
+ if err != nil || got != tc.want {
+ t.Fatalf("QwenSettingsPath(user) = %q, %v; want %q", got, err, tc.want)
+ }
+ if forHome, err := QwenSettingsPathForHome(LevelUser, home); err != nil || forHome != tc.want {
+ t.Fatalf("QwenSettingsPathForHome(user) = %q, %v; want %q", forHome, err, tc.want)
+ }
+ // The project file never moves.
+ projectPath, err := QwenSettingsPath(LevelProject)
+ if want := filepath.Join(cwd, ".qwen", "settings.json"); err != nil || projectPath != want {
+ t.Fatalf("QwenSettingsPath(project) = %q, %v; want %q", projectPath, err, want)
+ }
+ })
+ }
+
+ // The installer and the status check both go through the same resolver, so a hook written under
+ // QWEN_HOME is the one that is reported.
+ t.Setenv("QWEN_HOME", moved)
+ want := filepath.Join(moved, "settings.json")
+ if err := os.MkdirAll(moved, 0755); err != nil {
+ t.Fatal(err)
+ }
+ if err := os.WriteFile(want, []byte(`{"hooks":{"Stop":[{"hooks":[{"type":"command","command":"'/tmp/beacon-hooks' --platform qwen --log '/tmp/runtime.jsonl' stop"}]}]}}`), 0600); err != nil {
+ t.Fatal(err)
+ }
+ status := QwenHookStatus(QwenOptions{Level: LevelUser, UserMode: true})
+ if !status.Installed || status.SettingsPath != want {
+ t.Fatalf("QwenHookStatus = %#v, want installed at %q", status, want)
+ }
+ if configured, err := qwenRuntime.configPath(LevelUser); err != nil || configured != want {
+ t.Fatalf("installer config path = %q, %v; want %q", configured, err, want)
+ }
+}
diff --git a/cli/beacon/internal/endpoint/inventory/inventory.go b/cli/beacon/internal/endpoint/inventory/inventory.go
index 8b98a308..54f527da 100644
--- a/cli/beacon/internal/endpoint/inventory/inventory.go
+++ b/cli/beacon/internal/endpoint/inventory/inventory.go
@@ -525,11 +525,14 @@ func devinCandidates(home, wd string) []candidate {
// native config file that Beacon merges into rather than a file Beacon owns. That is why it is
// classified KindHookConfig and detected by the hook command it contains rather than by a
// Beacon-managed marker: there is no marker to write into a file the user also edits.
+//
+// The user file follows QWEN_HOME, as Qwen Code does, through the same resolver the installer uses.
func qwenCandidates(home, wd string) []candidate {
- return []candidate{
- {runtime: "qwen_code", path: filepath.Join(home, ".qwen", "settings.json"), scope: ScopeUser, format: formatJSON, kind: KindHookConfig},
- {runtime: "qwen_code", path: filepath.Join(wd, ".qwen", "settings.json"), scope: ScopeProject, format: formatJSON, kind: KindHookConfig},
+ items := []candidate{}
+ if path, err := hooks.QwenSettingsPathForHome(hooks.LevelUser, home); err == nil {
+ items = append(items, candidate{runtime: "qwen_code", path: path, scope: ScopeUser, format: formatJSON, kind: KindHookConfig})
}
+ return append(items, candidate{runtime: "qwen_code", path: filepath.Join(wd, ".qwen", "settings.json"), scope: ScopeProject, format: formatJSON, kind: KindHookConfig})
}
// Muse Code is two files: the managed hooks file Beacon owns outright, and Muse's own settings.json,
diff --git a/cli/beacon/internal/endpoint/inventory/inventory_test.go b/cli/beacon/internal/endpoint/inventory/inventory_test.go
index 895fab48..c9798281 100644
--- a/cli/beacon/internal/endpoint/inventory/inventory_test.go
+++ b/cli/beacon/internal/endpoint/inventory/inventory_test.go
@@ -490,6 +490,24 @@ func TestScanReadsGeminiSettingsFromGeminiCLIHome(t *testing.T) {
}
}
+// With QWEN_HOME set, the Qwen Code settings inventory reads are the ones Qwen reads.
+func TestScanReadsQwenSettingsFromQwenHome(t *testing.T) {
+ home := t.TempDir()
+ qwenHome := t.TempDir()
+ t.Setenv("QWEN_HOME", qwenHome)
+ writeFile(t, filepath.Join(qwenHome, "settings.json"), `{"mcpServers":{"github":{"command":"gh"}}}`)
+ writeFile(t, filepath.Join(home, ".qwen", "settings.json"), `{"mcpServers":{"stale":{"command":"old"}}}`)
+
+ result := Scan(Options{HomeDir: home, SkipProjectScope: true, Runtimes: []string{"qwen_code"}, Now: fixedNow})
+ config := findConfig(result.Configs, "qwen_code", filepath.Join(qwenHome, "settings.json"))
+ if config == nil || !config.Exists {
+ t.Fatalf("QWEN_HOME settings.json = %#v, want it read", config)
+ }
+ if stale := findConfig(result.Configs, "qwen_code", filepath.Join(home, ".qwen", "settings.json")); stale != nil {
+ t.Fatalf("inventory reported ~/.qwen/settings.json, which Qwen does not read with QWEN_HOME set: %#v", stale)
+ }
+}
+
// With CLAUDE_CONFIG_DIR set, the Claude Code files inventory reads are the ones Claude Code reads:
// settings.json, .claude.json and skills all move with it.
func TestScanReadsClaudeUserFilesFromClaudeConfigDir(t *testing.T) {
@@ -544,6 +562,8 @@ func TestScanIncludesAllSupportedCurrentUserAndProjectConfigs(t *testing.T) {
t.Setenv("CODEX_HOME", "")
t.Setenv("CLINE_DIR", "")
t.Setenv("GEMINI_CLI_HOME", "")
+ // Qwen Code's settings.json follows QWEN_HOME.
+ t.Setenv("QWEN_HOME", "")
// Hermes's config.yaml follows HERMES_HOME, its data-dir suffix and, on Windows, LOCALAPPDATA.
hermesRoot := hermesDefaultRoot(t, home)
diff --git a/cli/beacon/internal/endpoint/lifecycle/inventory_job_test.go b/cli/beacon/internal/endpoint/lifecycle/inventory_job_test.go
index f459dc38..564e8c12 100644
--- a/cli/beacon/internal/endpoint/lifecycle/inventory_job_test.go
+++ b/cli/beacon/internal/endpoint/lifecycle/inventory_job_test.go
@@ -557,6 +557,7 @@ func TestInventoryJobEnvRecordsTheOtherInventoryRootVariables(t *testing.T) {
"PI_CONFIG_DIR": ".omp-alt",
"OMP_PROFILE": "",
"PI_PROFILE": "work",
+ "QWEN_HOME": "qwen-alt",
}
for name, value := range set {
t.Setenv(name, value)
@@ -570,6 +571,7 @@ func TestInventoryJobEnvRecordsTheOtherInventoryRootVariables(t *testing.T) {
"PI_CONFIG_DIR": ".omp-alt",
"OMP_PROFILE": "",
"PI_PROFILE": "work",
+ "QWEN_HOME": filepath.Join(cwd, "qwen-alt"),
}
if runtime.GOOS == "windows" {
// Not absolute without a drive letter, so it is resolved like any relative path.
diff --git a/cli/beacon/internal/endpoint/lifecycle/lifecycle.go b/cli/beacon/internal/endpoint/lifecycle/lifecycle.go
index 82e2c283..3ea561a2 100644
--- a/cli/beacon/internal/endpoint/lifecycle/lifecycle.go
+++ b/cli/beacon/internal/endpoint/lifecycle/lifecycle.go
@@ -215,6 +215,7 @@ var inventoryJobPathEnv = []string{
"OMO_CODING_AGENT_DIR", // OMO
"SENPI_CODING_AGENT_DIR", // OMO's legacy name
"PRIME_AGENT_CODING_AGENT_DIR", // Prime Agent
+ "QWEN_HOME", // Qwen Code
}
// inventoryJobNameEnv are the variables the inventory scan reads as names rather than paths, so
diff --git a/cli/beacon/internal/hermessession/home.go b/cli/beacon/internal/hermessession/home.go
index f4924791..5a2e167c 100644
--- a/cli/beacon/internal/hermessession/home.go
+++ b/cli/beacon/internal/hermessession/home.go
@@ -10,6 +10,7 @@ import (
"strings"
"unicode/utf8"
+ "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/homepath"
"github.com/asymptote-labs/agent-beacon/cli/beacon/internal/sessionfs"
)
@@ -45,11 +46,11 @@ func HomeOverride(home string) (string, error) {
if home == "" {
home, _ = os.UserHomeDir()
}
- if home != "" {
- if path == "~" {
- path = home
- } else if strings.HasPrefix(path, "~/") || (runtime.GOOS == "windows" && strings.HasPrefix(path, `~\`)) {
- path = filepath.Join(home, path[2:])
+ // Hermes expands as Python's os.path.expanduser does: `~\` is a separator only on Windows, and
+ // with no home the path is left as written.
+ if home != "" && (runtime.GOOS == "windows" || !strings.HasPrefix(path, `~\`)) {
+ if expanded, err := homepath.ExpandTilde(path, home); err == nil {
+ path = expanded
}
}
absolute, err := filepath.Abs(path)
diff --git a/cli/beacon/internal/homepath/homepath.go b/cli/beacon/internal/homepath/homepath.go
new file mode 100644
index 00000000..ee3286ab
--- /dev/null
+++ b/cli/beacon/internal/homepath/homepath.go
@@ -0,0 +1,27 @@
+// Package homepath resolves a leading `~` in a runtime's directory override the way the runtimes
+// themselves do, so every installer, discovery probe, inventory scan and session reader that
+// follows an override such as QWEN_HOME or PI_CODING_AGENT_DIR lands on the same directory.
+package homepath
+
+import (
+ "fmt"
+ "path/filepath"
+ "strings"
+)
+
+// ExpandTilde expands a bare `~` or a `~/`- or `~\`-rooted path against home. Anything else,
+// `~user/...` included, is returned unchanged, which is the runtimes' own rule. Without it, an
+// install would create a literal `~` directory beside the working directory and report success
+// while the runtime kept reading the real home.
+func ExpandTilde(path, home string) (string, error) {
+ if path != "~" && !strings.HasPrefix(path, "~/") && !strings.HasPrefix(path, `~\`) {
+ return path, nil
+ }
+ if strings.TrimSpace(home) == "" {
+ return "", fmt.Errorf("home directory is required to resolve %q", path)
+ }
+ if path == "~" {
+ return home, nil
+ }
+ return filepath.Join(home, filepath.FromSlash(path[2:])), nil
+}
diff --git a/cli/beacon/internal/pisession/store.go b/cli/beacon/internal/pisession/store.go
index 6b96133d..310d19e8 100644
--- a/cli/beacon/internal/pisession/store.go
+++ b/cli/beacon/internal/pisession/store.go
@@ -6,6 +6,7 @@ import (
"encoding/json"
"errors"
"fmt"
+ "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/homepath"
"github.com/asymptote-labs/agent-beacon/cli/beacon/internal/sessionfs"
"io"
"io/fs"
@@ -82,10 +83,11 @@ func defaultAgentDir() (string, error) {
// inventory all resolve it here.
func AgentDir(home string) (string, error) {
if override := strings.TrimSpace(os.Getenv(piAgentDirEnv)); override != "" {
- if strings.TrimSpace(home) == "" && (override == "~" || strings.HasPrefix(override, "~/") || strings.HasPrefix(override, `~\`)) {
- return "", fmt.Errorf("home directory is required to resolve %s=%q", piAgentDirEnv, override)
+ dir, err := homepath.ExpandTilde(override, home)
+ if err != nil {
+ return "", fmt.Errorf("resolve %s: %w", piAgentDirEnv, err)
}
- return expandTilde(override, home), nil
+ return dir, nil
}
if strings.TrimSpace(home) == "" {
return "", errors.New("home directory is empty")
@@ -93,16 +95,6 @@ func AgentDir(home string) (string, error) {
return filepath.Join(home, ".pi", "agent"), nil
}
-func expandTilde(path, home string) string {
- if path == "~" {
- return home
- }
- if strings.HasPrefix(path, "~/") || strings.HasPrefix(path, `~\`) {
- return filepath.Join(home, filepath.FromSlash(path[2:]))
- }
- return path
-}
-
func (s *Store) Exists() bool {
info, err := sessionfs.Stat(s.SessionsDir)
return err == nil && info.IsDir()
diff --git a/cli/beacon/internal/primesession/store.go b/cli/beacon/internal/primesession/store.go
index 8a50ce18..99a6248b 100644
--- a/cli/beacon/internal/primesession/store.go
+++ b/cli/beacon/internal/primesession/store.go
@@ -5,6 +5,7 @@ import (
"encoding/json"
"errors"
"fmt"
+ "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/homepath"
"github.com/asymptote-labs/agent-beacon/cli/beacon/internal/sessionfs"
"io/fs"
"os"
@@ -88,7 +89,7 @@ func defaultAgentDir() (string, error) {
return "", fmt.Errorf("resolve home directory: %w", err)
}
if override := strings.TrimSpace(os.Getenv(primeAgentDirEnv)); override != "" {
- return expandTilde(override, home), nil
+ return homepath.ExpandTilde(override, home)
}
if strings.TrimSpace(home) == "" {
return "", errors.New("home directory is empty")
@@ -96,16 +97,6 @@ func defaultAgentDir() (string, error) {
return filepath.Join(home, ".prime", "agent"), nil
}
-func expandTilde(path, home string) string {
- if path == "~" {
- return home
- }
- if strings.HasPrefix(path, "~/") || strings.HasPrefix(path, `~\`) {
- return filepath.Join(home, filepath.FromSlash(path[2:]))
- }
- return path
-}
-
func (s *Store) Exists() bool {
return dirExists(s.SessionsDir) || dirExists(s.ArtifactsDir)
}
diff --git a/docs/cli/endpoint-inventory.mdx b/docs/cli/endpoint-inventory.mdx
index dba731c1..525c46fd 100644
--- a/docs/cli/endpoint-inventory.mdx
+++ b/docs/cli/endpoint-inventory.mdx
@@ -67,7 +67,7 @@ A scheduled local job appends inventory telemetry to a separate `inventory_state
A system-mode job runs as root and inventories the active console user's home. When nobody is logged in, or the console is held by a macOS service account such as `_mbsetupuser` at the login window, it still writes the heartbeat, with `user_scope.mode` set to `no_console_user`, and no snapshot. Runtime state files the runtime rewrites on every session (`~/.claude.json`) are reported with their hash but left out of the change digest, so `inventory.snapshot` is written when something inventory-relevant changed (a config, hook, skill, or MCP server), not on every Claude Code session. On a Mac with more than one console user the job keeps the last digest per home, so a switch between users is not reported as a change. The scheduled scan covers user-level configuration only; project-scoped files (`.cursor/mcp.json`, `.claude/settings.json` in a repository) are reported by `beacon endpoint inventory` run from that directory, not by the job.
-launchd and systemd start the job without your shell's environment, so a per-user `beacon endpoint install` or `repair` writes the variables that move a runtime's user directory into the job's definition, taking each value from the shell it runs in: `CODEX_HOME`, `HERMES_HOME` and `HERMES_DATA_DIR_SUFFIX`, `CLINE_DIR`, `GEMINI_CLI_HOME`, `CLAUDE_CONFIG_DIR`, `KIRO_HOME`, `KIMI_CODE_HOME`, `DSH_HOME`, `OH_PERSISTENCE_DIR`, `OPENCLAW_STATE_DIR`, `XDG_CONFIG_HOME`, `PI_CODING_AGENT_DIR`, `OMO_CODING_AGENT_DIR`, `SENPI_CODING_AGENT_DIR`, `PRIME_AGENT_CODING_AGENT_DIR`, `PI_CONFIG_DIR`, `OMP_PROFILE` and `PI_PROFILE`. A relative path is recorded as the absolute path it named at install time. If you change one of them later, run `beacon endpoint repair` from a shell that has the new value. A system-mode job records none of them, since the installer's environment is root's.
+launchd and systemd start the job without your shell's environment, so a per-user `beacon endpoint install` or `repair` writes the variables that move a runtime's user directory into the job's definition, taking each value from the shell it runs in: `CODEX_HOME`, `HERMES_HOME` and `HERMES_DATA_DIR_SUFFIX`, `CLINE_DIR`, `GEMINI_CLI_HOME`, `CLAUDE_CONFIG_DIR`, `KIRO_HOME`, `KIMI_CODE_HOME`, `DSH_HOME`, `OH_PERSISTENCE_DIR`, `OPENCLAW_STATE_DIR`, `XDG_CONFIG_HOME`, `PI_CODING_AGENT_DIR`, `OMO_CODING_AGENT_DIR`, `SENPI_CODING_AGENT_DIR`, `PRIME_AGENT_CODING_AGENT_DIR`, `QWEN_HOME`, `PI_CONFIG_DIR`, `OMP_PROFILE` and `PI_PROFILE`. A relative path is recorded as the absolute path it named at install time. If you change one of them later, run `beacon endpoint repair` from a shell that has the new value. A system-mode job records none of them, since the installer's environment is root's.
By default, inventory snapshots include config file metadata, MCP server metadata, skill metadata, and hook config metadata across supported local runtimes. They do not include skill instruction bodies, MCP secret values, full environment values, full command arguments, or unrelated config content.
diff --git a/docs/runtimes/qwen-code.mdx b/docs/runtimes/qwen-code.mdx
index 33d1eb58..a1508949 100644
--- a/docs/runtimes/qwen-code.mdx
+++ b/docs/runtimes/qwen-code.mdx
@@ -19,7 +19,7 @@ beacon endpoint hooks install --harness qwen
Before enabling Qwen Code telemetry, make sure:
-- Qwen Code is installed and available as the `qwen` executable, or has a local config directory at `~/.qwen`.
+- Qwen Code is installed and available as the `qwen` executable, or has a local config directory at `~/.qwen` (or `$QWEN_HOME`).
- `beacon endpoint install` has run so shared endpoint config and runtime log paths exist.
- On Windows, `bash` is on `PATH`. Beacon's hooks declare `shell: bash`. See [Hook shell](#hook-shell).
- Project-level hooks are only used in a folder Qwen Code trusts. See [Known gaps](#known-gaps).
@@ -31,9 +31,11 @@ Qwen Code reads settings from two locations, with project settings taking preced
| Level | Settings path |
|-------|---------------|
-| User | `~/.qwen/settings.json` |
+| User | `~/.qwen/settings.json`, or `$QWEN_HOME/settings.json` when `QWEN_HOME` is set |
| Project | `./.qwen/settings.json` |
+`QWEN_HOME` is read as Qwen Code reads it: a leading `~` is expanded, a relative path is made absolute, and `settings.json` sits directly in that directory. If you change `QWEN_HOME` after installing, run `beacon endpoint repair` from a shell that has the new value; see [Agent inventory](/cli/endpoint-inventory) for why the scheduled scan needs it.
+
User level is the default. A project-level install only takes effect once Qwen trusts the folder, and `beacon endpoint discover` reports on the user path only, so a project-level install does not appear in discovery output.
`settings.json` also holds the user's own configuration, such as model, theme, MCP servers, and their own hooks. Install merges into that file rather than rewriting it: unrelated top-level keys are preserved, non-Beacon hooks in the same event group survive, and a re-install replaces Beacon's entries instead of adding a second copy. Beacon recognizes its own entries by the `--platform qwen` argument in the hook command.
@@ -73,7 +75,7 @@ Beacon does not register Qwen's fire-and-forget events: `MessageDisplay`, `StopF
## Discovery and status
-Beacon detects Qwen Code through the `qwen` executable, and treats the `~/.qwen` config directory as an additional signal. Qwen Code installs through npm, so a version manager, a shell alias, or a per-project install can hide the binary from the endpoint process's `PATH` while `~/.qwen` is still present. The OpenCode, Cursor, Pi, and Hermes probes use the same fallback.
+Beacon detects Qwen Code through the `qwen` executable, and treats its user config directory (`~/.qwen`, or `$QWEN_HOME`) as an additional signal. Qwen Code installs through npm, so a version manager, a shell alias, or a per-project install can hide the binary from the endpoint process's `PATH` while that directory is still present. The OpenCode, Cursor, Pi, and Hermes probes use the same fallback.
```bash title="Show Qwen Code discovery state"
beacon endpoint discover --all --json
@@ -83,7 +85,7 @@ Qwen Code reports as the `qwen_code` harness with capability `hooks`:
| Telemetry status | Meaning |
|------------------|---------|
-| `missing` | No `~/.qwen/settings.json`, or it could not be read |
+| `missing` | No user `settings.json` (`~/.qwen/settings.json` or `$QWEN_HOME/settings.json`), or it could not be read |
| `misconfigured` | `settings.json` exists but its JSON is invalid, so install will refuse to touch it |
| `disabled` | Hooks are turned off by `disableAllHooks`, or the file exists with no Beacon `--platform qwen` entry |
| `enabled` | Beacon's Qwen Code hooks are configured |
@@ -115,7 +117,7 @@ A project-level install reports that Qwen Code runs project hooks only in a trus
| Area | Support |
|------|---------|
-| Runtime discovery | Supported through executable and `~/.qwen` detection, settings path, and telemetry status |
+| Runtime discovery | Supported through executable and `~/.qwen` (or `$QWEN_HOME`) detection, settings path, and telemetry status |
| Harness attribution | Supported. `qwen`, `qwen_code`, `qwen-code`, `qwen code`, `qwencode`, `qwen_cli`, `qwen-cli`, `qwen cli`, `qwen_coder`, `qwen-coder`, and `qwen coder` all normalize to `qwen_code` |
| Hook install, status, uninstall, and repair | Supported |
| Session lifecycle | Supported through `SessionStart` and `SessionEnd`, with the start `source` preserved |