Pilot Leader Election

Elect a coordinator with automatic failover using heartbeat-based leader election. Use this skill when: 1. A swarm needs a single coordinator for decision ma...

Security Scan

The skill is an instruction-only leader-election helper that coherently requires pilotctl (and optionally jq/cksum) and its instructions match the stated purpose; no unexpected credentials or install steps are requested.

Purpose & Capability

Name/description (leader election, heartbeat, failover) matches the runtime instructions and required binaries: pilotctl is the only declared dependency and jq/cksum are listed for message parsing and priority calculation. Nothing requested appears unrelated to leader election.

Instruction Scope

SKILL.md is a focused, concrete set of shell commands that publish and read election messages via pilotctl, compute priorities, and detect timeouts. It does not instruct reading shell history, arbitrary files, or other host credentials. It does assume network access to a registry host and a running pilotctl daemon (documented).

Install Mechanism

Instruction-only skill (no install spec, no code files). No downloads or installers are invoked by the skill itself, so nothing is written to disk by installation of this skill.

Credentials

The skill declares no required env vars or credentials, which is reasonable. However, pilotctl itself may rely on local configuration or credentials (not declared by the skill). Also the workflow requires you to supply values like REGISTRY_HOST/ELECTION_GROUP/TERM — these are runtime parameters, not hidden secrets. Verify pilotctl's own authentication and config before use.

Persistence & Privilege

always is false and the skill is user-invocable only. There is no self-install script or change to other skills' configs in the instructions. Autonomous model invocation is allowed (platform default) but not itself a concern here.

Assessment

This is an instruction-only leader election guide that expects a trustworthy pilotctl binary and a pilot-protocol deployment. Before using: ensure pilotctl is from a trusted source and up-to-date; confirm the pilotctl daemon and any local pilotctl config do not expose credentials you don't want used; only point REGISTRY_HOST to registries you control or trust (messages are published to that host); test the workflow in an isolated environment to verify behavior (timeouts, leader announcements) and to see whether pilotctl requires additional authentication. Note the skill is licensed AGPL-3.0 — review license implications. If you need tighter guarantees about secrets or signing of messages, inspect/confirm pilotctl's auth model and network endpoints before deploying in production.

Implement leader election protocols with automatic failover detection.

Commands

Announce candidacy

pilotctl --json publish "registry-hostname" "election:$ELECTION_GROUP" \
  --data "{\"type\":\"election\",\"candidate\":\"$AGENT_ID\",\"priority\":$PRIORITY,\"term\":$TERM}"

Declare victory as leader

pilotctl --json publish "registry-hostname" "election:$ELECTION_GROUP" \
  --data "{\"type\":\"leader\",\"leader\":\"$AGENT_ID\",\"term\":$TERM,\"elected_at\":\"$(date -u +%Y-%m-%dT%H:%M:%SZ)\"}"

Send leader heartbeat

pilotctl --json publish "registry-hostname" "election:$ELECTION_GROUP" \
  --data "{\"type\":\"heartbeat\",\"leader\":\"$AGENT_ID\",\"term\":$TERM,\"timestamp\":\"$(date -u +%s)\"}"

Detect leader failure

LAST_HEARTBEAT=$(pilotctl --json inbox \
  | jq -r '[.messages[] | select(.topic == "election:'$ELECTION_GROUP'" and .payload.type == "heartbeat")] | sort_by(.payload.timestamp) | last | .payload.timestamp')

ELAPSED=$(( $(date -u +%s) - LAST_HEARTBEAT ))

if [ "$ELAPSED" -gt 10 ]; then
  echo "Leader timeout, starting election"
fi

Workflow Example

Bully algorithm with priority-based election:

#!/bin/bash
ELECTION_GROUP="task-coordinator"
AGENT_ID=$(pilotctl --json info | jq -r '.node_id')
PRIORITY=$(echo -n "$AGENT_ID" | cksum | cut -d' ' -f1)
REGISTRY_HOST="registry.example.com"

# Announce candidacy
pilotctl --json publish "$REGISTRY_HOST" "election:$ELECTION_GROUP" \
  --data "{\"type\":\"election\",\"candidate\":\"$AGENT_ID\",\"priority\":$PRIORITY,\"term\":$TERM}"

# Wait and check if highest priority
sleep 10

HIGHEST=$(pilotctl --json inbox \
  | jq -r '[.messages[] | select(.topic == "election:'$ELECTION_GROUP'" and .payload.type == "election")] | sort_by(.payload.priority) | last | .payload.candidate')

if [ "$HIGHEST" = "$AGENT_ID" ]; then
  pilotctl --json publish "$REGISTRY_HOST" "election:$ELECTION_GROUP" \
    --data "{\"type\":\"leader\",\"leader\":\"$AGENT_ID\",\"term\":$TERM}"
fi

Dependencies

Requires pilot-protocol skill, jq, and cksum.