feat(agent): probe phase + startup capability table

Adds a lightweight version of the ProbeableGear mechanism from #60 §1.
Each gear self-reports whether its prerequisites are present; gears that
probe non-Available are skipped entirely (no Initialize, no Start, no
routes, no collectors/streamers). After the probe phase the manager
writes a summary table to stderr — readable in the systemd journal —
so operators can see at startup which gears are running on this host
and which aren't:

  Gear probe summary:

    GEAR          STATUS    REASON
    certificates  enabled
    haproxy       enabled
    logs          enabled
    metrics       enabled
    security      disabled  neither fail2ban-client nor nft found on PATH
    traffic       enabled
    updates       enabled

Framework changes (internal/framework/gear/):
- Add ProbeStatus enum: available, not_installed, inaccessible, disabled
- Add ProbeResult struct + helper constructors (ProbeAvailable, etc.)
- Add ProbeableGear sub-interface; gears that don't implement it default
  to Available, so the migration is incremental
- Add Manager.ProbeAll, ProbeResults, isLoaded; Initialize/Start/
  RegisterRoutes/startCollectors/startStreamers/setupEventHandlers all
  skip non-Available gears silently (the table already explained why)
- Inject tableWriter so tests can capture the rendered output

Per-gear probes:
- certificates: certbot or acme.sh on PATH/common paths (side-effect-free
  variant of the existing detectCertbot)
- haproxy: stats URL, stats socket existence, or haproxy binary present
  (with distinct inaccessible reason when the socket path is set but
  missing — operator's fix differs from "install HAProxy")
- logs: journalctl or tail on PATH
- metrics: /proc/stat readable (containerized agents without /proc bind-
  mounted land here as inaccessible)
- security: fail2ban-client or nft on PATH
- traffic: same surface as haproxy (stick tables go over the same socket)
- updates: any of apt-get/apt/dnf/yum/zypper/apk on PATH

Tests cover lifecycle skip behavior, default-Available for non-probeable
gears, the snapshot copy semantics of ProbeResults, and table formatting
(headers, alignment, reasons surfaced only for disabled rows). 9 tests
pass under -race.

Refs #60

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: sarg3nt

gearbox-agent/cmd/gearbox-agent/main.go

@@ -388,8 +388,15 @@ func main() {
 	// Create plugin manager
 	gearManager := gear.NewManager(gearDeps, logger)
 
-	// Initialize all plugins
+	// Probe the host: each gear self-reports whether its prerequisites are
+	// present. Gears that probe negative are skipped for the rest of the
+	// lifecycle (no Initialize, no Start, no routes). A summary table is
+	// written to stderr (→ systemd journal) so operators can see at a
+	// glance which gears are running on this box and why others aren't.
 	ctx := context.Background()
+	gearManager.ProbeAll(ctx)
+
+	// Initialize the gears that probed Available.
 	if err := gearManager.InitializeAll(ctx); err != nil {
 		logger.Error("Failed to initialize plugins", "error", err)
 		os.Exit(1)

gearbox-agent/internal/framework/gear/interface.go

@@ -204,3 +204,94 @@ func NewUnhealthyStatus(message string) HealthStatus {
 		LastCheck: time.Now(),
 	}
 }
+
+// ProbeStatus is the agent's verdict on whether a gear can run on this host.
+// Operators reading the startup table and the upcoming
+// /api/v1/system/capabilities endpoint distinguish the four states because
+// the appropriate fix differs — "install the thing", "fix the access", or
+// "change the config" — and conflating them costs debugging time.
+type ProbeStatus string
+
+const (
+	// ProbeStatusAvailable means the gear's prerequisites are present and
+	// reachable. The gear will go through Initialize/Start normally.
+	ProbeStatusAvailable ProbeStatus = "available"
+
+	// ProbeStatusNotInstalled means the thing the gear manages isn't on
+	// this host at all. Expected on hosts that don't run this software.
+	ProbeStatusNotInstalled ProbeStatus = "not_installed"
+
+	// ProbeStatusInaccessible means the prerequisites exist but the agent
+	// can't reach them — bind mount missing, permission denied, socket
+	// unreadable. The fix is access, not installation.
+	ProbeStatusInaccessible ProbeStatus = "inaccessible"
+
+	// ProbeStatusDisabled means the gear was turned off by configuration.
+	// Reserved for a future GEARBOX_AGENT_DISABLE_GEARS-style mechanism;
+	// no gear returns this yet.
+	ProbeStatusDisabled ProbeStatus = "disabled"
+)
+
+// ProbeResult is what a ProbeableGear returns from Probe(). Status drives
+// the manager's load decision; Reason is a human-readable sentence shown
+// in the startup table and the capabilities API.
+type ProbeResult struct {
+	// Status is the verdict. Only Available causes the gear to load.
+	Status ProbeStatus
+
+	// Reason is a free-text sentence written for an operator: name the
+	// surface that was probed and what was wrong. Mandatory unless the
+	// status is Available (in which case it may describe what was found).
+	Reason string
+
+	// Capabilities is optional detected facts the gear wants to surface
+	// (e.g. "haproxy_version": "2.8.5", "stats_socket": "/run/haproxy/admin.sock").
+	// Populated mainly when Status == Available.
+	Capabilities map[string]string
+}
+
+// IsAvailable reports whether the gear should be loaded.
+func (r ProbeResult) IsAvailable() bool {
+	return r.Status == ProbeStatusAvailable
+}
+
+// ProbeAvailable returns an available ProbeResult with an optional reason
+// (typically the detected version or path) and capabilities map.
+func ProbeAvailable(reason string, capabilities map[string]string) ProbeResult {
+	return ProbeResult{Status: ProbeStatusAvailable, Reason: reason, Capabilities: capabilities}
+}
+
+// ProbeNotInstalled returns a result for the case where the software the
+// gear manages isn't on this host.
+func ProbeNotInstalled(reason string) ProbeResult {
+	return ProbeResult{Status: ProbeStatusNotInstalled, Reason: reason}
+}
+
+// ProbeInaccessible returns a result for the case where prereqs exist but
+// the agent can't reach them. Use when the fix is access, not installation.
+func ProbeInaccessible(reason string) ProbeResult {
+	return ProbeResult{Status: ProbeStatusInaccessible, Reason: reason}
+}
+
+// ProbeDisabled returns a result for gears that have been turned off by
+// configuration.
+func ProbeDisabled(reason string) ProbeResult {
+	return ProbeResult{Status: ProbeStatusDisabled, Reason: reason}
+}
+
+// ProbeableGear is implemented by gears that can self-report whether they
+// have what they need to run on the current host. Gears that do not
+// implement this interface are treated as always-available.
+//
+// Probe runs before Initialize. A non-Available result causes the manager
+// to skip Initialize, Start, and route registration for that gear — it
+// does not exist for this run.
+type ProbeableGear interface {
+	Gear
+
+	// Probe inspects the host for the gear's prerequisites and returns the
+	// verdict. It must be side-effect-free: do not connect to anything,
+	// do not mutate state, do not log loudly. The manager logs a single
+	// summary line per probe.
+	Probe(ctx context.Context, deps Dependencies) ProbeResult
+}