Skip to content

DX: grove doctor command + improved operator diagnostics #215

@windoliver

Description

@windoliver

Summary

Operators and agents frequently hit silent configuration issues. A grove doctor command would surface problems before they cause confusion.

Motivation

From the DX audit:

  • Goal/session MCP tools fail silently when goalSessionStore isn't wired (DX: fix goalSessionStore not wired in stdio MCP, normalize error formats #214)
  • Nexus connectivity issues only surface at grove up time
  • Agent identity env vars (GROVE_AGENT_ID, etc.) are invisible until something fails
  • MCP tool availability depends on preset/mode, but there's no way to check what's enabled
  • The nexus-lifecycle.ts file currently has unresolved git conflict markers on main

Proposed: grove doctor

$ grove doctor

Grove Environment
  .grove directory:     /Users/alice/project/.grove ✓
  grove.db:             exists (1.2 MB) ✓
  CAS:                  .grove/cas/ (47 artifacts) ✓
  GROVE.md:             valid v3 contract ✓
  grove.json:           preset=review-loop, backend=nexus ✓

Agent Identity
  GROVE_AGENT_ID:       claude-worker-1 ✓
  GROVE_AGENT_ROLE:     researcher ✓
  GROVE_AGENT_PLATFORM: claude-code ✓

Services
  HTTP server:          http://localhost:4515 ✓ (responding)
  MCP server:           not configured (preset has services.mcp: false)
  Nexus:                http://localhost:2026 ✓ (healthy)
  API key:              sk-****7f3a (from nexus.yaml) ✓

MCP Tools (for current mode)
  Contributions:        grove_submit_work, grove_submit_review, ... (6 tools) ✓
  Claims:               grove_claim, grove_release, grove_list_claims ✓
  Queries:              grove_frontier, grove_search, ... (6 tools) ✓
  Goals:                ✗ goalSessionStore not configured
  Bounties:             enabled (evaluation mode) ✓

Gossip
  Peers:                not configured (no GOSSIP_SEEDS)

Issues Found:
  ⚠ Goal/session tools will return NOT_CONFIGURED — see #214
  ⚠ GROVE_AGENT_NAME not set (optional but recommended)

Implementation

  • New standalone CLI command in src/cli/commands/doctor.ts
  • Checks: file existence, contract parse, Nexus health, env vars, port connectivity
  • --json output for scripting
  • Could also serve as the basis for a health panel in the TUI

Additional diagnostics improvements

  • grove status --json already exists but could include doctor-level checks
  • MCP tools could include a grove_doctor tool so agents can self-diagnose
  • TUI status bar could surface top-priority doctor warning

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions