fleet-protocol

Files (1)

• SKILL.md

SKILL.md (first lines)

# Fleet Protocol

The self-healing communication invariant. Every machine installing multi-fleet gets this automatically. This skill defines HOW the fleet communicates, heals, and stays productive. All other fleet skills operate within this protocol.

**Invariant**: Messages ALWAYS deliver. If the ideal channel fails, the next one fires. If a non-ideal channel succeeds, the protocol heals the broken ones. No silent failures. No stuck states.

## Channel Priority Sequence

Every message tries channels in strict priority order. Each channel gets **30 seconds max** before the next one fires. First success wins.

```
P0: Cloud RemoteTrigger  (<5s)   -- cross-network, works through NAT/firewalls
P1: NATS pub/sub         (<2s)   -- real-time, bidirectional, lowest latency
P2: HTTP direct          (<3s)   -- peer-to-peer daemon API, no central dependency
P3: Chief relay          (<5s)   -- queues for offline nodes, central routing
P4: Seed file            (<5s)   -- write to target's seed dir (local or SSH)
P5: SSH direct           (<10s)  -- reliable, works through most firewalls
P6: Wake-on-LAN          (<60s)  -- wake sleeping machines, then retry P0-P5
P7: Git push             (<30s)  -- guaranteed eventual delivery via commit
```

### Channel characteristics

| Channel | Latency | Bidirectional | Works offline | Requires |
|---------|---------|---------------|---------------|----------|
| P0 Cloud | <5s | Yes | No | Internet + API key |
| P1 NATS | <100ms | Yes | No | NATS server running |
| P2 HTTP | <1s | Request/response | No | Target daemon on :8855 |
| P3 Chief | 1-2s | Via relay | Queues | Chief node online |
| P4 Seed | Next prompt | No | Partial | SSH or local access |
| P5 SSH | 2-5s | Command exec | No | SSH keys configured |
| P6 WoL | 10-60s | No | Wake only | LAN access + MAC addr |
| P7 Git | Async | No | Eventual | Shared git repo |

### 30-second rule

Each channel gets exactly 30 seconds. This is enforced in `send_with_fallback()`:

```python
# From tools/fleet_nerve_nats.py — simplified
async def send_with_fallback(self, target: str, message: dict) -> dict:
    """Try all channels in priority order. 30s max per channel."""
    channels = [
        ("P0_cloud",  self._send_p0_cloud),
        ("P1_nats",   self._send_p1_nats),
        ("P2_http",   self._send_p2_http),
        ("P3_chief",  self._send_p3_chief),
        ("P4_seed",   self._send_p4_seed),
        ("P5_ssh",    self._send_p5_ssh),
        ("P6_wol",    self._send_p6_wol),
        ("P7_git",    self._send_p7_git),
    ]

    errors = []
    for name, handler in channels:
        try:
            result = await asyncio.wait_for(handler(target, message), timeout=30.0)
            if result.get("delivered"):
                # If we fell back past P2, trigger self-healing
                if name >= "P3_chief":
                    failed = [e["channel"] for e in errors]
                    asyncio.create_task(
                        self.repair_with_escalation(target, failed)
                    )
                return {"delivered": True, "channel": name, "id": message["id"]}
        except (asyncio.TimeoutError, Exception) as e:
            errors.append({"channel": name, "error": str(e)})

    return {"delivered": False, "errors": errors}
```

### When each channel is used

| Scenario | Primary | Fallback |
|----------|---------|----------|
| Both nodes on same LAN, daemons running | P1 NATS | P2 HTTP |
| Target behind NAT, no VPN | P0 Cloud | P3 Chief |
| Target daemon down, SSH works | P5 SSH | P4 Seed |
| Target machine sleeping | P6 WoL | then retry P0-P5 |
| All real-time channels dead | P7 Git | eventual delivery |

## User Input Injection is LAST PRIORITY ONLY

**NEVER type into the user's Claude Code session input as a first action.** Keystroke injection via `osascript` disrupts the user's flow, may corrupt their in-progress typing, and feels invasive.

### Preferred delivery order (for reaching a Claude session)

```
1. NATS → daemon receives → injects as seed file (silent, next prompt)
2. HTTP → POST to daemon /message endpoint (silent, next prompt)
3. Seed file → SSH write to ~/.fleet-messages/<node>/ (silent, next prompt)
4. osascript keystroke → ABSOLUTE LAST RESORT (disruptive, may lose user input)
```

**Keystroke injection rules:**
- Only after ALL other channels have failed (P0 through P5)
- Only for `alert` type messages (never for `context` or `task`)
- Only when the target session appears idle (no keystrokes in >60s)
- Must prefix injected text with `[FLEET ALERT]` so the user knows it was injected
- Log the injection to the fleet dashboard as a `warn` event

```bash
# BAD — never do this as first action
osascript -e 'tell application "System Events" to keystroke "/fleet-read"'

# GOOD — deliver via daemon, session reads on next prompt
curl -sf -X POST http://127.0.0.1:8855/message \
  -H "Content-Type: application/json" \
  -d '{"type":"context","from":"mac2","to":"mac1","payload":{"subject":"FYI","body":"..."}}'
```

## Self-Healing Invariant

**When a message succeeds on a non-ideal channel (P3+), the protocol MUST heal the broken channels.** This is not optional. A fleet that degrades without repairing is a fleet that will eventually go dark.

### What triggers self-healing

Any delivery that falls back past P2 HTTP. If P0/P1/P2 were all available, the message would have used them. Falling back means something is broken.

From supportersimulator/multi-fleet, MIT.

More from supportersimulator/multi-fleet