The cross-harness, self-improving memory layer for AI agents. Join our community: https://discord.com/invite/zdNChS2fBu
Go agent-ai-cliagent-harnessesagent-securitybrowser-extensionciclaude-codecloudcodexcursordetection-engineeringjevknowledge-basememorymobile-device-managementobservabilitysecuritysecurity-information-and-event-managementsecurity-toolstelemetrytraces
fix(hermes): resolve install, hooks and inventory paths through HERMES_HOME (#873)
claude[bot]87680d9ed182
diff --git a/cli/beacon/internal/endpoint/harness/harness.go b/cli/beacon/internal/endpoint/harness/harness.goindex 6c985f01..117086b6 100644--- a/cli/beacon/internal/endpoint/harness/harness.go+++ b/cli/beacon/internal/endpoint/harness/harness.go@@ -15,6 +15,7 @@ import ("github.com/asymptote-labs/agent-beacon/cli/beacon/internal/codexsession""github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/hooks""github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/integrations/cowork"+ "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/hermessession""gopkg.in/yaml.v3")@@ -255,8 +256,14 @@ func DiscoverHermes() Harness {h := Harness{Name: "hermes", DisplayName: "Hermes Agent", Capability: "hooks"}detectExecutable(&h, "hermes")home, _ := os.UserHomeDir()- h.ConfigPath = filepath.Join(home, ".hermes", "config.yaml")- if !h.Detected && dirExists(filepath.Join(home, ".hermes")) {+ dir, err := hermessession.HomeDir(home)+ if err != nil {+ h.TelemetryStatus = TelemetryMissing+ h.Message = "Hermes home directory could not be resolved: " + err.Error()+ return h+ }+ h.ConfigPath = filepath.Join(dir, "config.yaml")+ if !h.Detected && dirExists(dir) {h.Detected = true}if fileExists(h.ConfigPath) {diff --git a/cli/beacon/internal/endpoint/harness/harness_test.go b/cli/beacon/internal/endpoint/harness/harness_test.goindex 7a780775..cf4e4bf5 100644--- a/cli/beacon/internal/endpoint/harness/harness_test.go+++ b/cli/beacon/internal/endpoint/harness/harness_test.go@@ -6,6 +6,7 @@ import ("github.com/asymptote-labs/agent-beacon/cli/beacon/internal/testenv""os""path/filepath"+ "runtime""strings""testing")@@ -1101,6 +1102,93 @@ func TestDiscoverClineDoesNotFallBackToAProjectPluginWhenHomeIsUnresolvable(t *t}}+// hermesDiscoverHome moves the home directory to a temporary one with no hermes executable on PATH,+// clears every variable that moves Hermes's home, and returns Hermes's native root there.+func hermesDiscoverHome(t *testing.T) string {+ t.Helper()+ home := t.TempDir()+ testenv.SetHome(t, home)+ t.Setenv("PATH", t.TempDir())+ t.Setenv("HERMES_HOME", "")+ t.Setenv("HERMES_DATA_DIR_SUFFIX", "")+ t.Setenv("LOCALAPPDATA", filepath.Join(home, "LocalAppData"))+ if runtime.GOOS == "windows" {+ return filepath.Join(home, "LocalAppData", "hermes")+ }+ return filepath.Join(home, ".hermes")+}++const hermesBeaconHooksYAML = `hooks:+ on_session_end:+ - command: env BEACON_ENDPOINT_MODE=1 beacon-hooks --platform hermes session-end+`++func writeHermesConfigFixture(t *testing.T, dir, content string) string {+ t.Helper()+ if err := os.MkdirAll(dir, 0o755); err != nil {+ t.Fatal(err)+ }+ path := filepath.Join(dir, "config.yaml")+ if err := os.WriteFile(path, []byte(content), 0o600); err != nil {+ t.Fatal(err)+ }+ return path+}++// Discovery reports the config.yaml Hermes reads: HERMES_HOME's, or the sticky profile's, rather+// than a stale ~/.hermes/config.yaml.+func TestDiscoverHermesFollowsHermesHomeAndActiveProfile(t *testing.T) {+ t.Run("unset", func(t *testing.T) {+ native := hermesDiscoverHome(t)+ want := writeHermesConfigFixture(t, native, hermesBeaconHooksYAML)+ h := DiscoverHermes()+ if h.ConfigPath != want || !h.Detected || h.TelemetryStatus != TelemetryEnabled {+ t.Fatalf("DiscoverHermes = path %q detected %v status %q, want %q detected and enabled", h.ConfigPath, h.Detected, h.TelemetryStatus, want)+ }+ })+ t.Run("HERMES_HOME", func(t *testing.T) {+ native := hermesDiscoverHome(t)+ writeHermesConfigFixture(t, native, "model: stale\n")+ dir := t.TempDir()+ t.Setenv("HERMES_HOME", dir)+ want := writeHermesConfigFixture(t, dir, hermesBeaconHooksYAML)+ h := DiscoverHermes()+ if h.ConfigPath != want || !h.Detected || h.TelemetryStatus != TelemetryEnabled {+ t.Fatalf("DiscoverHermes = path %q detected %v status %q, want %q detected and enabled", h.ConfigPath, h.Detected, h.TelemetryStatus, want)+ }+ })+ t.Run("active profile", func(t *testing.T) {+ native := hermesDiscoverHome(t)+ writeHermesConfigFixture(t, native, hermesBeaconHooksYAML)+ profile := filepath.Join(native, "profiles", "work")+ if err := os.MkdirAll(profile, 0o755); err != nil {+ t.Fatal(err)+ }+ if err := os.WriteFile(filepath.Join(native, "active_profile"), []byte("work\n"), 0o644); err != nil {+ t.Fatal(err)+ }+ h := DiscoverHermes()+ want := filepath.Join(profile, "config.yaml")+ if h.ConfigPath != want || !h.Detected || h.TelemetryStatus != TelemetryMissing {+ t.Fatalf("DiscoverHermes = path %q detected %v status %q, want %q detected and missing: the default profile's hooks do not run in this profile", h.ConfigPath, h.Detected, h.TelemetryStatus, want)+ }+ })+}++// Hermes refuses to start when active_profile names a profile it cannot use; discovery says so+// instead of reporting the default profile's config.+func TestDiscoverHermesReportsUnusableActiveProfile(t *testing.T) {+ native := hermesDiscoverHome(t)+ writeHermesConfigFixture(t, native, hermesBeaconHooksYAML)+ if err := os.WriteFile(filepath.Join(native, "active_profile"), []byte("gone\n"), 0o644); err != nil {+ t.Fatal(err)+ }+ h := DiscoverHermes()+ if h.TelemetryStatus != TelemetryMissing || !strings.Contains(h.Message, "active profile") || h.ConfigPath != "" {+ t.Fatalf("DiscoverHermes = status %q message %q path %q, want missing naming the active profile", h.TelemetryStatus, h.Message, h.ConfigPath)+ }+}+func TestGeminiSettingsHonorGeminiCLIHome(t *testing.T) {home := t.TempDir()testenv.SetHome(t, home)diff --git a/cli/beacon/internal/endpoint/hooks/hermes.go b/cli/beacon/internal/endpoint/hooks/hermes.goindex 17f63093..4e36b788 100644--- a/cli/beacon/internal/endpoint/hooks/hermes.go+++ b/cli/beacon/internal/endpoint/hooks/hermes.go@@ -6,6 +6,8 @@ import ("path/filepath""gopkg.in/yaml.v3"++ "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/hermessession")type HermesOptions struct {@@ -219,6 +221,8 @@ func isHermesInstalledAt(path string) bool {return false}+// hermesConfigPath is the config.yaml a plain `hermes` reads: HERMES_HOME or the native root, then+// the active profile, as hermessession.HomeDir resolves it.func hermesConfigPath(level Level) (string, error) {switch level {case "", LevelUser:@@ -226,7 +230,11 @@ func hermesConfigPath(level Level) (string, error) {if err != nil {return "", err}- return filepath.Join(home, ".hermes", "config.yaml"), nil+ dir, err := hermessession.HomeDir(home)+ if err != nil {+ return "", err+ }+ return filepath.Join(dir, "config.yaml"), nilcase LevelProject:return "", fmt.Errorf("Hermes Agent endpoint hooks support user-level config only")default:diff --git a/cli/beacon/internal/endpoint/hooks/hermes_test.go b/cli/beacon/internal/endpoint/hooks/hermes_test.goindex f2838761..8ab98b57 100644--- a/cli/beacon/internal/endpoint/hooks/hermes_test.go+++ b/cli/beacon/internal/endpoint/hooks/hermes_test.go@@ -1,11 +1,13 @@package hooksimport (- "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/testenv""os""path/filepath"+ "runtime""strings""testing"++ "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/testenv")func TestInstallHermesConfigPreservesExistingSettingsAndHooks(t *testing.T) {@@ -129,10 +131,24 @@ func TestRemoveHermesEndpointHooksPreservesOtherHooks(t *testing.T) {}}-func TestHermesHookStatusDetectsInstalled(t *testing.T) {+// hermesTestHome moves the home directory to a temporary one, clears every variable that moves+// Hermes's home, and returns Hermes's native root there.+func hermesTestHome(t *testing.T) string {+ t.Helper()home := t.TempDir()testenv.SetHome(t, home)- path := filepath.Join(home, ".hermes", "config.yaml")+ t.Setenv("HERMES_HOME", "")+ t.Setenv("HERMES_DATA_DIR_SUFFIX", "")+ t.Setenv("LOCALAPPDATA", filepath.Join(home, "LocalAppData"))+ if runtime.GOOS == "windows" {+ return filepath.Join(home, "LocalAppData", "hermes")+ }+ return filepath.Join(home, ".hermes")+}++func TestHermesHookStatusDetectsInstalled(t *testing.T) {+ native := hermesTestHome(t)+ path := filepath.Join(native, "config.yaml")if err := os.MkdirAll(filepath.Dir(path), 0755); err != nil {t.Fatal(err)}@@ -157,3 +173,110 @@ func TestHermesProjectLevelReturnsClearError(t *testing.T) {t.Fatalf("hermesConfigPath project err = %v, want user-level config only", err)}}++// Install, status and uninstall resolve one config.yaml, the one Hermes reads: under HERMES_HOME+// when it is set, under the sticky profile when one is active, and ~/.hermes otherwise.+func TestHermesHooksInstallStatusUninstallAgreeOnHermesHome(t *testing.T) {+ for _, tc := range []struct {+ name string+ setup func(t *testing.T, native string) string+ }{+ {"unset", func(t *testing.T, native string) string { return native }},+ {"HERMES_HOME", func(t *testing.T, native string) string {+ dir := filepath.Join(t.TempDir(), "hermes-data")+ t.Setenv("HERMES_HOME", dir)+ return dir+ }},+ {"relative HERMES_HOME", func(t *testing.T, native string) string {+ t.Chdir(t.TempDir())+ cwd, err := os.Getwd()+ if err != nil {+ t.Fatal(err)+ }+ t.Setenv("HERMES_HOME", "relative-hermes")+ return filepath.Join(cwd, "relative-hermes")+ }},+ {"active profile", func(t *testing.T, native string) string {+ profile := filepath.Join(native, "profiles", "work")+ if err := os.MkdirAll(profile, 0o755); err != nil {+ t.Fatal(err)+ }+ if err := os.WriteFile(filepath.Join(native, "active_profile"), []byte("work\n"), 0o644); err != nil {+ t.Fatal(err)+ }+ return profile+ }},+ {"HERMES_HOME names a profile", func(t *testing.T, native string) string {+ profile := filepath.Join(t.TempDir(), "profiles", "coder")+ t.Setenv("HERMES_HOME", profile)+ return profile+ }},+ } {+ t.Run(tc.name, func(t *testing.T) {+ native := hermesTestHome(t)+ want := filepath.Join(tc.setup(t, native), "config.yaml")+ opts := HermesOptions{Level: LevelUser, UserMode: true}++ installed, err := InstallHermes(opts)+ if err != nil {+ t.Fatalf("InstallHermes: %v", err)+ }+ if installed.ConfigPath != want {+ t.Fatalf("InstallHermes ConfigPath = %q, want %q", installed.ConfigPath, want)+ }+ if !isHermesInstalledAt(want) {+ t.Fatalf("no Beacon hooks in %s after install", want)+ }+ if want != filepath.Join(native, "config.yaml") {+ if _, err := os.Stat(filepath.Join(native, "config.yaml")); !os.IsNotExist(err) {+ t.Fatalf("InstallHermes also wrote the default config.yaml: %v", err)+ }+ }+ status := HermesHookStatus(opts)+ if !status.Installed || status.ConfigPath != want {+ t.Fatalf("HermesHookStatus = %#v, want installed at %q", status, want)+ }+ if !IsHermesInstalled(opts) {+ t.Fatal("IsHermesInstalled = false after install")+ }++ removed, err := UninstallHermes(opts)+ if err != nil {+ t.Fatalf("UninstallHermes: %v", err)+ }+ if removed.ConfigPath != want {+ t.Fatalf("UninstallHermes ConfigPath = %q, want %q", removed.ConfigPath, want)+ }+ if _, err := os.Stat(want); !os.IsNotExist(err) {+ t.Fatalf("config.yaml holding only Beacon hooks was not removed: %v", err)+ }+ if status := HermesHookStatus(opts); status.Installed || status.ConfigPath != want {+ t.Fatalf("HermesHookStatus after uninstall = %#v, want not installed at %q", status, want)+ }+ })+ }+}++// Hermes refuses to start when active_profile names a profile it cannot use, so hook install must+// fail rather than write the default profile's config.yaml.+func TestHermesHooksRefuseUnusableActiveProfile(t *testing.T) {+ native := hermesTestHome(t)+ if err := os.MkdirAll(native, 0o755); err != nil {+ t.Fatal(err)+ }+ if err := os.WriteFile(filepath.Join(native, "active_profile"), []byte("gone\n"), 0o644); err != nil {+ t.Fatal(err)+ }+ opts := HermesOptions{Level: LevelUser, UserMode: true}+ if _, err := InstallHermes(opts); err == nil || !strings.Contains(err.Error(), "active profile") {+ t.Fatalf("InstallHermes err = %v, want the active profile named", err)+ }+ for _, path := range []string{filepath.Join(native, "config.yaml"), filepath.Join(native, "profiles", "gone")} {+ if _, err := os.Stat(path); !os.IsNotExist(err) {+ t.Fatalf("InstallHermes created %s: %v", path, err)+ }+ }+ if status := HermesHookStatus(opts); status.Installed {+ t.Fatalf("HermesHookStatus = %#v, want not installed", status)+ }+}diff --git a/cli/beacon/internal/endpoint/inventory/inventory.go b/cli/beacon/internal/endpoint/inventory/inventory.goindex 23e44317..a2f0353e 100644--- a/cli/beacon/internal/endpoint/inventory/inventory.go+++ b/cli/beacon/internal/endpoint/inventory/inventory.go@@ -20,6 +20,7 @@ import ("github.com/asymptote-labs/agent-beacon/cli/beacon/internal/codexsession""github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/harness""github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/hooks"+ "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/hermessession")const (@@ -497,8 +498,14 @@ func omoCandidates(home, wd string) []candidate {return items}+// hermesCandidates resolves config.yaml through HERMES_HOME and the active profile, as Hermes does,+// and leaves it out when the active profile names one Hermes itself would refuse to start with.func hermesCandidates(home string) []candidate {- return []candidate{{runtime: "hermes", path: filepath.Join(home, ".hermes", "config.yaml"), scope: ScopeUser, format: formatYAML, kind: KindNativeConfig}}+ dir, err := hermessession.HomeDir(home)+ if err != nil {+ return nil+ }+ return []candidate{{runtime: "hermes", path: filepath.Join(dir, "config.yaml"), scope: ScopeUser, format: formatYAML, kind: KindNativeConfig}}}func devinCandidates(home, wd string) []candidate {diff --git a/cli/beacon/internal/endpoint/inventory/inventory_test.go b/cli/beacon/internal/endpoint/inventory/inventory_test.goindex 22e5c23b..84cbbf92 100644--- a/cli/beacon/internal/endpoint/inventory/inventory_test.go+++ b/cli/beacon/internal/endpoint/inventory/inventory_test.go@@ -4,6 +4,7 @@ import ("encoding/json""os""path/filepath"+ "runtime""strings""testing""time"@@ -369,6 +370,75 @@ func TestScanReadsCodexUserConfigFromCodexHome(t *testing.T) {}}+// hermesDefaultRoot clears every variable that moves Hermes's home and returns its native root+// under home.+func hermesDefaultRoot(t *testing.T, home string) string {+ t.Helper()+ t.Setenv("HERMES_HOME", "")+ t.Setenv("HERMES_DATA_DIR_SUFFIX", "")+ t.Setenv("LOCALAPPDATA", "")+ if runtime.GOOS == "windows" {+ return filepath.Join(home, "AppData", "Local", "hermes")+ }+ return filepath.Join(home, ".hermes")+}++const hermesMCPConfig = `+mcp_servers:+ memory:+ command: uvx+`++// With HERMES_HOME set, or a sticky profile active, inventory reads the config.yaml Hermes reads+// and not the default profile's.+func TestScanReadsHermesConfigFromHermesHomeAndActiveProfile(t *testing.T) {+ scanHermes := func(home string) []Config {+ return Scan(Options{HomeDir: home, SkipProjectScope: true, Runtimes: []string{"hermes"}, Now: fixedNow}).Configs+ }+ t.Run("HERMES_HOME", func(t *testing.T) {+ home := t.TempDir()+ root := hermesDefaultRoot(t, home)+ writeFile(t, filepath.Join(root, "config.yaml"), "model: stale\n")+ dir := t.TempDir()+ t.Setenv("HERMES_HOME", dir)+ writeFile(t, filepath.Join(dir, "config.yaml"), hermesMCPConfig)+ configs := scanHermes(home)+ if config := findConfig(configs, "hermes", filepath.Join(dir, "config.yaml")); config == nil || !config.Exists || config.MCPServerCount != 1 {+ t.Fatalf("HERMES_HOME config.yaml = %#v, want it read with one MCP server", config)+ }+ if stale := findConfig(configs, "hermes", filepath.Join(root, "config.yaml")); stale != nil {+ t.Fatalf("inventory reported the default config.yaml, which Hermes does not read with HERMES_HOME set: %#v", stale)+ }+ })+ t.Run("active profile", func(t *testing.T) {+ home := t.TempDir()+ root := hermesDefaultRoot(t, home)+ writeFile(t, filepath.Join(root, "config.yaml"), "model: stale\n")+ writeFile(t, filepath.Join(root, "active_profile"), "work\n")+ profile := filepath.Join(root, "profiles", "work")+ writeFile(t, filepath.Join(profile, "config.yaml"), hermesMCPConfig)+ configs := scanHermes(home)+ if config := findConfig(configs, "hermes", filepath.Join(profile, "config.yaml")); config == nil || !config.Exists || config.MCPServerCount != 1 {+ t.Fatalf("active profile config.yaml = %#v, want it read with one MCP server", config)+ }+ if stale := findConfig(configs, "hermes", filepath.Join(root, "config.yaml")); stale != nil {+ t.Fatalf("inventory reported the default profile's config.yaml: %#v", stale)+ }+ })+ t.Run("unusable active profile", func(t *testing.T) {+ // Hermes refuses to start, so there is no config.yaml in use to report.+ home := t.TempDir()+ root := hermesDefaultRoot(t, home)+ writeFile(t, filepath.Join(root, "config.yaml"), hermesMCPConfig)+ writeFile(t, filepath.Join(root, "active_profile"), "gone\n")+ for _, config := range scanHermes(home) {+ if config.Runtime == "hermes" {+ t.Fatalf("inventory reported %#v for an active profile Hermes cannot use", config)+ }+ }+ })+}+// With CLINE_DIR set, the user plugin inventory reports is the one Cline loads.func TestScanReadsClinePluginFromClineDir(t *testing.T) {home := t.TempDir()@@ -457,6 +527,8 @@ func TestScanIncludesAllSupportedCurrentUserAndProjectConfigs(t *testing.T) {t.Setenv("CODEX_HOME", "")t.Setenv("CLINE_DIR", "")t.Setenv("GEMINI_CLI_HOME", "")+ // Hermes's config.yaml follows HERMES_HOME, its data-dir suffix and, on Windows, LOCALAPPDATA.+ hermesRoot := hermesDefaultRoot(t, home)result := Scan(Options{HomeDir: home,@@ -515,7 +587,7 @@ func TestScanIncludesAllSupportedCurrentUserAndProjectConfigs(t *testing.T) {// plugin root and a global one, and a gateway can be running with either.{runtime: "openclaw_gateway", path: filepath.Join(home, ".openclaw", "extensions", "beacon-endpoint", "beacon.js"), scope: ScopeUser, format: formatMetadataOnly, kind: KindPlugin},{runtime: "openclaw_gateway", path: filepath.Join(work, ".openclaw", "extensions", "beacon-endpoint", "beacon.js"), scope: ScopeProject, format: formatMetadataOnly, kind: KindPlugin},- {runtime: "hermes", path: filepath.Join(home, ".hermes", "config.yaml"), scope: ScopeUser, format: formatYAML, kind: KindNativeConfig},+ {runtime: "hermes", path: filepath.Join(hermesRoot, "config.yaml"), scope: ScopeUser, format: formatYAML, kind: KindNativeConfig},{runtime: "devin-cli", path: filepath.Join(home, ".config", "devin", "config.json"), scope: ScopeUser, format: formatJSON, kind: KindNativeConfig},{runtime: "devin-cli", path: filepath.Join(work, ".devin", "hooks.v1.json"), scope: ScopeProject, format: formatJSON, kind: KindHookConfig},{runtime: "devin-desktop", path: filepath.Join(home, ".codeium", "windsurf", "hooks.json"), scope: ScopeUser, format: formatJSON, kind: KindHookConfig},@@ -585,7 +657,7 @@ func TestScanYAMLAndMetadataOnlyConfigs(t *testing.T) {work := t.TempDir()t.Setenv("SHELL", "/bin/zsh")t.Setenv("CLINE_DIR", "")- writeFile(t, filepath.Join(home, ".hermes", "config.yaml"), `+ writeFile(t, filepath.Join(hermesDefaultRoot(t, home), "config.yaml"), `mcpServers:memory:command: uvxdiff --git a/cli/beacon/internal/endpoint/lifecycle/inventory_job_test.go b/cli/beacon/internal/endpoint/lifecycle/inventory_job_test.goindex 12284e6c..6171bc9b 100644--- a/cli/beacon/internal/endpoint/lifecycle/inventory_job_test.go+++ b/cli/beacon/internal/endpoint/lifecycle/inventory_job_test.go@@ -132,6 +132,8 @@ func TestInventoryJobEnvRecordsCodexHomeForUserInstalls(t *testing.T) {t.Fatal(err)}t.Chdir(work)+ t.Setenv("HERMES_HOME", "")+ t.Setenv("HERMES_DATA_DIR_SUFFIX", "")t.Setenv("CLINE_DIR", "")t.Setenv("GEMINI_CLI_HOME", "")@@ -155,6 +157,57 @@ func TestInventoryJobEnvRecordsCodexHomeForUserInstalls(t *testing.T) {}}+// launchd and systemd start the job without the user's shell, so HERMES_HOME and the data-dir+// suffix are recorded in it. HERMES_HOME is recorded as given, before any profile is applied, so a+// later `hermes profile use` still reaches the job.+func TestInventoryJobEnvRecordsHermesHomeForUserInstalls(t *testing.T) {+ home := t.TempDir()+ testenv.SetHome(t, home)+ work := t.TempDir()+ t.Chdir(work)+ cwd, err := os.Getwd()+ if err != nil {+ t.Fatal(err)+ }+ t.Setenv("CODEX_HOME", "")+ t.Setenv("HERMES_DATA_DIR_SUFFIX", "")+ t.Setenv("CLINE_DIR", "")+ t.Setenv("GEMINI_CLI_HOME", "")++ // Relative and not created yet: Hermes creates its home, so it is recorded anyway.+ t.Setenv("HERMES_HOME", "hermes-data")+ want := filepath.Join(cwd, "hermes-data")+ if env := inventoryJobEnv(true); len(env) != 1 || env["HERMES_HOME"] != want {+ t.Fatalf("user mode env = %v, want only HERMES_HOME=%s", env, want)+ }+ if env := inventoryJobEnv(false); env != nil {+ t.Fatalf("system mode env = %v, want none: root's environment is not the console user's", env)+ }++ // A HERMES_HOME under a root with a sticky profile is still recorded as given.+ root := filepath.Join(home, ".hermes")+ if err := os.MkdirAll(filepath.Join(root, "profiles", "work"), 0o755); err != nil {+ t.Fatal(err)+ }+ if err := os.WriteFile(filepath.Join(root, "active_profile"), []byte("work\n"), 0o644); err != nil {+ t.Fatal(err)+ }+ t.Setenv("HERMES_HOME", "~/.hermes")+ if env := inventoryJobEnv(true); env["HERMES_HOME"] != root {+ t.Fatalf("user mode env = %v, want HERMES_HOME=%s, not the active profile", env, root)+ }++ t.Setenv("HERMES_HOME", " ")+ t.Setenv("HERMES_DATA_DIR_SUFFIX", "-dev")+ if env := inventoryJobEnv(true); len(env) != 1 || env["HERMES_DATA_DIR_SUFFIX"] != "-dev" {+ t.Fatalf("user mode env = %v, want only HERMES_DATA_DIR_SUFFIX=-dev", env)+ }+ t.Setenv("HERMES_DATA_DIR_SUFFIX", "")+ if env := inventoryJobEnv(true); env != nil {+ t.Fatalf("env with nothing set = %v, want none", env)+ }+}+// Cline uses a trimmed, non-empty CLINE_DIR as is, so the job gets its absolute form whenever it is// set. It is recorded beside CODEX_HOME, not instead of it.func TestInventoryJobEnvRecordsClineDirForUserInstalls(t *testing.T) {@@ -171,6 +224,8 @@ func TestInventoryJobEnvRecordsClineDirForUserInstalls(t *testing.T) {t.Setenv("CODEX_HOME", codexHome)t.Setenv("CLINE_DIR", " cline-state ")t.Setenv("GEMINI_CLI_HOME", "")+ t.Setenv("HERMES_HOME", "")+ t.Setenv("HERMES_DATA_DIR_SUFFIX", "")env := inventoryJobEnv(true)if want := filepath.Join(cwd, "cline-state"); env["CLINE_DIR"] != want {@@ -200,6 +255,8 @@ func TestInventoryJobEnvRecordsGeminiCLIHomeForUserInstalls(t *testing.T) {t.Setenv("CODEX_HOME", codexHome)t.Setenv("CLINE_DIR", "")t.Setenv("GEMINI_CLI_HOME", "gemini-home")+ t.Setenv("HERMES_HOME", "")+ t.Setenv("HERMES_DATA_DIR_SUFFIX", "")env := inventoryJobEnv(true)if want := filepath.Join(cwd, "gemini-home"); env["GEMINI_CLI_HOME"] != want {@@ -229,6 +286,8 @@ func TestInventoryJobEnvRecordsClaudeConfigDirForUserInstalls(t *testing.T) {t.Setenv("CODEX_HOME", codexHome)t.Setenv("CLINE_DIR", "")t.Setenv("GEMINI_CLI_HOME", "")+ t.Setenv("HERMES_HOME", "")+ t.Setenv("HERMES_DATA_DIR_SUFFIX", "")t.Setenv("CLAUDE_CONFIG_DIR", " claude-alt ")env := inventoryJobEnv(true)diff --git a/cli/beacon/internal/endpoint/lifecycle/lifecycle.go b/cli/beacon/internal/endpoint/lifecycle/lifecycle.goindex dda54609..05e44301 100644--- a/cli/beacon/internal/endpoint/lifecycle/lifecycle.go+++ b/cli/beacon/internal/endpoint/lifecycle/lifecycle.go@@ -22,6 +22,7 @@ import ("github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/service""github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/sysacl""github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/writer"+ "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/hermessession""github.com/asymptote-labs/agent-beacon/cli/beacon/internal/version")@@ -134,12 +135,16 @@ func reconcileInventoryJobWith(job inventoryJobController, opts InventoryJobOpti}// inventoryJobEnv is the environment written into a per-user inventory job. launchd and systemd-// start the job without the user's shell environment, so a CODEX_HOME, CLINE_DIR, GEMINI_CLI_HOME-// or CLAUDE_CONFIG_DIR exported in a shell profile would not reach it and the scheduled scan would-// inventory ~/.codex, ~/.cline, ~/.gemini or ~/.claude while the runtime reads the moved directory.-// Each value is resolved now, from the install's shell, as its runtime resolves it, and recorded as-// an absolute path so a relative value still means the directory it named at install time:+// start the job without the user's shell environment, so a CODEX_HOME, HERMES_HOME, CLINE_DIR,+// GEMINI_CLI_HOME or CLAUDE_CONFIG_DIR exported in a shell profile would not reach it and the+// scheduled scan would inventory ~/.codex, ~/.hermes, ~/.cline, ~/.gemini or ~/.claude while the+// runtime reads the moved directory. Each value is resolved now, from the install's shell, as its+// runtime resolves it, and recorded as an absolute path so a relative value still means the+// directory it named at install time:// - CODEX_HOME must name an existing directory, as Codex requires; otherwise nothing is recorded.+// - HERMES_HOME is trimmed and expanded as Hermes does, and HERMES_DATA_DIR_SUFFIX is recorded as+// it is. HERMES_HOME is recorded before profiles are applied, so the job still follows a later+// `hermes profile use`.// - CLINE_DIR is used whenever it is non-empty after trimming, as Cline uses it.// - GEMINI_CLI_HOME is used whenever it is non-empty, as Gemini CLI uses it.// - CLAUDE_CONFIG_DIR is used whenever it is non-empty after trimming, as Claude Code uses it.@@ -156,6 +161,12 @@ func inventoryJobEnv(userMode bool) map[string]string {env["CODEX_HOME"] = dir}}+ if dir, err := hermessession.HomeOverride(""); err == nil && dir != "" {+ env["HERMES_HOME"] = dir+ }+ if suffix := os.Getenv("HERMES_DATA_DIR_SUFFIX"); suffix != "" {+ env["HERMES_DATA_DIR_SUFFIX"] = suffix+ }if value := strings.TrimSpace(os.Getenv("CLINE_DIR")); value != "" {if dir, err := filepath.Abs(value); err == nil {env["CLINE_DIR"] = dirdiff --git a/cli/beacon/internal/hermessession/collect.go b/cli/beacon/internal/hermessession/collect.goindex 8370ec19..63979024 100644--- a/cli/beacon/internal/hermessession/collect.go+++ b/cli/beacon/internal/hermessession/collect.go@@ -13,8 +13,6 @@ import ("net/url""os""path/filepath"- "regexp"- "runtime""strconv""strings""time"@@ -122,51 +120,6 @@ type MappedEvent struct {Event schema.Event}-func DefaultDBPath() string {- if override := strings.TrimSpace(os.Getenv("HERMES_HOME")); override != "" {- path := hermesExpandVars(override)- if home, err := os.UserHomeDir(); err == nil {- if path == "~" {- path = home- } else if strings.HasPrefix(path, "~/") || (runtime.GOOS == "windows" && strings.HasPrefix(path, `~\`)) {- path = filepath.Join(home, path[2:])- }- }- return filepath.Join(path, "state.db")- }- suffix := os.Getenv("HERMES_DATA_DIR_SUFFIX")- if runtime.GOOS == "windows" {- if base := strings.TrimSpace(os.Getenv("LOCALAPPDATA")); base != "" {- return filepath.Join(base, "hermes"+suffix, "state.db")- }- }- if home, err := os.UserHomeDir(); err == nil && strings.TrimSpace(home) != "" {- if runtime.GOOS == "windows" {- return filepath.Join(home, "AppData", "Local", "hermes"+suffix, "state.db")- }- return filepath.Join(home, ".hermes"+suffix, "state.db")- }- return filepath.Join(os.TempDir(), "hermes", "state.db")-}--var hermesEnvReference = regexp.MustCompile(`\$\{([^}]*)\}|\$([A-Za-z0-9_]+)`)--// hermesExpandVars expands $VAR and ${VAR} like Python's os.path.expandvars, which Hermes-// uses: references to unset variables are left as written.-func hermesExpandVars(path string) string {- return hermesEnvReference.ReplaceAllStringFunc(path, func(reference string) string {- parts := hermesEnvReference.FindStringSubmatch(reference)- name := parts[1]- if parts[2] != "" {- name = parts[2]- }- if value, ok := os.LookupEnv(name); ok {- return value- }- return reference- })-}-func DefaultStatePath() string {base := filepath.Join(os.TempDir(), "beacon")if home, err := os.UserHomeDir(); err == nil && strings.TrimSpace(home) != "" {diff --git a/cli/beacon/internal/hermessession/home.go b/cli/beacon/internal/hermessession/home.gonew file mode 100644index 00000000..d2b43e25--- /dev/null+++ b/cli/beacon/internal/hermessession/home.go@@ -0,0 +1,205 @@+package hermessession++import (+ "errors"+ "fmt"+ "os"+ "path/filepath"+ "regexp"+ "runtime"+ "strings"+ "unicode/utf8"++ "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/sessionfs"+)++// HomeDir returns the directory a plain `hermes` invocation reads config.yaml and state.db from,+// resolved the way the Hermes launcher resolves it (_apply_profile_override in hermes_cli/main.py,+// over get_default_hermes_root in hermes_constants.py):+//+// - The base is HERMES_HOME (see HomeOverride), or the native root: ~/.hermes plus+// HERMES_DATA_DIR_SUFFIX, or %LOCALAPPDATA%\hermes plus the suffix on Windows.+// - A HERMES_HOME that already names a profile, <root>/profiles/<name>, is used as it is.+// - Otherwise a sticky profile, the name `hermes profile use` writes to <root>/active_profile,+// selects <root>/profiles/<name>. The profile root is the native root when HERMES_HOME is+// unset or inside it, and HERMES_HOME itself when it points elsewhere.+//+// home is the user's home directory, for the native root and a leading ~ in HERMES_HOME. A profile+// chosen for one invocation with `hermes -p` leaves no trace on disk, so it is not followed. An+// active_profile naming an invalid or missing profile is an error, because Hermes refuses to start+// with one rather than falling back to the default profile.+func HomeDir(home string) (string, error) {+ _, dir, err := resolveHome(home)+ return dir, err+}++// HomeOverride returns HERMES_HOME as Hermes reads it, as an absolute path: trimmed, with $VAR and+// ${VAR} expanded as Python's os.path.expandvars does and a leading ~ expanded against home (the+// current user's when home is empty). It is empty when HERMES_HOME is unset or blank.+func HomeOverride(home string) (string, error) {+ override := strings.TrimSpace(os.Getenv("HERMES_HOME"))+ if override == "" {+ return "", nil+ }+ path := hermesExpandVars(override)+ 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:])+ }+ }+ absolute, err := filepath.Abs(path)+ if err != nil {+ return "", fmt.Errorf("resolve HERMES_HOME %q: %w", override, err)+ }+ return absolute, nil+}++// DefaultDBPath is the state.db in HomeDir. When the active profile cannot be used, Hermes writes+// nothing new anywhere, so status, sync and handoff keep reading the base directory's store, which+// holds whatever Hermes wrote there before.+func DefaultDBPath() string {+ home, _ := os.UserHomeDir()+ base, dir, err := resolveHome(strings.TrimSpace(home))+ if err != nil {+ dir = base+ }+ if dir == "" {+ dir = filepath.Join(os.TempDir(), "hermes")+ }+ return filepath.Join(dir, "state.db")+}++// resolveHome returns the directory Hermes uses before profiles are considered, and the one it+// uses after.+func resolveHome(home string) (base, dir string, err error) {+ override, err := HomeOverride(home)+ if err != nil {+ return "", "", err+ }+ if override != "" && isProfileDir(override) {+ return override, override, nil+ }+ root := nativeRoot(home)+ if override != "" && (root == "" || !pathWithin(override, root)) {+ root = override+ }+ if root == "" {+ return "", "", errors.New("resolve Hermes home: home directory is empty")+ }+ base = override+ if base == "" {+ base = root+ }+ name, ok := activeProfile(root)+ if !ok {+ return base, base, nil+ }+ dir, err = profileDir(root, name)+ return base, dir, err+}++// nativeRoot is Hermes's platform default home, or empty when there is no home to put it in.+func nativeRoot(home string) string {+ name := "hermes" + os.Getenv("HERMES_DATA_DIR_SUFFIX")+ if runtime.GOOS == "windows" {+ if base := strings.TrimSpace(os.Getenv("LOCALAPPDATA")); base != "" {+ return filepath.Join(base, name)+ }+ if home == "" {+ return ""+ }+ return filepath.Join(home, "AppData", "Local", name)+ }+ if home == "" {+ return ""+ }+ return filepath.Join(home, "."+name)+}++// isProfileDir is the launcher's test for a HERMES_HOME that already selects a profile: its parent+// directory is named "profiles".+func isProfileDir(path string) bool {+ return filepath.Base(filepath.Dir(path)) == "profiles"+}++// pathWithin reports whether path is root or inside it, comparing the paths with symlinks resolved+// as Python's non-strict Path.resolve does.+func pathWithin(path, root string) bool {+ rel, err := filepath.Rel(resolveExisting(root), resolveExisting(path))+ return err == nil && rel != ".." && !strings.HasPrefix(rel, ".."+string(filepath.Separator))+}++// resolveExisting resolves symlinks in the longest prefix of path that exists and keeps the rest as+// written.+func resolveExisting(path string) string {+ rest := ""+ for dir := filepath.Clean(path); ; dir = filepath.Dir(dir) {+ if resolved, err := filepath.EvalSymlinks(dir); err == nil {+ return filepath.Join(resolved, rest)+ }+ if filepath.Dir(dir) == dir {+ return path+ }+ rest = filepath.Join(filepath.Base(dir), rest)+ }+}++// activeProfile reads the sticky profile name from <root>/active_profile. A missing, unreadable or+// empty file, or the name "default", selects no profile, as in Hermes.+func activeProfile(root string) (string, bool) {+ data, err := sessionfs.ReadFile(filepath.Join(root, "active_profile"))+ if err != nil || !utf8.Valid(data) {+ return "", false+ }+ name := strings.TrimSpace(string(data))+ if name == "" || name == "default" {+ return "", false+ }+ return name, true+}++var hermesProfileName = regexp.MustCompile(`^[a-z0-9][a-z0-9_-]{0,63}$`)++// hermesReservedProfiles are the names Hermes's validate_profile_name rejects.+var hermesReservedProfiles = map[string]bool{"hermes": true, "test": true, "tmp": true, "root": true, "sudo": true}++// profileDir is Hermes's resolve_profile_env: the name is matched case-insensitively, "default" is+// the root itself, and any other profile must be a valid name with an existing directory.+func profileDir(root, name string) (string, error) {+ canonical := strings.ToLower(name)+ if canonical == "default" {+ return root, nil+ }+ activePath := filepath.Join(root, "active_profile")+ if !hermesProfileName.MatchString(canonical) || hermesReservedProfiles[canonical] {+ return "", fmt.Errorf("Hermes active profile %q in %s is not a valid profile name", name, activePath)+ }+ dir := filepath.Join(root, "profiles", canonical)+ if info, err := sessionfs.Stat(dir); err != nil || !info.IsDir() {+ return "", fmt.Errorf("Hermes active profile %q in %s does not exist: %s is not a directory", name, activePath, dir)+ }+ return dir, nil+}++var hermesEnvReference = regexp.MustCompile(`\$\{([^}]*)\}|\$([A-Za-z0-9_]+)`)++// hermesExpandVars expands $VAR and ${VAR} like Python's os.path.expandvars, which Hermes+// uses: references to unset variables are left as written.+func hermesExpandVars(path string) string {+ return hermesEnvReference.ReplaceAllStringFunc(path, func(reference string) string {+ parts := hermesEnvReference.FindStringSubmatch(reference)+ name := parts[1]+ if parts[2] != "" {+ name = parts[2]+ }+ if value, ok := os.LookupEnv(name); ok {+ return value+ }+ return reference+ })+}diff --git a/cli/beacon/internal/hermessession/home_test.go b/cli/beacon/internal/hermessession/home_test.gonew file mode 100644index 00000000..059b885c--- /dev/null+++ b/cli/beacon/internal/hermessession/home_test.go@@ -0,0 +1,275 @@+package hermessession++import (+ "os"+ "path/filepath"+ "runtime"+ "strings"+ "testing"++ "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/testenv"+)++// hermesFixtureHome moves the home directory to a temporary one, clears every variable that moves+// Hermes's home, and returns the home and the native root Hermes would use there.+func hermesFixtureHome(t *testing.T) (home, native string) {+ t.Helper()+ home = t.TempDir()+ testenv.SetHome(t, home)+ t.Setenv("HERMES_HOME", "")+ t.Setenv("HERMES_DATA_DIR_SUFFIX", "")+ t.Setenv("LOCALAPPDATA", filepath.Join(home, "LocalAppData"))+ native = filepath.Join(home, ".hermes")+ if runtime.GOOS == "windows" {+ native = filepath.Join(home, "LocalAppData", "hermes")+ }+ return home, native+}++func mkdirAll(t *testing.T, dirs ...string) {+ t.Helper()+ for _, dir := range dirs {+ if err := os.MkdirAll(dir, 0o755); err != nil {+ t.Fatal(err)+ }+ }+}++func writeActiveProfile(t *testing.T, root, content string) {+ t.Helper()+ mkdirAll(t, root)+ if err := os.WriteFile(filepath.Join(root, "active_profile"), []byte(content), 0o644); err != nil {+ t.Fatal(err)+ }+}++func homeDirOf(t *testing.T, home string) string {+ t.Helper()+ dir, err := HomeDir(home)+ if err != nil {+ t.Fatalf("HomeDir: %v", err)+ }+ return dir+}++func TestHomeDirFollowsHermesHome(t *testing.T) {+ home, native := hermesFixtureHome(t)+ work := t.TempDir()+ t.Chdir(work)+ cwd, err := os.Getwd()+ if err != nil {+ t.Fatal(err)+ }+ custom := filepath.Join(work, "hermes-data")+ t.Setenv("BEACON_HERMES_HOME_FIXTURE", custom)+ for _, tc := range []struct{ name, value, want string }{+ {"unset", "", native},+ {"blank", " \t ", native},+ {"absolute", custom, custom},+ {"trimmed", " " + custom + "\n", custom},+ {"relative", "hermes-data", filepath.Join(cwd, "hermes-data")},+ {"dot relative", "./hermes-data/", filepath.Join(cwd, "hermes-data")},+ {"tilde", "~", home},+ {"tilde path", "~/hermes-data", filepath.Join(home, "hermes-data")},+ {"variable", "$BEACON_HERMES_HOME_FIXTURE", custom},+ {"braced variable", "${BEACON_HERMES_HOME_FIXTURE}", custom},+ } {+ t.Run(tc.name, func(t *testing.T) {+ t.Setenv("HERMES_HOME", tc.value)+ got := homeDirOf(t, home)+ if got != tc.want {+ t.Fatalf("HomeDir with HERMES_HOME=%q = %q, want %q", tc.value, got, tc.want)+ }+ if !filepath.IsAbs(got) {+ t.Fatalf("HomeDir with HERMES_HOME=%q = %q, want an absolute path", tc.value, got)+ }+ if db := DefaultDBPath(); db != filepath.Join(tc.want, "state.db") {+ t.Fatalf("DefaultDBPath with HERMES_HOME=%q = %q, want %q", tc.value, db, filepath.Join(tc.want, "state.db"))+ }+ })+ }+}++func TestHomeOverrideIsEmptyOnlyWhenUnset(t *testing.T) {+ _, _ = hermesFixtureHome(t)+ for _, value := range []string{"", " "} {+ t.Setenv("HERMES_HOME", value)+ if got, err := HomeOverride(""); got != "" || err != nil {+ t.Fatalf("HomeOverride with HERMES_HOME=%q = %q, %v; want empty", value, got, err)+ }+ }+ work := t.TempDir()+ t.Chdir(work)+ cwd, err := os.Getwd()+ if err != nil {+ t.Fatal(err)+ }+ t.Setenv("HERMES_HOME", "relative/home")+ if got, err := HomeOverride(""); err != nil || got != filepath.Join(cwd, "relative", "home") {+ t.Fatalf("HomeOverride for a relative HERMES_HOME = %q, %v; want it made absolute", got, err)+ }+}++// `hermes profile use <name>` records the profile in <root>/active_profile, and the launcher moves+// HERMES_HOME to <root>/profiles/<name> for every later plain `hermes` command.+func TestHomeDirFollowsActiveProfile(t *testing.T) {+ home, native := hermesFixtureHome(t)+ work := filepath.Join(native, "profiles", "work")+ mkdirAll(t, work)+ for _, tc := range []struct{ name, content, want string }{+ {"no file", "", native},+ {"named", "work\n", work},+ {"trimmed", " work \r\n", work},+ {"case-insensitive", "Work", work},+ {"default", "default", native},+ {"default any case", "Default\n", native},+ {"blank", " \n", native},+ } {+ t.Run(tc.name, func(t *testing.T) {+ path := filepath.Join(native, "active_profile")+ _ = os.Remove(path)+ if tc.name != "no file" {+ writeActiveProfile(t, native, tc.content)+ }+ if got := homeDirOf(t, home); got != tc.want {+ t.Fatalf("HomeDir with active_profile %q = %q, want %q", tc.content, got, tc.want)+ }+ if db := DefaultDBPath(); db != filepath.Join(tc.want, "state.db") {+ t.Fatalf("DefaultDBPath with active_profile %q = %q, want %q", tc.content, db, filepath.Join(tc.want, "state.db"))+ }+ })+ }+}++// Hermes refuses to start when active_profile names a profile it cannot use, so Beacon reports the+// problem instead of using the default profile's directory.+func TestHomeDirRefusesUnusableActiveProfile(t *testing.T) {+ home, native := hermesFixtureHome(t)+ mkdirAll(t, filepath.Join(native, "profiles", "hermes"))+ for _, tc := range []struct{ name, content, want string }{+ {"missing", "gone", "does not exist"},+ {"traversal", "../../outside", "not a valid profile name"},+ {"separator", "a/b", "not a valid profile name"},+ {"reserved", "hermes", "not a valid profile name"},+ {"too long", strings.Repeat("a", 65), "not a valid profile name"},+ } {+ t.Run(tc.name, func(t *testing.T) {+ writeActiveProfile(t, native, tc.content)+ dir, err := HomeDir(home)+ if err == nil || !strings.Contains(err.Error(), tc.want) || !strings.Contains(err.Error(), "active_profile") {+ t.Fatalf("HomeDir with active_profile %q = %q, %v; want an error saying %q", tc.content, dir, err, tc.want)+ }+ // The session reader keeps reading the base directory's store.+ if db := DefaultDBPath(); db != filepath.Join(native, "state.db") {+ t.Fatalf("DefaultDBPath with an unusable profile = %q, want %q", db, filepath.Join(native, "state.db"))+ }+ })+ }+}++func TestHomeDirProfileRootFollowsHermesHome(t *testing.T) {+ home, native := hermesFixtureHome(t)+ nativeWork := filepath.Join(native, "profiles", "work")+ mkdirAll(t, nativeWork)+ writeActiveProfile(t, native, "work")++ t.Run("HERMES_HOME names a profile", func(t *testing.T) {+ // An explicit profile directory wins over the sticky profile.+ coder := filepath.Join(native, "profiles", "coder")+ mkdirAll(t, coder)+ t.Setenv("HERMES_HOME", coder)+ if got := homeDirOf(t, home); got != coder {+ t.Fatalf("HomeDir = %q, want the profile HERMES_HOME names, %q", got, coder)+ }+ })++ t.Run("HERMES_HOME names a profile that does not exist yet", func(t *testing.T) {+ later := filepath.Join(t.TempDir(), "profiles", "later")+ t.Setenv("HERMES_HOME", later)+ if got := homeDirOf(t, home); got != later {+ t.Fatalf("HomeDir = %q, want %q", got, later)+ }+ })++ t.Run("HERMES_HOME inside the native root", func(t *testing.T) {+ // The profile root is still the native root, so its sticky profile applies.+ t.Setenv("HERMES_HOME", filepath.Join(native, "custom"))+ if got := homeDirOf(t, home); got != nativeWork {+ t.Fatalf("HomeDir = %q, want the native root's active profile %q", got, nativeWork)+ }+ })++ t.Run("HERMES_HOME is the native root", func(t *testing.T) {+ // systemd units commonly hard-code HERMES_HOME=~/.hermes; the sticky profile still applies.+ t.Setenv("HERMES_HOME", native)+ if got := homeDirOf(t, home); got != nativeWork {+ t.Fatalf("HomeDir = %q, want %q", got, nativeWork)+ }+ })++ t.Run("HERMES_HOME elsewhere is its own profile root", func(t *testing.T) {+ data := t.TempDir()+ t.Setenv("HERMES_HOME", data)+ if got := homeDirOf(t, home); got != data {+ t.Fatalf("HomeDir = %q, want %q: the native root's active_profile does not apply", got, data)+ }+ research := filepath.Join(data, "profiles", "research")+ mkdirAll(t, research)+ writeActiveProfile(t, data, "research")+ if got := homeDirOf(t, home); got != research {+ t.Fatalf("HomeDir = %q, want %q", got, research)+ }+ if db := DefaultDBPath(); db != filepath.Join(research, "state.db") {+ t.Fatalf("DefaultDBPath = %q, want %q", db, filepath.Join(research, "state.db"))+ }+ })+}++func TestHomeDirFollowsActiveProfileUnderSuffixedRoot(t *testing.T) {+ home, native := hermesFixtureHome(t)+ t.Setenv("HERMES_DATA_DIR_SUFFIX", "-dev")+ suffixed := native + "-dev"+ work := filepath.Join(suffixed, "profiles", "work")+ mkdirAll(t, work)+ // The unsuffixed root's sticky profile belongs to another installation.+ writeActiveProfile(t, native, "other")+ if got := homeDirOf(t, home); got != suffixed {+ t.Fatalf("HomeDir = %q, want the suffixed root %q", got, suffixed)+ }+ writeActiveProfile(t, suffixed, "work")+ if got := homeDirOf(t, home); got != work {+ t.Fatalf("HomeDir = %q, want %q", got, work)+ }+}++func TestHomeDirNeedsAHome(t *testing.T) {+ _, _ = hermesFixtureHome(t)+ t.Setenv("LOCALAPPDATA", "")+ if dir, err := HomeDir(""); err == nil {+ t.Fatalf("HomeDir with no home and no HERMES_HOME = %q, want an error", dir)+ }+ data := t.TempDir()+ t.Setenv("HERMES_HOME", data)+ if dir, err := HomeDir(""); err != nil || dir != data {+ t.Fatalf("HomeDir with only HERMES_HOME = %q, %v; want %q", dir, err, data)+ }+}++// Hermes compares resolved paths, so a HERMES_HOME reached through the real directory behind a+// symlinked ~/.hermes, even one that does not exist yet, is still inside the native root.+func TestHomeDirComparesResolvedPaths(t *testing.T) {+ if runtime.GOOS == "windows" {+ t.Skip("creating symlinks needs a privilege Windows runners do not grant by default")+ }+ home, native := hermesFixtureHome(t)+ real := t.TempDir()+ if err := os.Symlink(real, native); err != nil {+ t.Fatal(err)+ }+ mkdirAll(t, filepath.Join(real, "profiles", "work"))+ writeActiveProfile(t, real, "work")+ t.Setenv("HERMES_HOME", filepath.Join(real, "not-yet", "custom"))+ if got, want := homeDirOf(t, home), filepath.Join(native, "profiles", "work"); got != want {+ t.Fatalf("HomeDir = %q, want %q", got, want)+ }+}diff --git a/cli/beacon/internal/mcpconnect/targets.go b/cli/beacon/internal/mcpconnect/targets.goindex 168e40e1..4c82d35e 100644--- a/cli/beacon/internal/mcpconnect/targets.go+++ b/cli/beacon/internal/mcpconnect/targets.go@@ -11,6 +11,7 @@ import ("github.com/asymptote-labs/agent-beacon/cli/beacon/internal/codexsession""github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/harness""github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/hooks"+ "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/hermessession")// ServerName is the name Beacon registers the Beacon Cloud MCP server under in every harness.@@ -236,7 +237,7 @@ func Targets() []Target {{Name: "hermes", DisplayName: "Hermes Agent", Aliases: []string{"hermes", "hermes-agent"},manual: func(url string) string {- return "Add to ~/.hermes/config.yaml:\n" ++ return "Add to " + hermesConfigHint() + ":\n" +"mcp_servers:\n " + ServerName + ":\n url: " + url + "\n headers:\n Authorization: \"Bearer <token>\""},},@@ -321,6 +322,18 @@ func codexConfigPath(home string) (string, error) {return filepath.Join(dir, "config.toml"), nil}+// hermesConfigHint names the config.yaml a plain `hermes` reads, resolved through HERMES_HOME and+// the active profile as Hermes does. When that fails, it says why instead of naming a file Hermes+// would not read.+func hermesConfigHint() string {+ home, _ := os.UserHomeDir()+ dir, err := hermessession.HomeDir(home)+ if err != nil {+ return "config.yaml in your Hermes home (" + err.Error() + ")"+ }+ return filepath.Join(dir, "config.yaml")+}+// vscodeMCPPath is the user-profile mcp.json, next to the settings.json VS Code discovery uses.func vscodeMCPPath(string) (string, error) {settings, err := harness.VSCodeUserSettingsPath()diff --git a/docs/changelog/cli.mdx b/docs/changelog/cli.mdxindex 25c3bed0..44cdcb75 100644--- a/docs/changelog/cli.mdx+++ b/docs/changelog/cli.mdx@@ -11,6 +11,7 @@ Stay up to date with the latest changes to the Agent Beacon CLI.## October 2026+- **Hermes Agent install, hooks and inventory follow `HERMES_HOME` and the active profile** · `beacon endpoint hooks install|uninstall|status --harness hermes`, `beacon endpoint discover`, inventory and the `beacon mcp connect` hint now use `config.yaml` in the directory Hermes uses: `HERMES_HOME` when set, otherwise `~/.hermes` plus `HERMES_DATA_DIR_SUFFIX` (`%LOCALAPPDATA%\hermes` on Windows). They previously always used `~/.hermes/config.yaml`, so with `HERMES_HOME` set Hermes never loaded Beacon's hooks. All of these, and Hermes session status, sync and handoff, also follow a sticky profile selected with `hermes profile use`, as Hermes does. A per-user install or repair also writes `HERMES_HOME` and `HERMES_DATA_DIR_SUFFIX` into the scheduled inventory job, as it does `CODEX_HOME`. An `active_profile` naming a profile Hermes cannot use is an error, as Hermes treats it. A profile chosen for one command with `hermes -p` is still not followed.- **Concurrent hooks no longer clobber the per-session state file** · The hook adapter keeps a small `state.json` (session model, prompt-emitted flag, reprompt counts) that every hook process reads and rewrites. Two hooks running at once shared one temporary file, so one could fail with `rename ...: no such file or directory` and a surviving write could drop the other's change. Access is now serialized with a file lock and each write uses its own temporary file.- **Claude Code settings, sessions and inventory follow `CLAUDE_CONFIG_DIR`** · `beacon endpoint install`, `beacon endpoint hooks install --harness claude`, `beacon endpoint discover`, inventory, `beacon endpoint claude status` and `sync`, the session backfill and `beacon handoff` now use `$CLAUDE_CONFIG_DIR` when `CLAUDE_CONFIG_DIR` is set, as Claude Code does: `settings.json`, `.claude.json`, `skills` and `projects` all move with it. They previously always used `~/.claude` (and `~/.claude.json`), so with the variable set Claude Code never saw Beacon's OTLP settings or hooks, live capture silently recorded nothing, and session sync found no transcripts. A per-user install or repair also writes the resolved `CLAUDE_CONFIG_DIR` into the scheduled inventory job, as it does `CODEX_HOME`. Project-level `.claude/settings.json` is unchanged, and `--projects-dir` and `--claude-projects-dir` still override.- **Codex install, hooks and inventory follow `CODEX_HOME`** · `beacon endpoint install`, `beacon endpoint hooks install --harness codex`, `beacon endpoint discover` and inventory now read and write `$CODEX_HOME/config.toml` and `$CODEX_HOME/hooks.json` when `CODEX_HOME` is set, as Codex does. They previously always used `~/.codex`, so with `CODEX_HOME` set, Codex never saw the OTLP exporter or the SessionStart hook and live capture silently recorded nothing. A per-user install or repair also writes the resolved `CODEX_HOME` into the scheduled inventory job, which launchd and systemd start without your shell's environment. A `CODEX_HOME` that is not an existing directory is now an install error rather than a silent write to `~/.codex`. Project-level `.codex` files are unchanged.diff --git a/docs/cli/endpoint-discover.mdx b/docs/cli/endpoint-discover.mdxindex e145be76..57400b2c 100644--- a/docs/cli/endpoint-discover.mdx+++ b/docs/cli/endpoint-discover.mdx@@ -13,7 +13,7 @@ beacon endpoint discoverBeacon discovers local runtime surfaces and reports their telemetry configuration state, including whether supported configuration appears Beacon-managed or customer-managed. By default, discover prints detected targets. Add `--all` to include every supported runtime target, including runtimes that are not detected on the host. OpenClaw Gateway is discovered through its managed plugin, and its separate gateway OTLP export is validated through the `beacon endpoint integrations openclaw` commands after Gateway diagnostics export is configured.-Gemini CLI discovery looks for the `gemini` executable and `~/.gemini/settings.json`, then checks whether local OTLP telemetry is enabled for Beacon. VS Code discovery checks Copilot Chat OpenTelemetry configuration and reports Beacon-managed state when the OTLP endpoint points at Beacon's local receiver. GitHub Copilot CLI discovery looks for the `copilot` executable or `~/.copilot/config.json`, then validates that `COPILOT_OTEL_ENABLED=true` and the effective OTLP endpoint points at Beacon's local HTTP receiver, usually `http://127.0.0.1:4318`. Claude Code discovery looks for the `claude` executable and Claude settings paths; optional Claude hook status is available through `beacon endpoint hooks status --harness claude`. Antigravity CLI discovery looks for the `antigravity` or `antigravity-cli` executable, `~/.gemini/config`, or `./.agents`, then checks whether Beacon endpoint hooks are installed in `~/.gemini/config/hooks.json` or `./.agents/hooks.json`. Grok Build discovery checks whether Beacon's managed hook file is installed at `~/.grok/hooks/beacon-endpoint.json` or `./.grok/hooks/beacon-endpoint.json`. Hermes Agent discovery looks for the `hermes` executable or `~/.hermes`, then checks `~/.hermes/config.yaml` for Beacon-managed hooks, identified by the endpoint settings flags (`--log`, `--config`, `--cli`) or a legacy `BEACON_ENDPOINT_MODE=1` prefix, together with `--platform hermes`. OpenCode discovery looks for the `opencode` executable or `~/.config/opencode`, then checks whether Beacon's managed plugin is installed at `~/.config/opencode/plugins/beacon.ts`. Cline discovery looks for `~/.cline` and treats a `cline` executable as an additional signal rather than the deciding one, because Cline's VS Code and JetBrains hosts ship no executable; it then checks whether Beacon's managed plugin is installed at `~/.cline/plugins/beacon.ts`. Pi discovery looks for the `pi` executable and treats `~/.pi/agent` as an additional signal, because an npm, pnpm, or bun install is often absent from the inherited `PATH` while its state directory is not; it then reports whether Beacon's managed extension is installed at `~/.pi/agent/extensions/beacon.ts`, and reports a `beacon.ts` without Beacon's marker as disabled rather than enabled. Oh My Pi discovery looks for the `omp` executable and treats the resolved agent directory as an additional signal for the same reason as Pi; it then reports whether Beacon's managed extension is installed at `~/.omp/agent/extensions/beacon.ts`, and honors `PI_CODING_AGENT_DIR` and `PI_CONFIG_DIR` when resolving that path. OpenClaw Gateway discovery looks for the `openclaw` executable and treats the extensions directory as an additional signal, because a gateway is commonly run as a daemon under an account whose `PATH` this process did not inherit; it then reports whether Beacon's managed plugin is installed at `~/.openclaw/extensions/beacon-endpoint/`, honors `OPENCLAW_STATE_DIR` when resolving that path, and reports a plugin directory missing either manifest as disabled rather than enabled, because OpenClaw skips such a directory silently. fx discovery looks for the `fx` executable and treats `~/.fx` as an additional signal; because fx has no file Beacon writes into, its telemetry status reports how much of the session store under `~/.fx/sessions` has actually been collected rather than whether a marker is present, distinguishing "no sessions yet" from "sessions present and none collected" from "collected and current". Qwen Code discovery looks for the `qwen` executable and treats `~/.qwen` as an additional signal, because an npm or version-manager install is often absent from the inherited `PATH` while its config directory is not; it then checks `~/.qwen/settings.json` for Beacon hook commands carrying `--platform qwen`, reporting hooks turned off by `disableAllHooks` as disabled and invalid settings JSON as misconfigured rather than missing. Devin CLI discovery looks for the `devin` executable, `~/.config/devin`, or `./.devin`, then checks whether Beacon endpoint hooks are installed in `~/.config/devin/config.json` or `./.devin/hooks.v1.json`; `devin` remains a legacy alias for `devin-cli`. Devin Desktop discovery checks Cascade/Windsurf hook files at `~/.codeium/windsurf/hooks.json` or `./.windsurf/hooks.json`. Factory Droid discovery looks for the `droid` executable and validates the effective `OTEL_TELEMETRY_ENDPOINT` launch environment without treating customer-managed shell export values as Beacon-owned configuration. Set MDM-managed launch environments to Beacon's local OTLP HTTP receiver through MDM or another customer-owned launch policy.+Gemini CLI discovery looks for the `gemini` executable and `~/.gemini/settings.json`, then checks whether local OTLP telemetry is enabled for Beacon. VS Code discovery checks Copilot Chat OpenTelemetry configuration and reports Beacon-managed state when the OTLP endpoint points at Beacon's local receiver. GitHub Copilot CLI discovery looks for the `copilot` executable or `~/.copilot/config.json`, then validates that `COPILOT_OTEL_ENABLED=true` and the effective OTLP endpoint points at Beacon's local HTTP receiver, usually `http://127.0.0.1:4318`. Claude Code discovery looks for the `claude` executable and Claude settings paths; optional Claude hook status is available through `beacon endpoint hooks status --harness claude`. Antigravity CLI discovery looks for the `antigravity` or `antigravity-cli` executable, `~/.gemini/config`, or `./.agents`, then checks whether Beacon endpoint hooks are installed in `~/.gemini/config/hooks.json` or `./.agents/hooks.json`. Grok Build discovery checks whether Beacon's managed hook file is installed at `~/.grok/hooks/beacon-endpoint.json` or `./.grok/hooks/beacon-endpoint.json`. Hermes Agent discovery looks for the `hermes` executable or the Hermes home directory (`~/.hermes` by default, moved by `HERMES_HOME` and the active profile), then checks its `config.yaml` for Beacon-managed hooks, identified by the endpoint settings flags (`--log`, `--config`, `--cli`) or a legacy `BEACON_ENDPOINT_MODE=1` prefix, together with `--platform hermes`. OpenCode discovery looks for the `opencode` executable or `~/.config/opencode`, then checks whether Beacon's managed plugin is installed at `~/.config/opencode/plugins/beacon.ts`. Cline discovery looks for `~/.cline` and treats a `cline` executable as an additional signal rather than the deciding one, because Cline's VS Code and JetBrains hosts ship no executable; it then checks whether Beacon's managed plugin is installed at `~/.cline/plugins/beacon.ts`. Pi discovery looks for the `pi` executable and treats `~/.pi/agent` as an additional signal, because an npm, pnpm, or bun install is often absent from the inherited `PATH` while its state directory is not; it then reports whether Beacon's managed extension is installed at `~/.pi/agent/extensions/beacon.ts`, and reports a `beacon.ts` without Beacon's marker as disabled rather than enabled. Oh My Pi discovery looks for the `omp` executable and treats the resolved agent directory as an additional signal for the same reason as Pi; it then reports whether Beacon's managed extension is installed at `~/.omp/agent/extensions/beacon.ts`, and honors `PI_CODING_AGENT_DIR` and `PI_CONFIG_DIR` when resolving that path. OpenClaw Gateway discovery looks for the `openclaw` executable and treats the extensions directory as an additional signal, because a gateway is commonly run as a daemon under an account whose `PATH` this process did not inherit; it then reports whether Beacon's managed plugin is installed at `~/.openclaw/extensions/beacon-endpoint/`, honors `OPENCLAW_STATE_DIR` when resolving that path, and reports a plugin directory missing either manifest as disabled rather than enabled, because OpenClaw skips such a directory silently. fx discovery looks for the `fx` executable and treats `~/.fx` as an additional signal; because fx has no file Beacon writes into, its telemetry status reports how much of the session store under `~/.fx/sessions` has actually been collected rather than whether a marker is present, distinguishing "no sessions yet" from "sessions present and none collected" from "collected and current". Qwen Code discovery looks for the `qwen` executable and treats `~/.qwen` as an additional signal, because an npm or version-manager install is often absent from the inherited `PATH` while its config directory is not; it then checks `~/.qwen/settings.json` for Beacon hook commands carrying `--platform qwen`, reporting hooks turned off by `disableAllHooks` as disabled and invalid settings JSON as misconfigured rather than missing. Devin CLI discovery looks for the `devin` executable, `~/.config/devin`, or `./.devin`, then checks whether Beacon endpoint hooks are installed in `~/.config/devin/config.json` or `./.devin/hooks.v1.json`; `devin` remains a legacy alias for `devin-cli`. Devin Desktop discovery checks Cascade/Windsurf hook files at `~/.codeium/windsurf/hooks.json` or `./.windsurf/hooks.json`. Factory Droid discovery looks for the `droid` executable and validates the effective `OTEL_TELEMETRY_ENDPOINT` launch environment without treating customer-managed shell export values as Beacon-owned configuration. Set MDM-managed launch environments to Beacon's local OTLP HTTP receiver through MDM or another customer-owned launch policy.## Flagsdiff --git a/docs/cli/endpoint-install.mdx b/docs/cli/endpoint-install.mdxindex f1833693..48f0af0c 100644--- a/docs/cli/endpoint-install.mdx+++ b/docs/cli/endpoint-install.mdx@@ -221,7 +221,7 @@ Install Hermes Agent hooks at the user level:beacon endpoint hooks install --harness hermes```-Hermes hooks write `~/.hermes/config.yaml` and support user-level installs only.+Hermes hooks write `config.yaml` in the Hermes home directory, which follows `HERMES_HOME` and the active profile (default `~/.hermes/config.yaml`; see [Hermes home and profiles](/runtimes/hermes-agent#hermes-home-and-profiles)), and support user-level installs only.Install Qwen Code hooks at the user level:diff --git a/docs/cli/endpoint-paths.mdx b/docs/cli/endpoint-paths.mdxindex dd9ad6b6..2e380f78 100644--- a/docs/cli/endpoint-paths.mdx+++ b/docs/cli/endpoint-paths.mdx@@ -61,7 +61,7 @@ Hook and plugin configuration is written to:| Devin Desktop | `~/.codeium/windsurf/hooks.json` | `./.windsurf/hooks.json` || Factory | `~/.factory/settings.json` | `./.factory/settings.json` || Grok Build | `~/.grok/hooks/beacon-endpoint.json` | `./.grok/hooks/beacon-endpoint.json` |-| Hermes Agent | `~/.hermes/config.yaml` | Not supported |+| Hermes Agent | `$HERMES_HOME/config.yaml` or the active profile's (default `~/.hermes/config.yaml`) | Not supported || OpenCode | `~/.config/opencode/plugins/beacon.ts` | `./.opencode/plugins/beacon.ts` || Pi | `~/.pi/agent/extensions/beacon.ts` | `./.pi/extensions/beacon.ts` || Qwen Code | `~/.qwen/settings.json` | `./.qwen/settings.json` |diff --git a/docs/cli/handoff.mdx b/docs/cli/handoff.mdxindex b91a57d9..8d82b7c7 100644--- a/docs/cli/handoff.mdx+++ b/docs/cli/handoff.mdx@@ -27,7 +27,7 @@ Sessions come from each runtime's own local session store, not from Beacon's run| Prime Agent | `~/.prime/agent`, both `sessions` and `session-artifacts` (or `PRIME_AGENT_CODING_AGENT_DIR`) | `prime` || Factory Droid | `~/.factory/sessions` | `droid` || GitHub Copilot CLI | `$COPILOT_HOME/session-state` when set; otherwise `~/.copilot/session-state` | `copilot` |-| Hermes Agent | `$HERMES_HOME/state.db` when set; otherwise `~/.hermes/state.db` (Windows: `%LOCALAPPDATA%/hermes/state.db`) | `hermes` |+| Hermes Agent | `state.db` in the [Hermes home](/runtimes/hermes-agent#hermes-home-and-profiles): `$HERMES_HOME` or the active profile when set; otherwise `~/.hermes/state.db` (Windows: `%LOCALAPPDATA%/hermes/state.db`) | `hermes` || DeepSeek Harness | `~/.dsh/sessions` (or under `DSH_HOME`) | `dsh` || fx | `~/.fx/sessions` | `fx` || Grok Build | `~/.grok/sessions` | `grok` |diff --git a/docs/cli/mcp-connect.mdx b/docs/cli/mcp-connect.mdxindex 5bded846..e3f4436e 100644--- a/docs/cli/mcp-connect.mdx+++ b/docs/cli/mcp-connect.mdx@@ -217,7 +217,7 @@ It prints the command or snippet instead, with a `<token>` placeholder for a tok- Devin Desktop: `~/.codeium/windsurf/mcp_config.json` (`serverUrl`)- Qwen Code: `~/.qwen/settings.json` (`httpUrl`)- Factory Droid: `droid mcp add beacon-managed <url> --type http --header …`-- Hermes Agent: `mcp_servers` in `~/.hermes/config.yaml`+- Hermes Agent: `mcp_servers` in `config.yaml` in the [Hermes home](/runtimes/hermes-agent#hermes-home-and-profiles) (`~/.hermes` unless `HERMES_HOME` or a profile is set)- Kimi Code: `kimi mcp add --transport http beacon-managed <url> --header …`- Antigravity CLI: `~/.gemini/antigravity/mcp_config.json` (`serverUrl`)diff --git a/docs/runtimes/hermes-agent.mdx b/docs/runtimes/hermes-agent.mdxindex 2cc9a804..8cf76691 100644--- a/docs/runtimes/hermes-agent.mdx+++ b/docs/runtimes/hermes-agent.mdx@@ -11,7 +11,7 @@ Beacon supports Hermes Agent through shell hook payloads sent to `beacon-hooks`,Before enabling Hermes Agent hooks, make sure:-- Hermes Agent is installed for the user or `~/.hermes/config.yaml` exists.+- Hermes Agent is installed for the user or its `config.yaml` exists in the Hermes home directory (see [Hermes home and profiles](#hermes-home-and-profiles)).- `beacon endpoint install` has run so shared endpoint config and runtime log paths exist.- Beacon hooks are installed with `beacon endpoint hooks install --harness hermes`.- Hermes hook consent is handled for the session, especially in non-interactive gateway, cron, or CI runs.@@ -19,7 +19,7 @@ Before enabling Hermes Agent hooks, make sure:## Collection path-Beacon merges shell-hook entries into `~/.hermes/config.yaml`. Hermes invokes Beacon's hook adapter for supported lifecycle, prompt, tool, approval, and subagent events, and the adapter writes normalized endpoint events to the configured runtime JSONL log.+Beacon merges shell-hook entries into the `config.yaml` of the Hermes home directory, `~/.hermes/config.yaml` by default. Hermes invokes Beacon's hook adapter for supported lifecycle, prompt, tool, approval, and subagent events, and the adapter writes normalized endpoint events to the configured runtime JSONL log.Beacon can also read Hermes Agent's committed SQLite session store:@@ -28,11 +28,11 @@ beacon endpoint hermes statusbeacon endpoint hermes sync```-The sync path reads `~/.hermes/state.db` locally and offline. It writes mapped events with `harness.collection_method=poll`, so it can recover historical sessions or sessions that ran before hooks were installed, but it cannot hold, approve, deny, or delay tool calls.+The sync path reads the home directory's `state.db` (`~/.hermes/state.db` by default) locally and offline. It writes mapped events with `harness.collection_method=poll`, so it can recover historical sessions or sessions that ran before hooks were installed, but it cannot hold, approve, deny, or delay tool calls.## Discovery and status-Beacon detects Hermes through the `hermes` executable or a local `~/.hermes` directory, then checks `~/.hermes/config.yaml` for Beacon-managed commands, identified by the endpoint settings flags (`--log`, `--config`, `--cli`) or a legacy `BEACON_ENDPOINT_MODE=1` prefix, together with `--platform hermes`.+Beacon detects Hermes through the `hermes` executable or the Hermes home directory, then checks that directory's `config.yaml` for Beacon-managed commands, identified by the endpoint settings flags (`--log`, `--config`, `--cli`) or a legacy `BEACON_ENDPOINT_MODE=1` prefix, together with `--platform hermes`.Use `beacon endpoint hooks status --harness hermes` to inspect Hermes Agent hook status. Use `beacon endpoint hermes status` to inspect committed local sessions and how much Beacon has synced.@@ -46,6 +46,20 @@ beacon endpoint hooks install --harness hermesHermes Agent hooks support user-level config only. Project-level installs are rejected because Hermes reads shell hooks from the user's Hermes config.+## Hermes home and profiles++Hook install, uninstall and status, discovery, inventory, and session status, sync and handoff all resolve one Hermes home directory, the one a plain `hermes` command uses:++1. The base directory is `HERMES_HOME` when it is set in Beacon's environment, trimmed, with a leading `~/` and `$VAR`/`${VAR}` references expanded, and a relative value taken from the current directory. Otherwise it is Hermes's native root: `~/.hermes` on macOS/Linux or `%LOCALAPPDATA%/hermes` on Windows, with `HERMES_DATA_DIR_SUFFIX` appended when set.+2. A `HERMES_HOME` that already names a profile, `<root>/profiles/<name>`, is used as it is.+3. Otherwise a sticky profile selected with `hermes profile use <name>`, which Hermes records in `<root>/active_profile`, moves the home to `<root>/profiles/<name>`. The root is the native root when `HERMES_HOME` is unset or inside it, and `HERMES_HOME` itself when it points elsewhere.++When `active_profile` names a profile that is not a valid name or has no directory, Hermes refuses to start. Hook install, uninstall and status then return an error naming the profile, discovery reports Hermes as `missing` with the reason, and inventory leaves out the Hermes config. Session status, sync and handoff keep reading the base directory's `state.db`.++A profile chosen for a single command with `hermes -p <name>` leaves nothing on disk, so Beacon cannot see it. Its hooks and sessions belong to `<root>/profiles/<name>`: run Beacon with `HERMES_HOME` set to that directory, or pass `--db <path>` to status/sync or `--store-dir hermes=<path>` to handoff.++The scheduled inventory job runs without your shell's environment, so a per-user install or repair records `HERMES_HOME` (as an absolute path) and `HERMES_DATA_DIR_SUFFIX` in the job when they are set. It does not record the active profile, so the job follows a later `hermes profile use` on its own. If you change either variable later, run `beacon endpoint repair` from a shell that has the new value. System-mode installs record neither.+## Telemetry coverage| Area | Support |@@ -60,7 +74,7 @@ Hermes Agent hooks support user-level config only. Project-level installs are re## Session database sync-`beacon endpoint hermes sync` reads committed rows from Hermes Agent's state database after Hermes has written them. Session status, sync, and handoff use `$HERMES_HOME/state.db` when `HERMES_HOME` is set in Beacon's environment, expanding a leading `~/` and `$VAR`/`${VAR}` references. Otherwise they use Hermes's native data root: `~/.hermes` on macOS/Linux or `%LOCALAPPDATA%/hermes` on Windows, with `HERMES_DATA_DIR_SUFFIX` appended when set. A profile selected only through `hermes -p` or `hermes profile use` is not followed; pass `--db <path>` to status/sync or `--store-dir hermes=<path>` to handoff to select its database explicitly.+`beacon endpoint hermes sync` reads committed rows from Hermes Agent's state database after Hermes has written them. Session status, sync, and handoff use the `state.db` in the [Hermes home directory](#hermes-home-and-profiles), following `HERMES_HOME` and a sticky profile. Pass `--db <path>` to status/sync or `--store-dir hermes=<path>` to handoff to select a database explicitly.The cursor is stored in Beacon endpoint state and advances by session message id. Use `--print` to preview mapped events without writing the runtime log or advancing the cursor.@@ -68,7 +82,7 @@ For scheduled collection, run `beacon endpoint hermes sync --watch`, or run one-## Deployment notes-Hermes prompts for first-use consent for each `(event, command)` hook pair. For non-interactive gateway, cron, or CI runs, set `HERMES_ACCEPT_HOOKS=1`, start Hermes with `--accept-hooks`, or configure `hooks_auto_accept: true` in `~/.hermes/config.yaml`.+Hermes prompts for first-use consent for each `(event, command)` hook pair. For non-interactive gateway, cron, or CI runs, set `HERMES_ACCEPT_HOOKS=1`, start Hermes with `--accept-hooks`, or configure `hooks_auto_accept: true` in the Hermes home directory's `config.yaml`.Beacon preserves existing Hermes settings and non-Beacon hooks when installing or uninstalling Hermes telemetry. It replaces only Beacon-managed Hermes hook commands.