Condition Codes

Condition Codes

Stable, operator-facing codes returned by aindy-runtime in /ready and /health responses. Automation tools, monitoring dashboards, and incident runbooks should key on these strings.

RuntimeConditionCode

Codes emitted at startup that describe active degradation. Appear in:

• /ready → required_failures (if classification is unsafe_degraded or startup_fatal)
• /ready → checks.runtime_conditions array (all classifications)

Each condition has a classification:

Classification	Effect on /ready	Meaning
safe_degraded	No effect — advisory only	Feature degraded but runtime is operational
unsafe_degraded	Added to required_failures (HTTP 503)	Correctness risk; production should not proceed
startup_fatal	Added to required_failures (HTTP 503)	Startup cannot complete in production

Condition Reference

Code	Classification	What it means
external_python_override_enabled	safe_degraded	AINDY_TRUST_EXTERNAL_PYTHON_EXTENSIONS is set; legacy override active (in-process execution still blocked)
redis_single_instance_mode	safe_degraded	REDIS_URL unset; cross-instance WAIT/RESUME unavailable
event_bus_local_only	safe_degraded	Event bus in local-only mode; cross-instance resume unavailable
event_bus_subscriber_unavailable	safe_degraded	Event bus subscriber failed to start; local-only fallback active
queue_backend_fallback	safe_degraded / unsafe_degraded*	Redis unavailable; queue fell back to in-memory transport
mongo_optional_unavailable	safe_degraded	Optional MongoDB unavailable; embedding-dependent features degraded
mongo_required_unavailable	startup_fatal	Required MongoDB (MONGO_REQUIRED=true) unavailable
distributed_worker_unavailable	unsafe_degraded	Distributed profile requires a worker heartbeat; none detected
event_bus_rehydration_drain_failed	unsafe_degraded	Buffered event drain after rehydration failed; resume events may be lost
wait_eus_rehydration_failed	unsafe_degraded	WAIT execution-unit rehydration failed; pending waits may be stranded
flow_run_rehydration_failed	unsafe_degraded	FlowRun rehydration failed; waiting flows may not resume correctly
dynamic_registry_restore_failed	unsafe_degraded	Dynamic registry restore failed; runtime extensions not restored from DB
dynamic_registry_restore_incomplete	unsafe_degraded	Registry restore incomplete; some flows, nodes, or webhooks missing

*queue_backend_fallback is safe_degraded in single-instance mode, unsafe_degraded in distributed mode.

ReadinessBlockerCode

Codes that appear in required_failures in the /ready response. A non-empty list means status: "not_ready" (HTTP 503).

Code	Trigger
startup_incomplete	API startup sequence has not finished
postgres	PostgreSQL unreachable
schema	Schema contract check failed
redis	Redis unavailable (required by profile)
queue	Queue backend unavailable (required by profile)
event_bus	Event bus unavailable (required by profile)
worker	Worker heartbeat missing (required by profile)
scheduler	Scheduler not running (this instance is elected leader)
plugin_hosts	Plugin host health check failed
plugin_sandbox_attestation	Hostile third-party profile: sandbox attestation violations
(any RuntimeConditionCode)	unsafe_degraded or startup_fatal condition is active

Entity Status Codes

FlowRunStatus

Value	Terminal	Meaning
running	No	Execution in progress
waiting	No	Suspended on WAIT node
completed	Yes	Finished successfully
failed	Yes	Terminated with error

AgentRunStatus

Value	Terminal	Meaning
pending_approval	No	Awaiting approval
approved	No	Approved; execution will begin
executing	No	Plan in progress
delegated	No	Sub-agent dispatched
completed	Yes	Finished successfully
failed	Yes	Terminated with error

Health Status Codes

/health top-level status field:

Value	Meaning
ok	All critical dependencies operational
degraded	Non-critical failures
unhealthy	A critical dependency has failed

Per-dependency status in /health/deep:

Value	Meaning
ok	Operational
degraded	Operational with non-critical failures
unavailable	Unreachable or failed
not_configured	Optional dependency not wired up
not_running	Initialized but not active
not_applicable	Not relevant for this deployment profile

Syscall Response Status

Every syscall response envelope status field:

Value	Meaning
success	Handler completed without exception
error	Handler raised exception or validation failed

Python Reference

These codes are formally defined in AINDY/kernel/condition_codes.py:

from AINDY.kernel.condition_codes import (
    RuntimeConditionCode,
    ReadinessBlockerCode,
    ConditionClassification,
    FlowRunStatus,
    AgentRunStatus,
    DependencyStatus,
    PublicHealthStatus,
    SyscallResponseStatus,
    AutonomyDecision,
)

# Check a condition code
if condition["code"] == RuntimeConditionCode.REDIS_SINGLE_INSTANCE_MODE:
    # handle single-instance mode
    ...