Skip to main content

Runtime States

This page explains the runtime status fields exposed by replay() and how to interpret them.

The main health fields​

The runtime health snapshot exposes several different dimensions:

  • status
  • authorityState
  • protectionLevel
  • durability
  • tier
  • compatEnforcement
  • governanceAttachment
  • unresolvedReceiptCount
  • bypass_detected

These fields describe different things. Read them together.

status​

Broad health rollup:

  • healthy
  • degraded
  • inactive

Use this as the first signal, not the full explanation.

Examples:

  • unresolved governed receipts -> degraded
  • killed session -> inactive
  • zero-config review-only state can still be healthy

authorityState​

How much authority the runtime currently has:

  • active
  • advisory
  • compromised
  • recovering
  • killed
  • inactive

Use this to answer: “should I trust this session as authoritative right now?”

Examples:

  • bypass detected -> compromised
  • attached authoritative runtime -> active
  • no approved plan yet -> often advisory

protectionLevel​

Effective runtime protection tier:

  • monitor
  • protect
  • govern

Meaning:

  • monitor -> evaluate without blocking
  • protect -> local enforcement/blocking
  • govern -> durable server-backed authority

Important detail:

If a session was supposed to be govern-level but lost authority, the effective protection can drop to protect.

durability​

Where durable authority currently lives:

  • server
  • degraded-local
  • inactive

Meaning:

  • server -> active durable server backing
  • degraded-local -> authority degraded or fell back locally
  • inactive -> no durable authority in play

Common reasons for degraded-local:

  • runtime init degraded
  • authority was lost mid-session
  • unresolved governed receipts exist

tier​

Enforcement tier:

  • strong
  • compat

Roughly:

  • strong -> authoritative server-backed runtime behavior
  • compat -> compatibility/local behavior

compatEnforcement​

Compatibility-tier enforcement behavior:

  • protective
  • advisory

Use it to answer whether compatibility-tier violations are blocking or only being surfaced.

governanceAttachment​

Especially important for zero-config governance sessions.

Values:

  • pending
  • no_plan
  • attached
  • artifact_invalid
  • attachment_failed
  • fetch_failed

Meaning:

  • pending -> plan fetch or attachment still in progress
  • no_plan -> hosted lookup succeeded, but no approved plan exists
  • attached -> approved plan found and runtime attached successfully
  • artifact_invalid -> approved plan exists, but the artifact failed validation
  • attachment_failed -> approved plan exists, but runtime init failed
  • fetch_failed -> hosted governance lookup failed

This field usually explains zero-config confusion fastest.

Important scope note:

governanceAttachment is specific to zero-config governance sessions. It is not the universal explanation field for every explicit local replay() configuration.

unresolvedReceiptCount​

Counts tool executions whose receipt submission failed after the executor ran.

Why it matters:

  • the side effect may already have happened
  • but the control plane does not have a clean committed receipt
  • the runtime treats that as ambiguous pending work

If this is non-zero, treat the session as degraded until reconciled.

bypass_detected​

This means the original client path was called directly instead of going through session.client.

Operational meaning:

  • the wrapped path was bypassed
  • the session should not be treated as authoritative
  • start a fresh session after fixing the code path

Common combinations​

Review-first zero-config state​

  • status: healthy
  • authorityState: advisory
  • protectionLevel: monitor
  • governanceAttachment: no_plan

Meaning:

The runtime is collecting/reviewing, but there is no approved artifact yet.

Attached approved state​

  • governanceAttachment: attached
  • status: healthy

Meaning:

The runtime found and attached to an approved artifact.

Hosted lookup failed​

  • status: degraded
  • governanceAttachment: fetch_failed

Meaning:

The runtime could not fetch the hosted plan. In staging/production-style paths this should be treated as fail closed.

Approved artifact broken​

  • status: degraded
  • governanceAttachment: artifact_invalid

Meaning:

Approval exists, but the artifact cannot be trusted.

Bypassed session​

  • authorityState: compromised
  • bypass_detected: true

Meaning:

Someone escaped the wrapped path. Treat the session as untrustworthy.

Receipt ambiguity​

  • status: degraded
  • unresolvedReceiptCount > 0
  • durability: degraded-local

Meaning:

The runtime cannot cleanly prove governed side effects were recorded.

Recovery path​

There is also an operator/internal recovery path in the runtime control plane. When a session is explicitly put through recovery, authorityState may move through a recovery-oriented state instead of cleanly staying active/advisory.

What to check first​

When a governed runtime looks wrong, check:

  1. governanceAttachment
  2. authorityState
  3. protectionLevel
  4. durability
  5. unresolvedReceiptCount
  6. bypass_detected

That order usually tells you whether the problem is:

  • no approved plan
  • broken artifact
  • failed hosted lookup
  • lost authority
  • bypass
  • ambiguous receipt state