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(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.goindex 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.goindex 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.allowInsecuret.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.goindex 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.allowInsecureif !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.goindex 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.goindex 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 = TelemetryMissingh.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.goindex 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.gonew file mode 100644index 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.goindex 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 nildiff --git a/cli/beacon/internal/endpoint/lifecycle/privilege_other.go b/cli/beacon/internal/endpoint/lifecycle/privilege_other.gonew file mode 100644index 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.gonew file mode 100644index 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.mdxindex b421d0b9..6e7f84e8 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 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.## Flagsdiff --git a/docs/cli/hooks.mdx b/docs/cli/hooks.mdxindex 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.mdxindex 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.shindex 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/nulltest -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" >&2exit 1fi