Skip to content

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

fix(windows): make system-mode install possible, and repair reach the right profile

shukieshah87ecf0cdf859
diff --git a/cli/beacon/cmd/endpoint_hooks_repair.go b/cli/beacon/cmd/endpoint_hooks_repair.go
index 40d07699..964acc57 100644
--- a/cli/beacon/cmd/endpoint_hooks_repair.go
+++ b/cli/beacon/cmd/endpoint_hooks_repair.go
@@ -7,6 +7,7 @@ import (
"os"
"os/exec"
"os/user"
+ "path/filepath"
"runtime"
"sort"
"strings"
@@ -150,19 +151,58 @@ func repairTargetOrder() []string {
return []string{"claude", "codex", "cursor", "vscode", "factory", "opencode", "grok", "hermes", "devin-cli", "devin-desktop", "antigravity"}
}
+// withUserHome runs fn as if it were executing inside another user's profile.
+//
+// Setting HOME alone was enough while every platform was POSIX. It is not on Windows:
+// os.UserHomeDir reads USERPROFILE there and ignores HOME entirely, so a system-mode repair would
+// resolve every runtime config path inside the *installing* account's profile and write hooks that
+// the person at the keyboard never runs -- the same silent shape as the Linux SUDO_USER bug this
+// whole code path exists to fix.
+//
+// APPDATA and LOCALAPPDATA come with it because several runtimes resolve their config from those
+// rather than from the profile root, and leaving them pointed at the installing account would move
+// the same bug one directory over. They are derived from the profile rather than read, since the
+// values in this process describe the wrong user by definition.
func withUserHome[T any](homeDir string, fn func() (T, error)) (T, error) {
- oldHome, hadHome := os.LookupEnv("HOME")
- _ = os.Setenv("HOME", homeDir)
+ restore := make([]func(), 0, 4)
+ for _, entry := range profileEnvironment(homeDir) {
+ key, value := entry[0], entry[1]
+ previous, existed := os.LookupEnv(key)
+ restore = append(restore, func() {
+ if existed {
+ _ = os.Setenv(key, previous)
+ } else {
+ _ = os.Unsetenv(key)
+ }
+ })
+ _ = os.Setenv(key, value)
+ }
defer func() {
- if hadHome {
- _ = os.Setenv("HOME", oldHome)
- } else {
- _ = os.Unsetenv("HOME")
+ for _, undo := range restore {
+ undo()
}
}()
return fn()
}
+// profileEnvironment lists the variables that make path resolution land in a given user's profile.
+//
+// Shared by the in-process path and the child-process one so the two cannot disagree about which
+// profile they are targeting.
+func profileEnvironment(homeDir string) [][2]string {
+ if runtime.GOOS != "windows" {
+ return [][2]string{{"HOME", homeDir}}
+ }
+ return [][2]string{
+ // HOME is still set: it is what Git and other POSIX-shaped tools on Windows read, and the
+ // hook commands Beacon writes are executed by Git Bash there.
+ {"HOME", homeDir},
+ {"USERPROFILE", homeDir},
+ {"APPDATA", filepath.Join(homeDir, "AppData", "Roaming")},
+ {"LOCALAPPDATA", filepath.Join(homeDir, "AppData", "Local")},
+ }
+}
+
// defaultActiveConsoleUser resolves the human whose runtime configuration a system install should
// reach.
//
@@ -330,6 +370,9 @@ func defaultRunHookRepairAsUser(info consoleUserInfo, args ...string) error {
}
ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
defer cancel()
+ if runtime.GOOS == "windows" {
+ return runHookRepairInProfile(ctx, bin, info, args...)
+ }
// runuser is the root-side tool for this and ships with util-linux, so it is present on a
// minimal Debian or RPM system where sudo may not be installed at all -- and a package
// postinstall runs as root, which is exactly runuser's precondition. sudo remains the path
@@ -352,3 +395,42 @@ func defaultRunHookRepairAsUser(info consoleUserInfo, args ...string) error {
}
return nil
}
+
+// runHookRepairInProfile re-runs this binary against another user's profile on Windows.
+//
+// There is no sudo and no runuser there. The POSIX path uses them to *drop* privileges so the files it
+// writes end up owned by the person whose profile they live in; Windows has no comparable one-liner,
+// so this keeps the elevated identity and redirects the profile instead.
+//
+// That is a real difference, and it is acceptable for what these files are. A hook config written into
+// C:\Users\Jane\.cursor\ inherits that directory's ACL, which grants Jane full control -- so she can
+// read it, and her runtime can rewrite it, even though an administrator created it. What she does not
+// get is ownership, which nothing in this path depends on.
+//
+// The honest alternative is CreateProcessAsUser with the token WTS already hands back for the console
+// session, which would make the files hers outright. It is a good deal more code for a property no
+// caller relies on, so it is not done here rather than done badly.
+//
+// Still a child process rather than an in-process call, matching POSIX: the repair reconfigures global
+// state through env vars, and doing that inside the running process would leave a system install's own
+// paths pointed at a user profile if anything after it failed.
+func runHookRepairInProfile(ctx context.Context, bin string, info consoleUserInfo, args ...string) error {
+ cmd := exec.CommandContext(ctx, bin, args...)
+ env := os.Environ()
+ for _, entry := range profileEnvironment(info.HomeDir) {
+ env = append(env, entry[0]+"="+entry[1])
+ }
+ // Appended rather than replaced: a later assignment wins in Go's exec, so these override the
+ // inherited values while everything else the child needs -- PATH, SystemRoot -- survives. Dropping
+ // SystemRoot in particular makes Windows networking and crypto calls fail in ways that read as
+ // unrelated bugs.
+ cmd.Env = env
+ out, err := cmd.CombinedOutput()
+ if err != nil {
+ return fmt.Errorf("refresh hooks for %s: %s: %w", info.Username, strings.TrimSpace(string(out)), err)
+ }
+ if text := strings.TrimSpace(string(out)); text != "" {
+ fmt.Println(text)
+ }
+ return nil
+}
diff --git a/cli/beacon/cmd/endpoint_test.go b/cli/beacon/cmd/endpoint_test.go
index 30d8248f..5e7bca9c 100644
--- a/cli/beacon/cmd/endpoint_test.go
+++ b/cli/beacon/cmd/endpoint_test.go
@@ -1555,15 +1555,30 @@ func TestEndpointUpdateApplyFlagRegistered(t *testing.T) {
}
}
-func TestApplyUpdateRequiresRoot(t *testing.T) {
- if os.Geteuid() == 0 {
- t.Skip("root can apply updates")
+// TestApplyUpdateRequiresElevation asks the same question the code now asks.
+//
+// It used to check for the literal words "requires root", which is the POSIX spelling. That phrasing
+// was wrong on Windows in both directions: os.Geteuid returns -1 there so the guard could never pass,
+// and the advice it printed -- rerun with sudo -- names a command the platform does not have. The
+// requirement is elevation; what elevation is called is the platform's business.
+func TestApplyUpdateRequiresElevation(t *testing.T) {
+ if lifecycle.HasSystemPrivileges() {
+ t.Skip("an elevated process can apply updates")
}
oldAllow := endpointUpdateOpts.allowInsecure
t.Cleanup(func() { endpointUpdateOpts.allowInsecure = oldAllow })
endpointUpdateOpts.allowInsecure = false
- if err := applyUpdate(context.Background(), "0.0.1"); err == nil || !strings.Contains(err.Error(), "requires root") {
- t.Fatalf("applyUpdate error = %v, want root requirement", err)
+ err := applyUpdate(context.Background(), "0.0.1")
+ if err == nil {
+ t.Fatal("applyUpdate succeeded without elevation")
+ }
+ if !strings.Contains(err.Error(), "elevated privileges") {
+ t.Fatalf("applyUpdate error = %v, want it to name the elevation requirement", err)
+ }
+ // The advice has to be runnable on the platform that printed it.
+ if !strings.Contains(err.Error(), lifecycle.SystemPrivilegeHint()) {
+ t.Fatalf("applyUpdate error = %v, want it to carry this platform's hint (%q)",
+ err, lifecycle.SystemPrivilegeHint())
}
}
diff --git a/cli/beacon/cmd/endpoint_update.go b/cli/beacon/cmd/endpoint_update.go
index e2010874..b541f5b9 100644
--- a/cli/beacon/cmd/endpoint_update.go
+++ b/cli/beacon/cmd/endpoint_update.go
@@ -12,6 +12,7 @@ import (
"github.com/spf13/cobra"
endpointconfig "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/config"
+ "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/lifecycle"
"github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/selfupdate"
"github.com/asymptote-labs/agent-beacon/cli/beacon/internal/version"
)
@@ -203,8 +204,12 @@ func emitManualCheckEvent(opts selfupdate.CheckEventOptions) error {
func applyUpdate(parent context.Context, current string) error {
insecure := endpointUpdateOpts.allowInsecure
if !insecure {
- if os.Geteuid() != 0 {
- return fmt.Errorf("applying an update requires root; rerun with sudo")
+ // Asked through lifecycle so the answer and the advice match the platform. os.Geteuid
+ // returns -1 on Windows unconditionally, so the previous check rejected every apply there
+ // and told the operator to use sudo -- advice that does not exist on the platform it was
+ // printed on.
+ if !lifecycle.HasSystemPrivileges() {
+ return fmt.Errorf("applying an update needs elevated privileges; %s", lifecycle.SystemPrivilegeHint())
}
if install := detectUpdateInstall(); !install.SupportsSeamlessUpdate() {
return fmt.Errorf("automatic apply is only supported for the system package install (detected: %s)", install.Kind)
diff --git a/cli/beacon/cmd/endpoint_update_service.go b/cli/beacon/cmd/endpoint_update_service.go
index 0b4571d1..4ce09231 100644
--- a/cli/beacon/cmd/endpoint_update_service.go
+++ b/cli/beacon/cmd/endpoint_update_service.go
@@ -13,6 +13,7 @@ import (
"github.com/spf13/cobra"
endpointconfig "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/config"
+ "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/lifecycle"
"github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/selfupdate"
"github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/service"
"github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/writer"
@@ -117,8 +118,8 @@ func setConfigAutoUpdateModeAt(path, mode string) error {
}
func requireRootForUpdater() error {
- if os.Geteuid() != 0 {
- return fmt.Errorf("managing the background updater requires root; rerun with sudo")
+ if !lifecycle.HasSystemPrivileges() {
+ return fmt.Errorf("managing the background updater needs elevated privileges; %s", lifecycle.SystemPrivilegeHint())
}
return nil
}
diff --git a/cli/beacon/internal/endpoint/harness/harness.go b/cli/beacon/internal/endpoint/harness/harness.go
index fbe2e5fe..9edccce5 100644
--- a/cli/beacon/internal/endpoint/harness/harness.go
+++ b/cli/beacon/internal/endpoint/harness/harness.go
@@ -7,9 +7,11 @@ import (
"os"
"os/exec"
"path/filepath"
+ "runtime"
"strings"
"time"
+ "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/integrations/cowork"
"gopkg.in/yaml.v3"
)
@@ -277,9 +279,16 @@ func DiscoverDevinDesktop() Harness {
func DiscoverClaudeCowork() Harness {
h := Harness{Name: "claude_cowork", DisplayName: "Claude Cowork", Capability: "admin_otel"}
- if fileExists("/Applications/Claude.app/Contents/Info.plist") {
- h.Detected = true
- h.ExecutablePath = "/Applications/Claude.app"
+ // Detection asks the cowork package where Claude Desktop lives, rather than keeping a second copy
+ // of that list here. The two answers were allowed to drift and did: this one knew only the macOS
+ // path, so a Windows machine with Claude Desktop installed reported it as absent -- and an operator
+ // could not tell that from a machine that genuinely does not have it.
+ for _, path := range cowork.DesktopPathsForOS(runtime.GOOS) {
+ if dirExists(path) {
+ h.Detected = true
+ h.ExecutablePath = path
+ break
+ }
}
h.TelemetryStatus = TelemetryMissing
h.Message = "Claude Cowork telemetry is configured in Claude organization settings"
diff --git a/cli/beacon/internal/endpoint/integrations/cowork/cowork.go b/cli/beacon/internal/endpoint/integrations/cowork/cowork.go
index c68e4084..7dd2e683 100644
--- a/cli/beacon/internal/endpoint/integrations/cowork/cowork.go
+++ b/cli/beacon/internal/endpoint/integrations/cowork/cowork.go
@@ -78,6 +78,44 @@ Notes:
`, AdminURL, cfg.Endpoint, cfg.Protocol, headerText(cfg.Headers), resourceAttributesText(cfg.ResourceAttributes), MinVersion)
}
+// DesktopPathsForOS lists where Claude Desktop is installed on a given platform.
+//
+// Claude Cowork is configured in organization settings rather than locally, so all Beacon does here is
+// report whether the app is present -- which it could only ever answer for macOS, because the only
+// path it knew was /Applications/Claude.app. On Windows that meant a machine with Claude Desktop
+// installed reported it as absent, and the operator had no way to tell that from a machine without it.
+//
+// Parameterized on goos rather than reading runtime.GOOS, following vscodeUserDataDirsForOS: it makes
+// every platform's answer testable from a maintainer's Mac, so only genuinely OS-bound behavior needs
+// a runner.
+//
+// Windows has no per-user Applications directory to check as a fallback, and Claude Desktop installs
+// per-user under %LOCALAPPDATA%, so that is the whole list there. Read from the environment with a
+// fallback rather than hardcoded, since a redirected profile must not be missed.
+func DesktopPathsForOS(goos string) []string {
+ switch goos {
+ case "darwin":
+ return []string{
+ "/Applications/Claude.app",
+ filepath.Join(os.Getenv("HOME"), "Applications", "Claude.app"),
+ }
+ case "windows":
+ local := os.Getenv("LOCALAPPDATA")
+ if local == "" {
+ home, err := os.UserHomeDir()
+ if err != nil {
+ return nil
+ }
+ local = filepath.Join(home, "AppData", "Local")
+ }
+ return []string{filepath.Join(local, "AnthropicClaude")}
+ default:
+ // Claude Desktop does not ship for Linux. Returning nothing is the honest answer, and it is
+ // distinct from "looked and did not find it".
+ return nil
+ }
+}
+
func GetStatus(logPath string) Status {
status := Status{
Name: Name,
@@ -86,16 +124,11 @@ func GetStatus(logPath string) Status {
Configuration: "admin_configured",
Message: "Configure Claude Cowork in Claude Desktop organization settings",
}
- if runtime.GOOS == "darwin" {
- for _, path := range []string{
- "/Applications/Claude.app",
- filepath.Join(os.Getenv("HOME"), "Applications", "Claude.app"),
- } {
- if info, err := os.Stat(path); err == nil && info.IsDir() {
- status.Detected = true
- status.DesktopPath = path
- break
- }
+ for _, path := range DesktopPathsForOS(runtime.GOOS) {
+ if info, err := os.Stat(path); err == nil && info.IsDir() {
+ status.Detected = true
+ status.DesktopPath = path
+ break
}
}
if last, ok := LastCoworkEvent(logPath); ok {
diff --git a/cli/beacon/internal/endpoint/integrations/cowork/desktop_paths_test.go b/cli/beacon/internal/endpoint/integrations/cowork/desktop_paths_test.go
new file mode 100644
index 00000000..8a51e464
--- /dev/null
+++ b/cli/beacon/internal/endpoint/integrations/cowork/desktop_paths_test.go
@@ -0,0 +1,55 @@
+package cowork
+
+import (
+ "path/filepath"
+ "strings"
+ "testing"
+)
+
+// TestDesktopPathsForOSAnswersForEveryPlatform is why this takes goos as a parameter.
+//
+// Detection previously knew one path, /Applications/Claude.app, so on Windows a machine with Claude
+// Desktop installed reported it as absent -- indistinguishable from one that does not have it. Taking
+// goos rather than reading runtime.GOOS means every platform's answer is checkable from any machine,
+// which is the convention vscodeUserDataDirsForOS already set.
+func TestDesktopPathsForOSAnswersForEveryPlatform(t *testing.T) {
+ t.Run("darwin looks in both Applications directories", func(t *testing.T) {
+ paths := DesktopPathsForOS("darwin")
+ if len(paths) != 2 {
+ t.Fatalf("darwin paths = %#v, want the system and per-user Applications directories", paths)
+ }
+ if paths[0] != "/Applications/Claude.app" {
+ t.Fatalf("darwin paths[0] = %q", paths[0])
+ }
+ })
+
+ t.Run("windows reads LOCALAPPDATA", func(t *testing.T) {
+ t.Setenv("LOCALAPPDATA", filepath.Join("D:", "Redirected", "Local"))
+ paths := DesktopPathsForOS("windows")
+ want := filepath.Join("D:", "Redirected", "Local", "AnthropicClaude")
+ if len(paths) != 1 || paths[0] != want {
+ t.Fatalf("windows paths = %#v, want [%q]; a redirected profile must not be missed", paths, want)
+ }
+ })
+
+ t.Run("windows falls back when LOCALAPPDATA is unset", func(t *testing.T) {
+ // A service or scheduled task can run with a minimal environment. Returning nothing there
+ // would report Claude Desktop as absent for a reason that has nothing to do with Claude.
+ t.Setenv("LOCALAPPDATA", "")
+ paths := DesktopPathsForOS("windows")
+ if len(paths) != 1 {
+ t.Fatalf("windows paths with no LOCALAPPDATA = %#v, want one fallback path", paths)
+ }
+ if !strings.HasSuffix(paths[0], filepath.Join("AppData", "Local", "AnthropicClaude")) {
+ t.Fatalf("fallback path = %q, want it under AppData\\Local", paths[0])
+ }
+ })
+
+ t.Run("linux has nowhere to look", func(t *testing.T) {
+ // Claude Desktop does not ship for Linux, and "there is nowhere to look" is a different
+ // statement from "looked and did not find it".
+ if paths := DesktopPathsForOS("linux"); paths != nil {
+ t.Fatalf("linux paths = %#v, want none", paths)
+ }
+ })
+}
diff --git a/cli/beacon/internal/endpoint/lifecycle/lifecycle.go b/cli/beacon/internal/endpoint/lifecycle/lifecycle.go
index a3bc6864..b7b003a1 100644
--- a/cli/beacon/internal/endpoint/lifecycle/lifecycle.go
+++ b/cli/beacon/internal/endpoint/lifecycle/lifecycle.go
@@ -624,8 +624,9 @@ func preflight(cfg endpointconfig.Config, startService bool, kind service.Kind)
}
return fmt.Errorf("--service=%s is not usable here: %s", kind, reason)
}
- if !cfg.UserMode && os.Geteuid() != 0 {
- return fmt.Errorf("system install requires root; rerun with sudo or omit --system for the default user install")
+ if !cfg.UserMode && !HasSystemPrivileges() {
+ return fmt.Errorf("system install needs elevated privileges; %s, or omit --system for the default user install",
+ SystemPrivilegeHint())
}
if !startService {
return nil
diff --git a/cli/beacon/internal/endpoint/lifecycle/privilege_other.go b/cli/beacon/internal/endpoint/lifecycle/privilege_other.go
new file mode 100644
index 00000000..b9be99fd
--- /dev/null
+++ b/cli/beacon/internal/endpoint/lifecycle/privilege_other.go
@@ -0,0 +1,17 @@
+//go:build !windows
+
+package lifecycle
+
+import "os"
+
+// HasSystemPrivileges reports whether this process may write machine-wide state.
+//
+// Root, which is what /etc, /Library and /var/log all require and what launchd and systemd require to
+// register a system service.
+func HasSystemPrivileges() bool {
+ return os.Geteuid() == 0
+}
+
+func SystemPrivilegeHint() string {
+ return "rerun with sudo"
+}
diff --git a/cli/beacon/internal/endpoint/lifecycle/privilege_windows.go b/cli/beacon/internal/endpoint/lifecycle/privilege_windows.go
new file mode 100644
index 00000000..cf008405
--- /dev/null
+++ b/cli/beacon/internal/endpoint/lifecycle/privilege_windows.go
@@ -0,0 +1,30 @@
+//go:build windows
+
+package lifecycle
+
+import "golang.org/x/sys/windows"
+
+// HasSystemPrivileges reports whether this process may write machine-wide state.
+//
+// os.Geteuid returns -1 on Windows, unconditionally, so the POSIX check it replaces here rejected
+// every system-mode install on the platform -- including from a fully elevated administrator shell.
+// A dispatched run is what surfaced it: `beacon endpoint install --system` failed with "system install
+// requires root", which reads like a mistake by the operator rather than a check that cannot pass.
+//
+// Elevation rather than group membership. An administrator's *unelevated* token cannot write to
+// %ProgramData%\Beacon or open the Service Control Manager, so asking whether the account is in the
+// Administrators group would report yes and then fail at the first write -- halfway through an install.
+// IsElevated asks whether this process actually holds those rights now, which is the question.
+func HasSystemPrivileges() bool {
+ token, err := windows.OpenCurrentProcessToken()
+ if err != nil {
+ return false
+ }
+ defer token.Close()
+ return token.IsElevated()
+}
+
+// SystemPrivilegeHint is the platform's version of "rerun with sudo".
+func SystemPrivilegeHint() string {
+ return "run this from an elevated shell (right-click the terminal and choose Run as administrator)"
+}
diff --git a/docs/cli/endpoint-discover.mdx b/docs/cli/endpoint-discover.mdx
index b421d0b9..6e7f84e8 100644
--- a/docs/cli/endpoint-discover.mdx
+++ b/docs/cli/endpoint-discover.mdx
@@ -13,7 +13,7 @@ beacon endpoint discover
Beacon 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 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 shell hooks with `BEACON_ENDPOINT_MODE=1` and `--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`. 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 `~/.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`. 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.
## Flags
diff --git a/docs/cli/hooks.mdx b/docs/cli/hooks.mdx
index 7ca9bc3d..7168fba5 100644
--- a/docs/cli/hooks.mdx
+++ b/docs/cli/hooks.mdx
@@ -393,7 +393,7 @@ If Grok telemetry is missing, check the selected level, confirm the hook file co
## Hermes Agent troubleshooting
-Beacon merges Hermes Agent hooks into `~/.hermes/config.yaml`. Hermes hooks are user-level only; project-level install, status, or uninstall requests return a clear error. Beacon preserves existing Hermes settings and non-Beacon hooks, and replaces only Beacon-managed commands with `BEACON_ENDPOINT_MODE=1` and `--platform hermes`.
+Beacon merges Hermes Agent hooks into `~/.hermes/config.yaml`. Hermes hooks are user-level only; project-level install, status, or uninstall requests return a clear error. Beacon preserves existing Hermes settings and non-Beacon hooks, and replaces only Beacon-managed commands, identified by the endpoint settings flags (`--log`, `--config`, `--cli`) or a legacy `BEACON_ENDPOINT_MODE=1` prefix, together with `--platform hermes`.
If Hermes telemetry is missing, confirm `~/.hermes/config.yaml` contains commands with `--platform hermes`, restart Hermes, and verify hook consent. Hermes prompts for first-use consent for each `(event, command)` 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`.
diff --git a/docs/runtimes/hermes-agent.mdx b/docs/runtimes/hermes-agent.mdx
index a7cff80d..5f3b2b6b 100644
--- a/docs/runtimes/hermes-agent.mdx
+++ b/docs/runtimes/hermes-agent.mdx
@@ -23,7 +23,7 @@ Asymptote merges shell-hook entries into `~/.hermes/config.yaml`. Hermes invokes
## Discovery and status
-Asymptote detects Hermes through the `hermes` executable or a local `~/.hermes` directory, then checks `~/.hermes/config.yaml` for Asymptote-managed commands with `BEACON_ENDPOINT_MODE=1` and `--platform hermes`.
+Asymptote detects Hermes through the `hermes` executable or a local `~/.hermes` directory, then checks `~/.hermes/config.yaml` for Asymptote-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.
diff --git a/packaging/macos/smoke-endpoint.sh b/packaging/macos/smoke-endpoint.sh
index 4ba9fc6b..8711b9f2 100755
--- a/packaging/macos/smoke-endpoint.sh
+++ b/packaging/macos/smoke-endpoint.sh
@@ -111,8 +111,17 @@ run_beacon endpoint hooks install --harness cursor --user --log-path "$LOG_PATH"
run_beacon endpoint hooks status --harness cursor --user --log-path "$LOG_PATH" >/dev/null
test -f "$HOME_DIR/.cursor/hooks.json"
-if ! grep -q 'BEACON_ENDPOINT_MODE=1' "$HOME_DIR/.cursor/hooks.json"; then
- echo "expected Beacon hook command in Cursor hooks.json" >&2
+# The installed command passes its settings as flags rather than as an inline BEACON_ENDPOINT_MODE=1
+# prefix, so that prefix is no longer what identifies a Beacon hook. Asserting the log flag and the
+# platform instead: the flag is what makes it an endpoint hook, and the platform is what scopes it to
+# this runtime.
+if ! grep -q -- "--log " "$HOME_DIR/.cursor/hooks.json"; then
+ echo "expected Beacon hook command with --log in Cursor hooks.json" >&2
+ exit 1
+fi
+
+if ! grep -q -- "--platform cursor" "$HOME_DIR/.cursor/hooks.json"; then
+ echo "expected Beacon hook command scoped to cursor in Cursor hooks.json" >&2
exit 1
fi