Axon Testing Guide — Post-Integration Verification

Context

This document covers changes made in the claude/research-axon-claude-integration-gQIbC branch. Three roadmap features (P1-P3) were implemented along with cross-platform (Linux) support. All changes were tested on Linux (Ubuntu 24.04, Intel Xeon, 16GB). macOS code paths compile but have not been executed yet. This guide is for verifying on a real Mac.

What Changed (10 files, +883 / -107 lines)

Step 1: Build and Basic Smoke Test

cd /path/to/axon
git checkout claude/research-axon-claude-integration-gQIbC
git pull origin claude/research-axon-claude-integration-gQIbC

cargo build
cargo test --workspace

Expected: All tests pass. On macOS, the previously-failing test_uninstall_purges_data_dirs should now pass (it was failing on Linux before the fix, but was already fine on macOS with the old code; the new code uses platform-aware paths).

Step 2: Verify System Profile (macOS Path)

cargo run -- query system_profile

Expected output (on your MacBook Air M2, 8GB):

{
  "ok": true,
  "data": {
    "model_id": "Mac14,15",
    "chip": "Apple Silicon (...)",
    "core_count": 8,
    "ram_total_gb": 8.0,
    "os_version": "macOS ...",
    "axon_version": "0.2.0"
  }
}

What to check:

• model_id should NOT be empty or "Unknown" — it comes from sysctl -n hw.model
• chip should contain "Apple Silicon" — from sysctl -n hw.perflevel0.name fallback
• core_count should be 8
• ram_total_gb should be ~8.0

If model_id or chip is wrong: The detect_platform_info() function at crates/axon-core/src/collector.rs:557 is the macOS path. Debug with:

sysctl -n hw.model
sysctl -n machdep.cpu.brand_string
sysctl -n hw.perflevel0.name

Step 3: Verify Headroom Field (P1)

cargo run -- query hw_snapshot

Expected: JSON response now includes two new fields:

{
  "headroom": "adequate",
  "headroom_reason": "System has headroom"
}

Headroom rules (priority order):

To force different headroom levels, generate load:

# Eat memory to push RAM into warn/critical
python3 -c "x = bytearray(4 * 1024**3); input('holding 4GB...')"

# In another terminal:
cargo run -- query hw_snapshot | grep headroom

On an 8GB MacBook Air M2, allocating 4GB should push RAM to ~75%+ (critical).

Narrative check: The narrative field should end with one of:

• Headroom: adequate.
• Headroom: limited.
• Headroom: INSUFFICIENT -- defer heavy tasks.

Step 4: Verify Agent Accumulation Detection (P2)

# Open 2+ terminal windows, each running:
cargo run -- serve
# (they will block on stdin)

# In another terminal:
cargo run -- query process_blame

Expected when multiple axon serve (or claude, Cursor) processes are running:

{
  "anomaly_type": "agent_accumulation",
  "culprit_group": {
    "name": "axon",
    "process_count": 2,
    ...
  },
  "impact": "Multiple AI agent instances detected. Combined resource usage is growing.",
  "fix": "2 axon instances are running. Close unused sessions to free ~0.1GB..."
}

Note: axon itself is not in the known agent list (only claude, cursor, windsurf, code, zed). To test accumulation detection properly:

• Open multiple Claude Code sessions (claude CLI in different terminals)
• Or open multiple Cursor windows
• Then run cargo run -- query process_blame

Known agent names (after normalization, case-insensitive): claude, claude code, cursor, windsurf, code, zed.

If no accumulation is detected: The detector is at crates/axon-core/src/impact.rs:101. It checks g.process_count > 1 && is_known_agent(&g.name). Debug with:

cargo run -- query process_blame 2>&1 | python3 -m json.tool
# Check the culprit_group.name — does it match a known agent?

Step 5: Verify Session Health Tool (P3)

# Let axon collect data for a bit first:
cargo run -- serve &
sleep 30
kill %1

# Then query:
cargo run -- query session_health

Expected:

{
  "ok": true,
  "data": {
    "since": "...",
    "snapshot_count": 3,
    "alert_count": 0,
    "worst_impact_level": "healthy",
    "worst_anomaly_type": "none",
    "avg_cpu_pct": 12.5,
    "avg_ram_gb": 5.2,
    "peak_cpu_pct": 25.0,
    "peak_ram_gb": 5.8,
    "peak_temp_celsius": 45.0,
    "throttle_event_count": 0
  }
}

What to check:

• snapshot_count > 0 (needs prior axon serve to populate the DB)
• peak_temp_celsius should be non-null on a real Mac (reads die temperature)
• avg_cpu_pct and avg_ram_gb should be reasonable values

If snapshot_count is 0: The DB may not have data in the last hour. Run axon serve for at least 10 seconds, then try again.

