aios/docs/superpowers/specs/2026-08-19-autonomous-control-plane.md

AIOS Autonomous Control Plane — Admission + Invariant + Repair

Why this exists

Recent Agent registration, Task claim, release-worker, credential and retry failures shared one failure mode:

The control plane accepted an intent before the runtime had proved it could execute the intent.

This design does not add another fleet of daemons. It adds one shared library contract that Task API, workers and governed host recovery consume.

Three layers

Intent
  ↓
Runtime Admission
  ↓
System Invariants
  ↓
Repair Policy
  ↓
Execution

Runtime Admission

Admission occurs before Task claim.

A capability such as release:candidate is not considered executable merely because its name matches. The capability contract also binds:

• supported contract version;
• allowed permission;
• forbidden operations;
• runtime dependencies;
• health requirements.

For release:candidate:

permission:
  prepare_release

forbidden:
  production_deploy
  submit_owner_approval
  tag_publish
  baseline_registry_finalize
  runtime_switch

dependencies:
  credential_projection
  trusted_builder

health:
  authenticated_probe
  release_api_health
  worker_liveness

Only a fully passing decision reaches:

EXECUTION_READY

A failed decision remains:

EXECUTION_READY_FAILED

and the worker does not call /claim.

Therefore an infrastructure defect discovered by admission does not consume a business attempt.

System Invariants

The same admission checks are exposed as a machine-readable invariant snapshot.

Examples:

capability_contract_registry
task_capabilities_registered
worker_capabilities_registered
capability_match
forbidden_operations_absent
credential_projection
trusted_builder
authenticated_probe
release_api_health
worker_liveness

A runtime can expose:

HEALTHY
DEGRADED

without relying on a human reconstructing state from logs.

Repair Policy

Failure classification maps to bounded recovery:

DEPENDENCY_UNAVAILABLE       → level 0 / auto local
RESOURCE_UNAVAILABLE         → level 0 / auto local
WORKER_CRASH                 → level 0 / auto local
LEASE_LOST                   → level 0 / auto local

CAPABILITY_CONTRACT_ERROR    → level 1 / same-lineage repair task
CREDENTIAL_PROJECTION_ERROR  → level 1 / same-lineage repair task
UNKNOWN                      → level 1 / diagnostic repair task

POLICY_DENIED                → level 2 / Owner authorization
BUSINESS_PERMANENT           → level 3 / terminal/manual decision

Only business-permanent failure consumes the business retry budget in this first contract.

The current Task API does not yet have a first-class EXECUTION_READY_FAILED durable state. Until it does, the Release Worker enforces the most important invariant by refusing to claim a Task whose admission fails.

Capability Contract Registry

aios_capability_contract.py remains backward-compatible with existing aliases but now validates every alias target against a versioned semantic contract registry.

Unknown capabilities and wildcard capabilities remain fail-closed.

Agent registration and Task creation should next be changed to call registered_capability() so a capability cannot be accepted at registration and rejected only later by the matcher.

Credential rule

Admission probes credential usability, not merely credential existence.

For release candidate creation the authenticated probe intentionally sends an invalid empty /createReleaseCandidate request.

Expected:

HTTP 400

This proves:

credential readable
→ authentication succeeded
→ scope accepted
→ request validation rejected empty business input

A permission failure/401/403/5xx is EXECUTION_READY_FAILED.

Lineage

Repair actions are descriptive, not permission grants. Any repair Task must retain the existing root/parent/attempt/authority chain and use governed same-lineage recovery.

No repair action may silently create a replacement business Task.

Authority separation

Capability answers:

can this runtime perform the operation?

Authority answers:

is this operation currently authorized?

release:candidate never implies Owner approval, deployment, tag publication, baseline finalization or runtime switch.

Deployment sequence

Phase 1 (this candidate):

• Capability Contract Registry;
• shared Autonomous Control Plane library;
• Release Worker pre-claim admission;
• failure classification + repair evidence.

Phase 2:

• Task API uses the same library before returning Tasks from poll and again during claim CAS;
• Task schema gains durable ADMITTED/EXECUTION_READY/EXECUTION_READY_FAILED evidence without counting pre-side-effect infrastructure failures against business attempts.

Phase 3:

• Agent registration validates against the same Capability Contract Registry;
• external connector writes only durable Intent/Command Inbox records and leaves execution to the local control plane.

This sequencing avoids a second controller stack while converging every decision onto one contract.