A pure-Python resilience, thermal governance, and resource protection runtime for distributed agentic fleets, providing sub-5-second hot standby failover, discrete thermal hysteresis, 3-tier proxy affinity verification, and sliding-window circuit breakers over hexagonal ports.
Long-horizon autonomous swarms operating over hostile external surfaces fail when worker mortality, rate-limit heat, proxy drift, or provisioning storms go unchecked. Swarm Self-Healing enforces four deterministic guarantees:
Eliminates multi-minute mission stalls when an active worker drops or gets banned by maintaining a warm pool of STANDBY_READY Scouts and promoting replacements in under 5 seconds.
Prevents irreversible identity burn via a bounded thermal score in [0.0, 1.0] with discrete friction deltas and hysteresis that preemptively moves stressed workers to COOLING_DOWN at 0.78.
Blocks cross-account contamination and residential DHCP drift through 3-tier network affinity validation (Endpoint Match, Subnet/ASN Match, or Hard Reject) before any external dispatch.
Halts runaway SIM/eSIM and proxy financial drain during systemic target outages via a sliding-window ResourceCircuitBreaker that locks incubator expenditure until explicit operator review.
Formalized in SSH-SPEC-0001 and implemented in zero-I/O pure Python 3.11+ with Pydantic v2 and hexagonal typing.Protocol ports.
Reconciles fleet invariants on every heartbeat tick: demotes overheated or banned workers, immediately promotes the coolest STANDBY_READY Scout into ACTIVE duty, and triggers asynchronous background pool replenishment.
Tracks discrete operational friction (normal_turn +0.06, TurnTimeout +0.18, CaptchaOrBlock +0.35, BanDetected → 1.0) and passive decay (-0.08/min), enforcing a wide 0.35..0.78 hysteresis deadband against state thrashing.
Enforces strict 1:1 identity-to-proxy binding while gracefully tolerating legitimate ISP DHCP renewals within the same ASN and /24 IPv4 (or /48 IPv6) prefix, raising ProxyAffinityViolationError on anomalous jumps.
Tracks ban and provisioning failures across a rolling 600-second window. Reaching 5 failures trips the breaker to OPEN, blocking all automated provisioning until explicit operator inspection and unlock().
Designed as a standalone, zero-I/O core that plugs into any orchestrator, ledger, or cloud provisioner via two structural protocols.
Zero coupled database drivers or HTTP clients. State persistence and infrastructure lifecycle are injected strictly via SwarmLedgerPort and ScoutProvisionerPort.
Hot standby promotion always executes before new cold provisioning, ensuring active mission continuity even if the external incubator is degraded or circuit-broken.
Piecewise-linear clamping guarantees heat_score ∈ [0.0, 1.0] under arbitrary event bursts, while dual thresholds (0.35 vs 0.78) prevent oscillation.
Distinguishes benign ISP IP rotation within the same /24 subnet and ASN from true proxy hijacking, updating records in-place without dropping active sessions.
Validated by an isolated pytest suite proving sub-5-second failover promotion, hysteresis saturation, 3-tier subnet checks, and circuit-breaker storm suppression.
The complete SSH-SPEC-0001 specification, hexagonal port definitions, and pure-Python reference package with full pytest verification are available under the MIT License.
