Fleet Sync (V2.2)

Fleet Sync provides local-first MCP tool distribution and IDE rendering across canonical VMs.

Canonical Surfaces

VMs

• macmini - Primary macOS host
• homedesktop-wsl - WSL2 workstation
• epyc6 - Primary Linux host
• epyc12 - Secondary Linux host

IDE Lanes

Tool Classes

MCP Tools (integration_mode: mcp)

Rendered into IDE MCP configs with mcp.* block.

CLI Tools (integration_mode: cli)

Standalone CLI tools, not rendered to IDE configs.

Commands

Host-Level Convergence

# Drift detection only
~/agent-skills/scripts/dx-mcp-tools-sync.sh --check --json

# Install tools + render IDE configs
~/agent-skills/scripts/dx-mcp-tools-sync.sh --apply --json

# Force re-apply + verify
~/agent-skills/scripts/dx-mcp-tools-sync.sh --repair --json

Fleet-Wide Operations

# Fleet-wide drift check
~/agent-skills/scripts/dx-fleet.sh converge --check --json

# Fleet-wide apply
~/agent-skills/scripts/dx-fleet.sh converge --apply --json

# Fleet-wide repair
~/agent-skills/scripts/dx-fleet.sh converge --repair --json

Fleet Health Checks

# Daily runtime checks
~/agent-skills/scripts/dx-fleet.sh check --mode daily --json

# Weekly governance checks
~/agent-skills/scripts/dx-fleet.sh check --mode weekly --json

Fleet Audit

# Daily audit
~/agent-skills/scripts/dx-fleet.sh audit --daily --json

# Weekly audit
~/agent-skills/scripts/dx-fleet.sh audit --weekly --json

Validation Layers

Layer 1: Host Runtime Health

Verify tool binaries work on each host:

# MCP tools
tldr-mcp --version || llm-tldr --version
contextplus --version

# CLI tools
cm --version
cm quickstart --json
cm doctor --json

Layer 2: Config Convergence

~/agent-skills/scripts/dx-mcp-tools-sync.sh --apply --json --state-dir ~/.dx-state/fleet
~/agent-skills/scripts/dx-mcp-tools-sync.sh --check --json --state-dir ~/.dx-state/fleet

Layer 3: Fleet Gates

~/agent-skills/scripts/dx-fleet.sh check --mode daily --json --state-dir ~/.dx-state/fleet
~/agent-skills/scripts/dx-fleet.sh audit --weekly --json --state-dir ~/.dx-state/fleet

Layer 4: Client Visibility

Verify MCP tools appear in IDE clients:

codex mcp list    # Should show llm-tldr, context-plus
claude mcp list   # Should show llm-tldr, context-plus
gemini mcp list   # Should show llm-tldr, context-plus
opencode mcp list # Should show llm-tldr, context-plus

Note: cass-memory is CLI-native and does NOT need to appear in MCP lists.

Fail-Closed Semantics

The overall status is computed from BOTH tool rows AND file rows:

• If tools_fail > 0 → overall = "red"
• If files_fail > 0 → overall = "red"
• If warn > 0 → overall = "yellow"
• Otherwise → overall = "green"

Manifest Source

Single source of truth: ~/agent-skills/configs/mcp-tools.yaml

Key fields per tool:

• enabled: true/false
• integration_mode: "mcp" or "cli"
• install_cmd: Installation command
• health_cmd: Health check command
• target_ides: IDE targets (MCP only)
• mcp: MCP server config block (MCP only)

Related Skills

• llm-tldr: Static analysis context slicing
• cass-memory: CLI-native episodic memory
• context-plus: Structural context analysis

Related Docs

• ~/agent-skills/docs/FLEET_SYNC_SPEC.md - Architecture contract
• ~/agent-skills/docs/FLEET_SYNC_RUNBOOK.md - Operational runbook
• ~/agent-skills/docs/IDE_SPECS.md - IDE specifications
• ~/agent-skills/scripts/canonical-targets.sh - VM/IDE registry

Escalation

• green: No action
• yellow: Run dx-fleet repair --json
• red: Run repair on failing hosts and rerun checks