System Maneuverability Score

The System Maneverability (SM) Score is a real-time, composite metric that quantifies the available computational capacity of a hardware node within the AetherOS ecosystem. It functions as the "supply" side of the Agentic Maneuverability Score equation, providing a single integer from 0 (no capacity) to 100 (idle capacity) that represents the system's readiness to take on new work.

In the language of Energy-Maneuverability Theory, the SM Score is analogous to an aircraft's Specific Excess Power (P_s) at a given moment. It is not a measure of the system's total potential power, but its immediate, usable power to perform a "maneuver"—such as loading a large AI model or executing a complex task.

Core Philosophy: The Guardian's "Health"

The SM Score is the technical implementation of an agent's physical embodiment and health. For a Guardian agent, a high SM score indicates it is undamaged, has ample fuel, and is in a position of tactical advantage. A low score indicates it is "bleeding energy"—perhaps due to thermal stress ("overheating"), memory pressure ("high G-loading"), or I/O bottlenecks ("control surface sluggishness").

This score is what allows an agent to be truly embodied and self-aware. Before committing to a demanding action, the system first checks its own health, ensuring it has the physical capacity to execute the mission virtuously.

Technical Description

The SM Score is calculated by the `get_sm_score.py` sensor script, which aggregates multiple sources of system stress into a unified set of penalties subtracted from a baseline of 100.

Penalty Sources

The total penalty is the sum of several weighted factors, each representing a form of "energy bleed" on the system:

• Processor Load (CPU & GPU Utilization): The primary measure of ongoing work. High utilization incurs a significant penalty.
• Thermal Stress: A penalty is applied if system temperatures exceed a warning threshold (70°C) and scales up to a maximum penalty at a critical threshold (95°C), representing the risk of physical damage.
• I/O Bottleneck (Wait Time): High I/O wait times, where the CPU is idle waiting for disk or network operations, indicate a critical bottleneck and reduce maneuverability.
• Memory Pressure: Penalties are applied if swap usage is high (indicating physical RAM is exhausted) or if total RAM utilization exceeds a critical threshold (80%).
• System Trauma (Crash Detection): A large, immediate penalty is applied if the script detects evidence of a recent "Out of Memory" (OOM) crash in the system's kernel log (`dmesg`). This represents lasting instability from a catastrophic failure.

System Architecture

The SM protocol is a decoupled, multi-component system designed for resilience and portability.

1. The Sensor (`get_sm_score.py`): The core Python script that observes all system metrics via libraries like `psutil` and calculates the final score.
2. The Scribe (`log_sm_score.sh`): A shell script, typically run as a cron job every minute, that executes the sensor, logs the historical data, and calculates a 7-day rolling average.
3. The Public Record (`/tmp/sm_status.json`): The Scribe writes the output of the sensor (both the current score and the rolling average) to this simple JSON file. This file acts as the canonical, decoupled source of truth for any other process needing to know the system's status.
4. The Cockpit Display (`extension.js`): A GNOME Shell extension that reads the public record every 5 seconds to provide a persistent, at-a-glance display of the SM score on the operator's desktop.