Skip to content

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

doctor updates

Justin D'Souzaa771de9e7d50
diff --git a/cli/beacon/cmd/endpoint.go b/cli/beacon/cmd/endpoint.go
index 69e61b58..ad4b0f4b 100644
--- a/cli/beacon/cmd/endpoint.go
+++ b/cli/beacon/cmd/endpoint.go
@@ -52,6 +52,7 @@ var endpointOpts struct {
keepConfig bool
noStart bool
dryRun bool
+ fix bool
allTargets bool
coworkHeaders string
coworkEndpoint string
@@ -852,10 +853,12 @@ func init() {
endpointDiscoverCmd.Flags().BoolVar(&endpointOpts.allTargets, "all", false, "Discover all supported runtime targets")
endpointStatusCmd.Flags().BoolVar(&endpointOpts.jsonOutput, "json", false, "Print status as JSON")
endpointDoctorCmd.Flags().BoolVar(&endpointOpts.jsonOutput, "json", false, "Print doctor results as JSON")
+ endpointDoctorCmd.Flags().BoolVar(&endpointOpts.fix, "fix", false, "Apply safe endpoint doctor remediations")
endpointInventoryCmd.Flags().BoolVar(&endpointOpts.jsonOutput, "json", false, "Print inventory as JSON")
endpointInventoryCmd.Flags().BoolVar(&endpointOpts.allTargets, "all", false, "Include all supported targets")
endpointInventoryCmd.Flags().BoolVar(&endpointOpts.writeInventoryEvent, "write-event", false, "Append config inventory events to the endpoint runtime log")
topLevelDoctorCmd.Flags().BoolVar(&endpointOpts.jsonOutput, "json", false, "Print doctor results as JSON")
+ topLevelDoctorCmd.Flags().BoolVar(&endpointOpts.fix, "fix", false, "Apply safe endpoint doctor remediations")
topLevelStatusCmd.Flags().BoolVar(&endpointOpts.jsonOutput, "json", false, "Print status as JSON")
topLevelInventoryCmd.Flags().BoolVar(&endpointOpts.jsonOutput, "json", false, "Print inventory as JSON")
topLevelInventoryCmd.Flags().BoolVar(&endpointOpts.allTargets, "all", false, "Include all supported targets")
diff --git a/cli/beacon/cmd/endpoint_diagnostics.go b/cli/beacon/cmd/endpoint_diagnostics.go
index 660eb983..45c1b064 100644
--- a/cli/beacon/cmd/endpoint_diagnostics.go
+++ b/cli/beacon/cmd/endpoint_diagnostics.go
@@ -11,15 +11,18 @@ import (
"github.com/spf13/cobra"
+ endpointcollector "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/collector"
endpointconfig "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/config"
"github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/diagnostics"
"github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/harness"
endpointhooks "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/hooks"
+ endpointintegrations "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/integrations"
"github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/integrations/cowork"
"github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/integrations/openclaw"
endpointinventory "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/inventory"
"github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/lifecycle"
"github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/schema"
+ "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/service"
"github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/writer"
"github.com/asymptote-labs/agent-beacon/cli/beacon/internal/version"
)
@@ -27,6 +30,8 @@ import (
type doctorResult struct {
Status string `json:"status"`
Checks []diagnostics.Check `json:"checks"`
+ Fixes []plannedAction `json:"fixes,omitempty"`
+ Skipped []plannedAction `json:"skipped,omitempty"`
GeneratedAt string `json:"generated_at"`
}
@@ -71,26 +76,75 @@ type plannedAction struct {
func runEndpointDoctor(cmd *cobra.Command, args []string) error {
status := lifecycle.GetStatus(endpointUserMode(), endpointOpts.logPath)
- checks := append([]diagnostics.Check{}, status.Diagnostics...)
- checks = append(checks,
- collectorCheck(status),
- serviceCheck(status),
- lastEventCheck(status),
- )
+ result := buildDoctorResult(status, time.Now())
+ if endpointOpts.fix {
+ fixPlan := planDoctorFixes(result, status)
+ result.Fixes = fixPlan.Fixes
+ result.Skipped = fixPlan.Skipped
+ if err := applyDoctorFixes(fixPlan, status); err != nil {
+ return err
+ }
+ status = lifecycle.GetStatus(endpointUserMode(), endpointOpts.logPath)
+ result = buildDoctorResult(status, time.Now())
+ result.Fixes = fixPlan.Fixes
+ result.Skipped = fixPlan.Skipped
+ }
+ if err := printDoctorResult(result); err != nil {
+ return err
+ }
+ if result.Status == diagnostics.StatusFail {
+ return fmt.Errorf("endpoint health checks failed")
+ }
+ return nil
+}
+
+func buildDoctorResult(status lifecycle.Status, generatedAt time.Time) doctorResult {
+ checks := []diagnostics.Check{
+ configValidationCheck(status.RuntimeLog.EffectiveUserMode),
+ }
+ checks = append(checks, actionableChecks(status.Diagnostics, status.RuntimeLog)...)
+ checks = append(checks, collectorCheck(status), serviceCheck(status), lastEventCheck(status))
for _, h := range status.Harnesses {
- checks = append(checks, harnessCheck(h))
+ checks = append(checks, harnessCheck(h, status.LogPath))
}
result := doctorResult{
Status: aggregateCheckStatus(checks),
Checks: checks,
- GeneratedAt: time.Now().UTC().Format(time.RFC3339),
+ GeneratedAt: generatedAt.UTC().Format(time.RFC3339),
}
+ return result
+}
+
+func printDoctorResult(result doctorResult) error {
if endpointOpts.jsonOutput {
return json.NewEncoder(os.Stdout).Encode(result)
}
fmt.Printf("Beacon endpoint doctor: %s\n", result.Status)
+ printDoctorChecks(result.Checks, diagnostics.StatusFail)
+ printDoctorChecks(result.Checks, diagnostics.StatusWarn)
+ if len(result.Fixes) > 0 {
+ fmt.Println("Applied fixes:")
+ for _, fix := range result.Fixes {
+ printPlannedAction(fix)
+ }
+ }
+ if len(result.Skipped) > 0 {
+ fmt.Println("Skipped fixes:")
+ for _, skipped := range result.Skipped {
+ printPlannedAction(skipped)
+ }
+ }
+ failures, warnings := checkCounts(result.Checks)
+ fmt.Printf("Summary: %d failure(s), %d warning(s)\n", failures, warnings)
+ if result.Status == diagnostics.StatusOK {
+ fmt.Println("All endpoint health checks passed.")
+ }
+ return nil
+}
+
+func printDoctorChecks(checks []diagnostics.Check, status string) {
for _, check := range checks {
- if check.Status == "ok" {
+ if check.Status != status {
continue
}
fmt.Printf("%s: %s", check.Name, check.Status)
@@ -100,15 +154,11 @@ func runEndpointDoctor(cmd *cobra.Command, args []string) error {
if check.Message != "" {
fmt.Printf(" (%s)", check.Message)
}
+ if check.Action != "" {
+ fmt.Printf(" action=%q", check.Action)
+ }
fmt.Println()
}
- if result.Status == "ok" {
- fmt.Println("All endpoint health checks passed.")
- }
- if result.Status == "fail" {
- return fmt.Errorf("endpoint health checks failed")
- }
- return nil
}
func runEndpointInventory(cmd *cobra.Command, args []string) error {
@@ -459,18 +509,22 @@ func printPlannedActions(actions []plannedAction) error {
return json.NewEncoder(os.Stdout).Encode(actions)
}
for _, action := range actions {
- fmt.Printf("%s", action.Action)
- if action.Target != "" {
- fmt.Printf(" %s", action.Target)
- }
- if action.Message != "" {
- fmt.Printf(" (%s)", action.Message)
- }
- fmt.Println()
+ printPlannedAction(action)
}
return nil
}
+func printPlannedAction(action plannedAction) {
+ fmt.Printf("%s", action.Action)
+ if action.Target != "" {
+ fmt.Printf(" %s", action.Target)
+ }
+ if action.Message != "" {
+ fmt.Printf(" (%s)", action.Message)
+ }
+ fmt.Println()
+}
+
func hookTargets() ([]string, error) {
if endpointOpts.allTargets {
all := []string{"cursor", "vscode", "factory", "opencode", "grok", "hermes", "devin-cli", "devin-desktop", "antigravity"}
@@ -544,51 +598,265 @@ func targetStatus(installed bool) string {
return "not_installed"
}
+func configValidationCheck(userMode bool) diagnostics.Check {
+ path := endpointconfig.ConfigPath(userMode)
+ if _, err := endpointconfig.Load(userMode); err != nil {
+ action := doctorInstallCommand(userMode)
+ if !os.IsNotExist(err) {
+ action = "fix the endpoint config JSON or run " + doctorRepairCommand(userMode)
+ }
+ return diagnostics.Check{
+ Name: "config_valid",
+ Target: path,
+ Status: diagnostics.StatusFail,
+ Severity: diagnostics.SeverityHigh,
+ Message: err.Error(),
+ Evidence: "config_load_failed",
+ Action: action,
+ }
+ }
+ return diagnostics.Check{
+ Name: "config_valid",
+ Target: path,
+ Status: diagnostics.StatusOK,
+ Severity: diagnostics.SeverityInfo,
+ Message: "endpoint config is valid",
+ Evidence: "config_load_succeeded",
+ }
+}
+
+func actionableChecks(checks []diagnostics.Check, runtimeLog lifecycle.RuntimeLogSource) []diagnostics.Check {
+ out := make([]diagnostics.Check, 0, len(checks))
+ for _, check := range checks {
+ if check.Action == "" {
+ check.Action = actionForCheck(check, runtimeLog)
+ }
+ out = append(out, check)
+ }
+ return out
+}
+
+func actionForCheck(check diagnostics.Check, runtimeLog lifecycle.RuntimeLogSource) string {
+ switch check.Name {
+ case "config", "collector_config", "launchd_plist", "collector_health":
+ return doctorRepairCommand(runtimeLog.EffectiveUserMode)
+ case "runtime_log", "runtime_log_permissions":
+ return "beacon endpoint doctor --fix"
+ case "runtime_log_source":
+ if runtimeLog.RequestedUserMode && !runtimeLog.EffectiveUserMode {
+ return "stop the system collector or run beacon endpoint install --user"
+ }
+ return "review the requested and effective runtime log paths"
+ }
+ return ""
+}
+
func aggregateCheckStatus(checks []diagnostics.Check) string {
- out := "ok"
+ out := diagnostics.StatusOK
for _, check := range checks {
- if check.Status == "fail" {
- return "fail"
+ if check.Status == diagnostics.StatusFail {
+ return diagnostics.StatusFail
}
- if check.Status == "warn" {
- out = "warn"
+ if check.Status == diagnostics.StatusWarn {
+ out = diagnostics.StatusWarn
}
}
return out
}
func collectorCheck(status lifecycle.Status) diagnostics.Check {
+ if status.Collector.BinaryPath == "" {
+ return diagnostics.Check{Name: "collector_reachability", Target: status.ConfigPath, Status: diagnostics.StatusFail, Severity: diagnostics.SeverityHigh, Message: status.Collector.Message, Evidence: "collector_binary_missing", Action: doctorRepairCommand(status.RuntimeLog.EffectiveUserMode)}
+ }
+ if status.Collector.GRPCReady && status.Collector.HTTPReady {
+ return diagnostics.Check{Name: "collector_reachability", Target: status.ConfigPath, Status: diagnostics.StatusOK, Severity: diagnostics.SeverityInfo, Message: status.Collector.Message, Evidence: "collector_ready"}
+ }
if status.Collector.GRPCReady || status.Collector.HTTPReady {
- return diagnostics.Check{Name: "collector_reachability", Target: status.ConfigPath, Status: "ok", Severity: "info", Message: status.Collector.Message, Evidence: "collector_ready"}
+ return diagnostics.Check{Name: "collector_reachability", Target: status.ConfigPath, Status: diagnostics.StatusWarn, Severity: diagnostics.SeverityMedium, Message: "only one OTLP receiver is listening", Evidence: "collector_partially_ready", Action: doctorRepairCommand(status.RuntimeLog.EffectiveUserMode)}
}
- return diagnostics.Check{Name: "collector_reachability", Target: status.ConfigPath, Status: "fail", Severity: "high", Message: status.Collector.Message, Evidence: "collector_not_ready"}
+ return diagnostics.Check{Name: "collector_reachability", Target: status.ConfigPath, Status: diagnostics.StatusFail, Severity: diagnostics.SeverityHigh, Message: status.Collector.Message, Evidence: "collector_not_ready", Action: doctorRepairCommand(status.RuntimeLog.EffectiveUserMode)}
}
func serviceCheck(status lifecycle.Status) diagnostics.Check {
if status.Service.Running {
- return diagnostics.Check{Name: "service", Status: "ok", Severity: "info", Message: status.Service.Message, Evidence: "service_running"}
+ return diagnostics.Check{Name: "service", Status: diagnostics.StatusOK, Severity: diagnostics.SeverityInfo, Message: status.Service.Message, Evidence: "service_running"}
}
if status.Service.Loaded {
- return diagnostics.Check{Name: "service", Status: "warn", Severity: "medium", Message: status.Service.Message, Evidence: "service_loaded_not_running"}
+ return diagnostics.Check{Name: "service", Status: diagnostics.StatusWarn, Severity: diagnostics.SeverityMedium, Message: status.Service.Message, Evidence: "service_loaded_not_running", Action: doctorRepairCommand(status.RuntimeLog.EffectiveUserMode)}
}
- return diagnostics.Check{Name: "service", Status: "warn", Severity: "medium", Message: status.Service.Message, Evidence: "service_not_loaded"}
+ return diagnostics.Check{Name: "service", Status: diagnostics.StatusWarn, Severity: diagnostics.SeverityMedium, Message: status.Service.Message, Evidence: "service_not_loaded", Action: doctorRepairCommand(status.RuntimeLog.EffectiveUserMode)}
}
func lastEventCheck(status lifecycle.Status) diagnostics.Check {
if status.LastEvent != "" {
- return diagnostics.Check{Name: "last_event", Target: status.LogPath, Status: "ok", Severity: "info", Message: "runtime log has events", Evidence: "last_event_present"}
+ return diagnostics.Check{Name: "last_event", Target: status.LogPath, Status: diagnostics.StatusOK, Severity: diagnostics.SeverityInfo, Message: "runtime log has events", Evidence: "last_event_present"}
}
- return diagnostics.Check{Name: "last_event", Target: status.LogPath, Status: "warn", Severity: "low", Message: "runtime log has no events yet", Evidence: "last_event_missing"}
+ return diagnostics.Check{Name: "last_event", Target: status.LogPath, Status: diagnostics.StatusWarn, Severity: diagnostics.SeverityLow, Message: "runtime log has no events yet", Evidence: "last_event_missing", Action: "beacon endpoint test-event"}
}
-func harnessCheck(h harness.Harness) diagnostics.Check {
+func harnessCheck(h harness.Harness, logPath string) diagnostics.Check {
if !h.Detected {
- return diagnostics.Check{Name: "harness", Target: h.Name, Status: "ok", Severity: "info", Message: "not installed", Evidence: "not_installed"}
+ return diagnostics.Check{Name: "harness", Target: h.Name, Status: diagnostics.StatusOK, Severity: diagnostics.SeverityInfo, Message: "not installed", Evidence: "not_installed"}
}
if h.TelemetryStatus == harness.TelemetryEnabled {
- return diagnostics.Check{Name: "harness", Target: h.Name, Status: "ok", Severity: "info", Message: h.Message, Evidence: "configured"}
+ if !harnessEventObserved(logPath, h.Name) {
+ return diagnostics.Check{Name: "harness_observed", Target: h.Name, Status: diagnostics.StatusWarn, Severity: diagnostics.SeverityLow, Message: "telemetry is configured but no matching event has been observed yet", Evidence: "configured_not_observed", Action: "run " + h.DisplayName + " or beacon endpoint test-event"}
+ }
+ return diagnostics.Check{Name: "harness", Target: h.Name, Status: diagnostics.StatusOK, Severity: diagnostics.SeverityInfo, Message: h.Message, Evidence: "configured"}
+ }
+ return diagnostics.Check{Name: "harness", Target: h.Name, Status: diagnostics.StatusWarn, Severity: diagnostics.SeverityMedium, Message: h.Message, Evidence: string(h.TelemetryStatus), Action: harnessAction(h)}
+}
+
+func harnessEventObserved(logPath, name string) bool {
+ return endpointintegrations.HasRecentHarnessEvent(logPath, name)
+}
+
+func harnessAction(h harness.Harness) string {
+ switch h.Capability {
+ case "hooks", "plugin":
+ return "beacon endpoint hooks install --harness " + h.Name
+ case "otel_env", "otel_config":
+ return doctorRepairCommand(endpointUserMode())
+ case "admin_otel":
+ return "beacon endpoint integrations claude-cowork setup"
+ }
+ return ""
+}
+
+func checkCounts(checks []diagnostics.Check) (int, int) {
+ failures := 0
+ warnings := 0
+ for _, check := range checks {
+ switch check.Status {
+ case diagnostics.StatusFail:
+ failures++
+ case diagnostics.StatusWarn:
+ warnings++
+ }
+ }
+ return failures, warnings
+}
+
+func doctorRepairCommand(userMode bool) string {
+ if userMode {
+ return "beacon endpoint repair --user"
+ }
+ return "sudo beacon endpoint repair --system"
+}
+
+func doctorInstallCommand(userMode bool) string {
+ if userMode {
+ return "beacon endpoint install --user"
+ }
+ return "sudo beacon endpoint install --system"
+}
+
+type doctorFixPlan struct {
+ Fixes []plannedAction
+ Skipped []plannedAction
+}
+
+func planDoctorFixes(result doctorResult, status lifecycle.Status) doctorFixPlan {
+ plan := doctorFixPlan{}
+ addFix := func(action plannedAction) {
+ for _, existing := range plan.Fixes {
+ if existing.Action == action.Action && existing.Target == action.Target {
+ return
+ }
+ }
+ plan.Fixes = append(plan.Fixes, action)
+ }
+ addSkip := func(action plannedAction) {
+ for _, existing := range plan.Skipped {
+ if existing.Action == action.Action && existing.Target == action.Target {
+ return
+ }
+ }
+ plan.Skipped = append(plan.Skipped, action)
+ }
+
+ configUsable := true
+ for _, check := range result.Checks {
+ if check.Name == "config_valid" && check.Status == diagnostics.StatusFail {
+ configUsable = false
+ addSkip(plannedAction{Action: "manual_fix", Target: check.Target, Message: "endpoint config could not be repaired safely: " + check.Message})
+ }
+ }
+
+ for _, check := range result.Checks {
+ if check.Status == diagnostics.StatusOK {
+ continue
+ }
+ switch check.Name {
+ case "runtime_log", "runtime_log_permissions", "last_event":
+ if check.Evidence == "missing_optional_file" || check.Evidence == "runtime_log_missing" {
+ addFix(plannedAction{Action: "create_runtime_log", Target: status.LogPath, Message: "create runtime log file and parent directory"})
+ } else if check.Evidence == "last_event_missing" {
+ addSkip(plannedAction{Action: "manual_fix", Target: check.Target, Message: "run beacon endpoint test-event or generate a runtime event"})
+ }
+ case "collector_config", "launchd_plist", "collector_health", "collector_reachability", "service":
+ if configUsable {
+ addFix(plannedAction{Action: "repair_collector_service", Target: endpointconfig.ConfigPath(status.RuntimeLog.EffectiveUserMode), Message: "recreate managed collector config and launchd service"})
+ } else {
+ addSkip(plannedAction{Action: "repair_collector_service", Target: endpointconfig.ConfigPath(status.RuntimeLog.EffectiveUserMode), Message: "skipped because endpoint config is invalid"})
+ }
+ case "config", "config_valid":
+ if check.Status == diagnostics.StatusFail {
+ addSkip(plannedAction{Action: "manual_fix", Target: check.Target, Message: "review endpoint config or run " + doctorInstallCommand(status.RuntimeLog.EffectiveUserMode)})
+ }
+ case "harness":
+ message := "review harness configuration manually"
+ if check.Action != "" {
+ message = "run " + check.Action
+ }
+ addSkip(plannedAction{Action: "manual_fix", Target: check.Target, Message: message})
+ case "runtime_log_source":
+ addSkip(plannedAction{Action: "manual_fix", Target: check.Target, Message: check.Action})
+ }
+ }
+ return plan
+}
+
+func applyDoctorFixes(plan doctorFixPlan, status lifecycle.Status) error {
+ for _, action := range plan.Fixes {
+ switch action.Action {
+ case "create_runtime_log":
+ if err := ensureLogFile(action.Target); err != nil {
+ return err
+ }
+ case "repair_collector_service":
+ if err := repairCollectorServiceFromStatus(status); err != nil {
+ return err
+ }
+ }
+ }
+ return nil
+}
+
+func repairCollectorServiceFromStatus(status lifecycle.Status) error {
+ userMode := status.RuntimeLog.EffectiveUserMode
+ cfg, err := endpointconfig.Load(userMode)
+ if err != nil {
+ return err
+ }
+ if endpointOpts.logPath != "" {
+ cfg.LogPath = endpointOpts.logPath
+ }
+ binary, err := endpointcollector.ResolveBinary(cfg.Collector.BinaryPath)
+ if err != nil {
+ return err
+ }
+ if err := endpointcollector.WriteConfig(cfg); err != nil {
+ return err
+ }
+ manager := service.Manager{UserMode: userMode}
+ if _, err := manager.WritePlist(binary, cfg.Collector.ConfigPath); err != nil {
+ return err
+ }
+ if err := manager.Load(); err != nil {
+ return err
}
- return diagnostics.Check{Name: "harness", Target: h.Name, Status: "warn", Severity: "medium", Message: h.Message, Evidence: string(h.TelemetryStatus)}
+ return endpointcollector.WaitUntilReady(cfg, 10*time.Second)
}
func checkLogWritable(cfg endpointconfig.Config) diagnostics.Check {
diff --git a/cli/beacon/cmd/endpoint_test.go b/cli/beacon/cmd/endpoint_test.go
index e9048de1..bdc3d852 100644
--- a/cli/beacon/cmd/endpoint_test.go
+++ b/cli/beacon/cmd/endpoint_test.go
@@ -12,6 +12,7 @@ import (
endpointconfig "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/config"
"github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/diagnostics"
endpointinventory "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/inventory"
+ "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/lifecycle"
"github.com/spf13/cobra"
)
@@ -643,6 +644,14 @@ func TestRobustCLIFlagsRegistered(t *testing.T) {
if endpointBundleDiagnosticsCmd.Flags().Lookup("include-raw-events") == nil {
t.Fatal("bundle-diagnostics missing --include-raw-events")
}
+ for _, cmd := range []*cobra.Command{endpointDoctorCmd, topLevelDoctorCmd} {
+ if cmd.Flags().Lookup("fix") == nil {
+ t.Fatalf("%s missing --fix", cmd.Use)
+ }
+ if cmd.Flags().Lookup("dry-run") != nil {
+ t.Fatalf("%s should not register --dry-run", cmd.Use)
+ }
+ }
}
func TestCompletionAndDocsCommandsRegistered(t *testing.T) {
@@ -702,6 +711,117 @@ func TestAggregateCheckStatus(t *testing.T) {
}
}
+func TestConfigValidationCheckReportsInvalidConfig(t *testing.T) {
+ home := t.TempDir()
+ t.Setenv("HOME", home)
+ path := endpointconfig.ConfigPath(true)
+ if err := os.MkdirAll(filepath.Dir(path), 0755); err != nil {
+ t.Fatalf("mkdir config dir: %v", err)
+ }
+ if err := os.WriteFile(path, []byte("{not-json"), 0644); err != nil {
+ t.Fatalf("write config: %v", err)
+ }
+
+ check := configValidationCheck(true)
+ if check.Status != diagnostics.StatusFail {
+ t.Fatalf("config validation status = %#v, want fail", check)
+ }
+ if !strings.Contains(check.Action, "fix the endpoint config JSON") {
+ t.Fatalf("config validation action = %q", check.Action)
+ }
+}
+
+func TestActionableChecksUsesRequestedRuntimeLogMode(t *testing.T) {
+ checks := actionableChecks([]diagnostics.Check{{
+ Name: "runtime_log_source",
+ Status: diagnostics.StatusWarn,
+ }}, lifecycle.RuntimeLogSource{
+ RequestedUserMode: true,
+ EffectiveUserMode: false,
+ })
+ if len(checks) != 1 {
+ t.Fatalf("actionableChecks returned %d checks", len(checks))
+ }
+ if !strings.Contains(checks[0].Action, "stop the system collector") {
+ t.Fatalf("runtime log source action = %q", checks[0].Action)
+ }
+}
+
+func TestPrintDoctorResultIncludesActionsAndSummary(t *testing.T) {
+ old := endpointOpts
+ t.Cleanup(func() { endpointOpts = old })
+ endpointOpts.jsonOutput = false
+ result := doctorResult{
+ Status: diagnostics.StatusWarn,
+ Checks: []diagnostics.Check{
+ {Name: "ok_check", Status: diagnostics.StatusOK, Severity: diagnostics.SeverityInfo},
+ {Name: "warn_check", Status: diagnostics.StatusWarn, Severity: diagnostics.SeverityLow, Message: "needs attention", Action: "beacon endpoint test-event"},
+ },
+ GeneratedAt: "2026-06-05T12:00:00Z",
+ }
+
+ output, err := captureStdout(t, func() error { return printDoctorResult(result) })
+ if err != nil {
+ t.Fatalf("printDoctorResult returned error: %v", err)
+ }
+ if !strings.Contains(output, `action="beacon endpoint test-event"`) {
+ t.Fatalf("doctor output missing action: %s", output)
+ }
+ if !strings.Contains(output, "Summary: 0 failure(s), 1 warning(s)") {
+ t.Fatalf("doctor output missing summary: %s", output)
+ }
+}
+
+func TestPlanDoctorFixesAllowsRuntimeLogCreationAndSkipsInvalidConfig(t *testing.T) {
+ logPath := filepath.Join(t.TempDir(), "runtime.jsonl")
+ status := lifecycle.Status{
+ LogPath: logPath,
+ RuntimeLog: lifecycle.RuntimeLogSource{EffectiveUserMode: true},
+ }
+ result := doctorResult{
+ Checks: []diagnostics.Check{
+ {Name: "config_valid", Target: "/tmp/config.json", Status: diagnostics.StatusFail, Message: "invalid json"},
+ {Name: "runtime_log_permissions", Target: logPath, Status: diagnostics.StatusWarn, Evidence: "runtime_log_missing"},
+ {Name: "collector_reachability", Status: diagnostics.StatusFail},
+ },
+ }
+
+ plan := planDoctorFixes(result, status)
+ if len(plan.Fixes) != 1 || plan.Fixes[0].Action != "create_runtime_log" {
+ t.Fatalf("fix plan = %#v, want runtime log creation only", plan)
+ }
+ foundSkip := false
+ for _, skipped := range plan.Skipped {
+ if skipped.Action == "repair_collector_service" {
+ foundSkip = true
+ }
+ }
+ if !foundSkip {
+ t.Fatalf("fix plan did not skip endpoint repair for invalid config: %#v", plan)
+ }
+}
+
+func TestPlanDoctorFixesDoesNotTreatMissingEventAsAppliedFix(t *testing.T) {
+ logPath := filepath.Join(t.TempDir(), "runtime.jsonl")
+ status := lifecycle.Status{
+ LogPath: logPath,
+ RuntimeLog: lifecycle.RuntimeLogSource{EffectiveUserMode: true},
+ }
+ result := doctorResult{
+ Checks: []diagnostics.Check{
+ {Name: "last_event", Target: logPath, Status: diagnostics.StatusWarn, Evidence: "last_event_missing"},
+ },
+ }
+
+ plan := planDoctorFixes(result, status)
+ if len(plan.Fixes) != 0 {
+ t.Fatalf("missing last event should not be applied as a fix: %#v", plan)
+ }
+ if len(plan.Skipped) != 1 || !strings.Contains(plan.Skipped[0].Message, "test-event") {
+ t.Fatalf("missing last event should suggest test-event: %#v", plan)
+ }
+}
+
func TestEndpointIntegrationsValidateAllReturnsErrorForBrokenText(t *testing.T) {
oldAllTargets := endpointOpts.allTargets
oldJSONOutput := endpointOpts.jsonOutput
diff --git a/cli/beacon/internal/endpoint/diagnostics/diagnostics.go b/cli/beacon/internal/endpoint/diagnostics/diagnostics.go
index 6b850c8b..0d2a585e 100644
--- a/cli/beacon/internal/endpoint/diagnostics/diagnostics.go
+++ b/cli/beacon/internal/endpoint/diagnostics/diagnostics.go
@@ -18,8 +18,20 @@ type Check struct {
Severity string `json:"severity"`
Message string `json:"message,omitempty"`
Evidence string `json:"evidence,omitempty"`
+ Action string `json:"action,omitempty"`
}
+const (
+ StatusOK = "ok"
+ StatusWarn = "warn"
+ StatusFail = "fail"
+
+ SeverityInfo = "info"
+ SeverityLow = "low"
+ SeverityMedium = "medium"
+ SeverityHigh = "high"
+)
+
func Run(cfg endpointconfig.Config) []Check {
checks := []Check{
checkFile("config", endpointconfig.ConfigPath(cfg.UserMode), true),
@@ -37,18 +49,18 @@ func Run(cfg endpointconfig.Config) []Check {
func checkCollectorHealth(cfg endpointconfig.Config) Check {
status := collector.CheckStatus(cfg)
if status.HealthReady {
- return Check{Name: "collector_health", Target: fmt.Sprintf("127.0.0.1:%d", collector.HealthCheckPort), Status: "ok", Severity: "info", Message: "collector health check is ready", Evidence: "health_check_ready"}
+ return Check{Name: "collector_health", Target: fmt.Sprintf("127.0.0.1:%d", collector.HealthCheckPort), Status: StatusOK, Severity: SeverityInfo, Message: "collector health check is ready", Evidence: "health_check_ready"}
}
message := status.Message
if message == "" {
message = "collector health check is not ready"
}
- return Check{Name: "collector_health", Target: fmt.Sprintf("127.0.0.1:%d", collector.HealthCheckPort), Status: "warn", Severity: "medium", Message: message, Evidence: "health_check_unavailable"}
+ return Check{Name: "collector_health", Target: fmt.Sprintf("127.0.0.1:%d", collector.HealthCheckPort), Status: StatusWarn, Severity: SeverityMedium, Message: message, Evidence: "health_check_unavailable"}
}
func HasFailures(checks []Check) bool {
for _, check := range checks {
- if check.Status == "fail" {
+ if check.Status == StatusFail {
return true
}
}
@@ -59,29 +71,29 @@ func checkFile(name, path string, required bool) Check {
info, err := os.Stat(path)
if err != nil {
if os.IsNotExist(err) && !required {
- return Check{Name: name, Target: path, Status: "warn", Severity: "low", Message: fmt.Sprintf("%s does not exist yet", path), Evidence: "missing_optional_file"}
+ return Check{Name: name, Target: path, Status: StatusWarn, Severity: SeverityLow, Message: fmt.Sprintf("%s does not exist yet", path), Evidence: "missing_optional_file"}
}
- return Check{Name: name, Target: path, Status: "fail", Severity: "medium", Message: err.Error(), Evidence: "stat_failed"}
+ return Check{Name: name, Target: path, Status: StatusFail, Severity: SeverityMedium, Message: err.Error(), Evidence: "stat_failed"}
}
if info.IsDir() {
- return Check{Name: name, Target: path, Status: "fail", Severity: "medium", Message: path + " is a directory", Evidence: "target_is_directory"}
+ return Check{Name: name, Target: path, Status: StatusFail, Severity: SeverityMedium, Message: path + " is a directory", Evidence: "target_is_directory"}
}
- return Check{Name: name, Target: path, Status: "ok", Severity: "info", Message: path, Evidence: "file_exists"}
+ return Check{Name: name, Target: path, Status: StatusOK, Severity: SeverityInfo, Message: path, Evidence: "file_exists"}
}
func checkLogPermissions(path string) Check {
info, err := os.Stat(path)
if err != nil {
- return Check{Name: "runtime_log_permissions", Target: path, Status: "warn", Severity: "low", Message: "runtime log not created yet", Evidence: "runtime_log_missing"}
+ return Check{Name: "runtime_log_permissions", Target: path, Status: StatusWarn, Severity: SeverityLow, Message: "runtime log not created yet", Evidence: "runtime_log_missing"}
}
mode := info.Mode().Perm()
if mode&0022 != 0 {
- return Check{Name: "runtime_log_permissions", Target: path, Status: "fail", Severity: "high", Message: fmt.Sprintf("runtime log is group/world writable: %o", mode), Evidence: "group_or_world_writable"}
+ return Check{Name: "runtime_log_permissions", Target: path, Status: StatusFail, Severity: SeverityHigh, Message: fmt.Sprintf("runtime log is group/world writable: %o", mode), Evidence: "group_or_world_writable"}
}
if mode&0044 == 0 {
- return Check{Name: "runtime_log_permissions", Target: path, Status: "warn", Severity: "low", Message: fmt.Sprintf("runtime log may not be readable by Wazuh: %o", mode), Evidence: "not_group_or_world_readable"}
+ return Check{Name: "runtime_log_permissions", Target: path, Status: StatusWarn, Severity: SeverityLow, Message: fmt.Sprintf("runtime log may not be readable by Wazuh: %o", mode), Evidence: "not_group_or_world_readable"}
}
- return Check{Name: "runtime_log_permissions", Target: path, Status: "ok", Severity: "info", Message: fmt.Sprintf("mode %o", mode), Evidence: fmt.Sprintf("mode_%o", mode)}
+ return Check{Name: "runtime_log_permissions", Target: path, Status: StatusOK, Severity: SeverityInfo, Message: fmt.Sprintf("mode %o", mode), Evidence: fmt.Sprintf("mode_%o", mode)}
}
func launchPlistPath(userMode bool) string {