Step 6: Verify Battery Status (macOS Path)

cargo run -- query battery_status

Expected on a MacBook:

{
  "ok": true,
  "data": {
    "percentage": 75.0,
    "is_charging": false,
    "time_to_empty_min": 180,
    "narrative": "Battery at 75% (~3h 0m remaining)."
  }
}

If battery returns ok: false: Check that pmset -g batt works in Terminal.

Step 7: Verify Setup/Uninstall Paths (macOS)

# Check what agents are detected:
cargo run -- setup --list

# Setup Claude Desktop (writes to ~/Library/Application Support/Claude/):
cargo run -- setup claude-desktop

# Verify the config was written:
cat ~/Library/Application\ Support/Claude/claude_desktop_config.json | python3 -m json.tool

# Uninstall and verify cleanup:
cargo run -- uninstall claude-desktop

Expected paths on macOS:

• Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json
• VS Code: ~/Library/Application Support/Code/User/settings.json
• Cursor: ~/.cursor/mcp.json
• Data: ~/Library/Application Support/axon/hardware.db
• Config: ~/.config/axon/alert-dispatch.json

Step 8: MCP Protocol Test (Full E2E)

python3 scripts/mcp_exercise_all_tools.py $(which axon || echo ./target/debug/axon)

This script exercises all MCP tools via stdio. After our changes, there are now 6 tools (was 5). The script may need updating to call session_health — if it only tests the original 5, that is fine. The new tool can be tested manually:

# Manual MCP test for session_health:
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}
{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"session_health","arguments":{}}}' | cargo run -- serve 2>/dev/null

Step 9: Run Full Test Suite

cargo test --workspace
cargo test -p axon --test smoke -- --ignored      # ~5s, needs real binary

Expected: All tests pass. The new tests are:

Headroom tests (in crates/axon-core/src/impact.rs):

• test_headroom_insufficient_ram_critical
• test_headroom_insufficient_disk_critical
• test_headroom_insufficient_throttling
• test_headroom_insufficient_warn_plus_high_cpu
• test_headroom_limited_ram_warn
• test_headroom_limited_high_cpu
• test_headroom_adequate
• test_headroom_cpu_boundary
• test_headroom_ram_warn_cpu_boundary

Agent accumulation tests (in crates/axon-core/src/impact.rs):

• test_agent_accumulation_claude
• test_agent_accumulation_cursor
• test_agent_accumulation_single_is_normal
• test_agent_accumulation_ignores_non_agents
• test_suggest_fix_agent_accumulation
• test_impact_message_agent_accumulation

Setup/uninstall tests (in crates/axon-cli/tests/setup_uninstall.rs):

All 10 tests now use #[cfg(target_os = "macos")] / #[cfg(target_os = "linux")] for platform-aware paths.

Risk Areas

1. macOS cfg blocks not executed in CI — The #[cfg(target_os = "macos")] functions

(detect_platform_info, read_battery_macos) were not changed in logic, only moved into cfg-gated functions. But a typo inside them would only surface on macOS compilation.

1. 8GB MacBook Air — With only 8GB RAM, the thresholds (RAM_PCT_WARN=55%,

RAM_PCT_CRITICAL=75%) will fire more easily. 4.4GB used = warn, 6GB used = critical. This is by design and useful — the headroom field will correctly report "limited" or "insufficient" when your Mac is under memory pressure.

1. Agent accumulation false positives — The is_known_agent() function uses

contains() matching. A process named "encoder" would NOT match "code" because the check is lower == a || lower.contains(a) where a is the full agent name. However, "vscode-server" would match "code". This is intentional — VS Code server processes are legitimate agent processes.

1. Session health with empty DB — If axon serve has never run, session_health

returns snapshot_count: 0 gracefully. Not an error.

Architecture Reference (Post-Changes)

6 MCP Tools (was 5):
  hw_snapshot      → HwSnapshot + headroom + headroom_reason
  process_blame    → ProcessBlame + AgentAccumulation detection
  battery_status   → BatteryStatus (macOS pmset / Linux sysfs)
  system_profile   → SystemProfile (macOS sysctl / Linux /proc + DMI)
  hardware_trend   → TrendData (unchanged)
  session_health   → SessionHealth (NEW: since, peaks, worst levels, alerts)

New types:
  HeadroomLevel    → adequate | limited | insufficient
  AgentAccumulation → new AnomalyType variant
  SessionHealth    → retrospective session summary struct

Platform support:
  macOS  → #[cfg(target_os = "macos")]  — original behavior preserved
  Linux  → #[cfg(target_os = "linux")]  — new code paths
  Other  → #[cfg(not(any(...)))]        — graceful fallbacks