Skip to content

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

fix diagnostics

Justin D'Souza396184722ce6
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index f8e15834..e3ad4d5d 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -43,10 +43,16 @@ jobs:
runs-on: macos-latest
steps:
- uses: actions/checkout@v4
+ - uses: actions/setup-go@v5
+ with:
+ go-version-file: cli/beacon/go.mod
- name: Validate packaging scripts
run: |
test -x packaging/macos/install-endpoint.sh
test -x packaging/macos/uninstall-endpoint.sh
+ test -x packaging/macos/smoke-endpoint.sh
test -f collector-builder/builder.yaml
sh packaging/macos/test-endpoint-scripts.sh
+ - name: Endpoint install smoke test
+ run: sh packaging/macos/smoke-endpoint.sh
diff --git a/CLAUDE.md b/CLAUDE.md
index 1e810fc0..ef289d8b 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -61,6 +61,12 @@ Run packaging wrapper checks:
sh packaging/macos/test-endpoint-scripts.sh
```
+Run the macOS endpoint smoke test:
+
+```bash
+sh packaging/macos/smoke-endpoint.sh
+```
+
Build the CLI:
```bash
@@ -91,6 +97,7 @@ go run . endpoint dashboard --user
- Preserve optional event fields for agent-native metadata (`session`, `tool`, `file`, `command`, `mcp`, `approval`, `content`, `model`, `repository`, and `branch`) without changing existing required field semantics.
- Prefer metadata-first telemetry. If adding a new signal, include stable identifiers/counts/hashes before considering raw content.
- Keep the dashboard read-only. It should inspect local status and JSONL events but must not mutate endpoint configuration or telemetry.
+- Keep the release readiness guidance in `README.md` up to date when install, packaging, collector, or dashboard behavior changes.
## CI Expectations
@@ -102,3 +109,4 @@ CI runs:
- `go test ./...` in `collector-builder/exporter/beaconjsonexporter`.
- CLI help smoke checks for the public command tree.
- macOS packaging script validation via `packaging/macos/test-endpoint-scripts.sh`.
+- macOS endpoint smoke validation via `packaging/macos/smoke-endpoint.sh`.
diff --git a/README.md b/README.md
index 26a9a77a..f87a8915 100644
--- a/README.md
+++ b/README.md
@@ -71,6 +71,12 @@ Print Wazuh config and validate event output:
./beacon endpoint wazuh validate --user
```
+Run the macOS endpoint smoke test:
+
+```bash
+sh packaging/macos/smoke-endpoint.sh
+```
+
Optional integrations:
```bash
@@ -111,6 +117,47 @@ Uninstall:
`beaconjson` exporter.
- `packaging`: macOS packaging and MDM deployment assets.
+## Release Readiness
+
+Production pilots should use versioned artifacts rather than asking users to
+build Beacon from source. A release should include the `beacon` CLI with a
+platform-matched embedded hook adapter, the `beacon-otelcol` collector
+distribution, Wazuh content, SHA-256 checksums, and concise notes covering
+supported runtimes, content-retention defaults, log paths, and uninstall
+behavior.
+
+For macOS pilots, ship a signed and notarized package or Homebrew formula that
+installs the CLI, collector, Wazuh content pack, and deployment scripts. The
+package should apply explicit endpoint settings, for example:
+
+```bash
+beacon endpoint install --harness claude,codex --content-retention metadata
+```
+
+Before handing a build to a security team, verify the release from a clean
+checkout and clean macOS host or VM:
+
+- `beacon version` reports the expected version, commit, and build date.
+- `beacon endpoint install --user --no-start` succeeds without developer
+ tooling.
+- `beacon endpoint status --user` reports config, collector, service, harness,
+ diagnostic, and runtime log paths.
+- `beacon endpoint wazuh validate --user` writes a valid Beacon JSONL event.
+- `beacon endpoint dashboard --user` starts on `127.0.0.1`.
+- `beacon endpoint uninstall --user` removes managed service and config files.
+- macOS package signature and notarization are valid when distributing a `.pkg`.
+
+The repository smoke test keeps this flow local and non-root:
+
+```bash
+sh packaging/macos/smoke-endpoint.sh
+```
+
+It builds a temporary Beacon binary, uses a temporary `HOME`, runs a user-mode
+install with `--no-start`, validates status and Wazuh output, checks Cursor hook
+install/status, uninstalls, and preserves the runtime log long enough to assert
+expected events were written. The script skips automatically on non-macOS hosts.
+
## Test
```bash
diff --git a/cli/beacon/cmd/endpoint.go b/cli/beacon/cmd/endpoint.go
index d51c6c08..323a40b6 100644
--- a/cli/beacon/cmd/endpoint.go
+++ b/cli/beacon/cmd/endpoint.go
@@ -24,6 +24,7 @@ var endpointOpts struct {
userMode bool
logPath string
harnesses string
+ hookHarnesses string
outputDir string
jsonOutput bool
grpcPort int
@@ -273,7 +274,7 @@ func init() {
for _, c := range []*cobra.Command{endpointHooksInstallCmd, endpointHooksUninstallCmd, endpointHooksStatusCmd} {
c.Flags().BoolVar(&endpointOpts.userMode, "user", false, "Use per-user endpoint paths instead of system paths")
c.Flags().StringVar(&endpointOpts.logPath, "log-path", "", "Runtime JSONL log path")
- c.Flags().StringVar(&endpointOpts.harnesses, "harness", "cursor", "Comma-separated hook harnesses")
+ c.Flags().StringVar(&endpointOpts.hookHarnesses, "harness", "cursor", "Comma-separated hook harnesses")
c.Flags().StringVar(&endpointOpts.hookLevel, "level", "user", "Hook install level: user or project")
}
endpointHooksStatusCmd.Flags().BoolVar(&endpointOpts.jsonOutput, "json", false, "Print status as JSON")
@@ -283,7 +284,7 @@ func init() {
func runEndpointHooksInstall(cmd *cobra.Command, args []string) error {
cfg := loadOrDefaultConfig()
- for _, name := range splitCSV(endpointOpts.harnesses) {
+ for _, name := range splitCSV(endpointOpts.hookHarnesses) {
switch strings.TrimSpace(name) {
case "cursor":
status, err := endpointhooks.InstallCursor(endpointhooks.CursorOptions{
@@ -305,7 +306,7 @@ func runEndpointHooksInstall(cmd *cobra.Command, args []string) error {
func runEndpointHooksUninstall(cmd *cobra.Command, args []string) error {
cfg := loadOrDefaultConfig()
- for _, name := range splitCSV(endpointOpts.harnesses) {
+ for _, name := range splitCSV(endpointOpts.hookHarnesses) {
switch strings.TrimSpace(name) {
case "cursor":
status, err := endpointhooks.UninstallCursor(endpointhooks.CursorOptions{
diff --git a/cli/beacon/cmd/endpoint_test.go b/cli/beacon/cmd/endpoint_test.go
index cd2b8880..a0c6983e 100644
--- a/cli/beacon/cmd/endpoint_test.go
+++ b/cli/beacon/cmd/endpoint_test.go
@@ -30,3 +30,21 @@ func TestEndpointDashboardCommandRegistered(t *testing.T) {
t.Fatal("dashboard command missing --open flag")
}
}
+
+func TestEndpointHarnessDefaultsDoNotClobberInstall(t *testing.T) {
+ installFlag := endpointInstallCmd.Flags().Lookup("harness")
+ if installFlag == nil {
+ t.Fatal("install command missing --harness flag")
+ }
+ if got, want := installFlag.DefValue, "claude,codex"; got != want {
+ t.Fatalf("install --harness default = %q, want %q", got, want)
+ }
+
+ hooksFlag := endpointHooksInstallCmd.Flags().Lookup("harness")
+ if hooksFlag == nil {
+ t.Fatal("hooks install command missing --harness flag")
+ }
+ if got, want := hooksFlag.DefValue, "cursor"; got != want {
+ t.Fatalf("hooks install --harness default = %q, want %q", got, want)
+ }
+}
diff --git a/cli/beacon/internal/embedded/hooks.bin b/cli/beacon/internal/embedded/hooks.bin
index 4f2e970e..311c8dd0 100644
--- a/cli/beacon/internal/embedded/hooks.bin
+++ b/cli/beacon/internal/embedded/hooks.bin
@@ -1 +1 @@
-PLACEHOLDER
+PLACEHOLDER
\ No newline at end of file
diff --git a/cli/beacon/internal/endpoint/diagnostics/diagnostics.go b/cli/beacon/internal/endpoint/diagnostics/diagnostics.go
index 9199f0a7..f2e536ba 100644
--- a/cli/beacon/internal/endpoint/diagnostics/diagnostics.go
+++ b/cli/beacon/internal/endpoint/diagnostics/diagnostics.go
@@ -3,9 +3,11 @@ package diagnostics
import (
"fmt"
"os"
+ "path/filepath"
"runtime"
endpointconfig "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/config"
+ "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/service"
)
type Check struct {
@@ -70,9 +72,9 @@ func launchPlistPath(userMode bool) string {
if userMode {
home, err := os.UserHomeDir()
if err != nil {
- return "Library/LaunchAgents/com.beacon.endpoint.collector.plist"
+ return filepath.Join("Library", "LaunchAgents", service.UserLabel+".plist")
}
- return home + "/Library/LaunchAgents/com.beacon.endpoint.collector.plist"
+ return filepath.Join(home, "Library", "LaunchAgents", service.UserLabel+".plist")
}
- return "/Library/LaunchDaemons/com.beacon.endpoint.collector.plist"
+ return filepath.Join("/Library/LaunchDaemons", service.SystemLabel+".plist")
}
diff --git a/cli/beacon/internal/endpoint/diagnostics/diagnostics_test.go b/cli/beacon/internal/endpoint/diagnostics/diagnostics_test.go
index 97559fcd..57deb664 100644
--- a/cli/beacon/internal/endpoint/diagnostics/diagnostics_test.go
+++ b/cli/beacon/internal/endpoint/diagnostics/diagnostics_test.go
@@ -7,6 +7,7 @@ import (
"testing"
endpointconfig "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/config"
+ "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/service"
)
func TestCheckFileRequiredOptionalAndDirectory(t *testing.T) {
@@ -99,3 +100,20 @@ func TestRunAndHasFailures(t *testing.T) {
t.Fatal("expected HasFailures to report failed check")
}
}
+
+func TestLaunchPlistPathMatchesServiceManager(t *testing.T) {
+ home := t.TempDir()
+ t.Setenv("HOME", home)
+
+ userPath := launchPlistPath(true)
+ wantUserPath := filepath.Join(home, "Library", "LaunchAgents", service.UserLabel+".plist")
+ if userPath != wantUserPath {
+ t.Fatalf("user launchPlistPath = %q, want %q", userPath, wantUserPath)
+ }
+
+ systemPath := launchPlistPath(false)
+ wantSystemPath := filepath.Join("/Library/LaunchDaemons", service.SystemLabel+".plist")
+ if systemPath != wantSystemPath {
+ t.Fatalf("system launchPlistPath = %q, want %q", systemPath, wantSystemPath)
+ }
+}
diff --git a/packaging/macos/README.md b/packaging/macos/README.md
index 4350ec15..d7855c64 100644
--- a/packaging/macos/README.md
+++ b/packaging/macos/README.md
@@ -14,6 +14,18 @@ beacon endpoint status
beacon endpoint wazuh print-config
```
+## Smoke Test
+
+Run the non-root endpoint smoke test on a macOS host or VM:
+
+```bash
+sh packaging/macos/smoke-endpoint.sh
+```
+
+The smoke test builds a temporary Beacon binary, uses a temporary `HOME`, runs a
+user-mode install with `--no-start`, validates status/Wazuh output, installs
+Cursor hooks, and uninstalls while preserving the runtime log for assertions.
+
## MDM Install Script
Use `install-endpoint.sh` from Jamf, Kandji, or a generic macOS MDM command
diff --git a/packaging/macos/pkgbuild.md b/packaging/macos/pkgbuild.md
index 62d5771f..c809a7e8 100644
--- a/packaging/macos/pkgbuild.md
+++ b/packaging/macos/pkgbuild.md
@@ -18,5 +18,6 @@ Release gates:
- package signature verified with `pkgutil --check-signature`
- notarization accepted by Apple
- install/uninstall tested on a clean macOS runner or VM
+- `sh packaging/macos/smoke-endpoint.sh` passes on a clean macOS runner or VM
- Wazuh validation event successfully written after install
diff --git a/packaging/macos/smoke-endpoint.sh b/packaging/macos/smoke-endpoint.sh
new file mode 100755
index 00000000..f60aa992
--- /dev/null
+++ b/packaging/macos/smoke-endpoint.sh
@@ -0,0 +1,107 @@
+#!/bin/sh
+set -eu
+
+if [ "$(uname -s)" != "Darwin" ]; then
+ echo "Beacon endpoint smoke test is macOS-only; skipping on $(uname -s)."
+ exit 0
+fi
+
+ROOT_DIR="$(CDPATH= cd -- "$(dirname -- "$0")/../.." && pwd)"
+TMP_DIR="$(mktemp -d)"
+ORIGINAL_HOOKS="$TMP_DIR/hooks.bin.original"
+HOOKS_BIN="$ROOT_DIR/cli/beacon/internal/embedded/hooks.bin"
+
+cleanup() {
+ if [ -f "$ORIGINAL_HOOKS" ]; then
+ cp "$ORIGINAL_HOOKS" "$HOOKS_BIN"
+ chmod 644 "$HOOKS_BIN"
+ fi
+ rm -rf "$TMP_DIR"
+}
+trap cleanup EXIT INT TERM
+
+cp "$HOOKS_BIN" "$ORIGINAL_HOOKS"
+
+BIN_DIR="$TMP_DIR/bin"
+HOME_DIR="$TMP_DIR/home"
+LOG_PATH="$TMP_DIR/runtime.jsonl"
+COLLECTOR_BIN="$BIN_DIR/beacon-otelcol"
+BEACON_BIN="$BIN_DIR/beacon"
+
+mkdir -p "$BIN_DIR" "$HOME_DIR" "$HOME_DIR/Library/LaunchAgents"
+
+cat >"$COLLECTOR_BIN" <<'EOF'
+#!/bin/sh
+echo "fake beacon-otelcol for smoke test"
+EOF
+chmod +x "$COLLECTOR_BIN"
+
+echo "Building temporary beacon-hooks..."
+(
+ cd "$ROOT_DIR/cli/beacon-hooks"
+ go build -o "$HOOKS_BIN" .
+)
+
+echo "Building temporary beacon..."
+(
+ cd "$ROOT_DIR/cli/beacon"
+ go build -o "$BEACON_BIN" .
+)
+
+run_beacon() {
+ HOME="$HOME_DIR" "$BEACON_BIN" "$@"
+}
+
+echo "Installing endpoint config in temporary HOME..."
+run_beacon endpoint install \
+ --user \
+ --no-start \
+ --collector "$COLLECTOR_BIN" \
+ --log-path "$LOG_PATH" \
+ --harness claude,codex \
+ --otlp-grpc-port 55317 \
+ --otlp-http-port 55318 \
+ --content-retention metadata
+
+test -f "$HOME_DIR/.beacon/endpoint/config.json"
+test -f "$HOME_DIR/.beacon/endpoint/otelcol.yaml"
+test -f "$HOME_DIR/Library/LaunchAgents/com.beacon.endpoint.collector.user.plist"
+test -f "$LOG_PATH"
+
+echo "Checking endpoint status..."
+run_beacon endpoint status --user --log-path "$LOG_PATH" >/dev/null
+
+echo "Writing Wazuh validation event..."
+run_beacon endpoint wazuh validate --user --log-path "$LOG_PATH" >/dev/null
+
+if ! grep -q '"action":"telemetry.enabled"' "$LOG_PATH"; then
+ echo "expected telemetry.enabled event in runtime log" >&2
+ exit 1
+fi
+
+if ! grep -q '"category":"validation"' "$LOG_PATH"; then
+ echo "expected validation event in runtime log" >&2
+ exit 1
+fi
+
+echo "Installing Cursor hooks in temporary HOME..."
+run_beacon endpoint hooks install --harness cursor --user --log-path "$LOG_PATH" >/dev/null
+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
+ exit 1
+fi
+
+echo "Uninstalling endpoint config..."
+run_beacon endpoint uninstall --user --log-path "$LOG_PATH" --keep-logs >/dev/null
+
+if [ -f "$HOME_DIR/.beacon/endpoint/config.json" ]; then
+ echo "endpoint config was not removed by uninstall" >&2
+ exit 1
+fi
+
+test -f "$LOG_PATH"
+
+echo "Beacon endpoint smoke test passed."