Skip to main content

Troubleshooting

Common issues with replay() and how to fix them.

This page is focused on the current public runtime path: zero-config governance, Studio approval, and hosted runtime attachment.

No approved plan yet​

Typical signals:

  • governanceAttachment: no_plan
  • runtime stays advisory/non-blocking
  • Studio shows no active approval

What it means:

The hosted lookup succeeded, but there is no approved plan for that agent/environment yet.

What to do:

  1. Open Governance Studio
  2. Review the workspace draft
  3. Resolve blockers
  4. Approve when ready

Hosted plan lookup failed​

Typical signals:

  • governanceAttachment: fetch_failed
  • runtime health becomes degraded

What it means:

The runtime could not fetch the hosted governance plan.

What to do:

  1. Check hosted connectivity
  2. Check runtime URL / environment assumptions
  3. Treat staging/production-style flows as fail closed until the lookup succeeds again

Approved artifact is invalid​

Typical signals:

  • governanceAttachment: artifact_invalid
  • hosted plan endpoint returns APPROVED_ARTIFACT_INVALID

What it means:

An approved plan exists, but its runtime artifact is not valid enough to attach.

What to do:

  1. Check the current approval/artifact path
  2. Re-approve or repair the artifact-producing path
  3. Do not treat the runtime as attached until the artifact becomes valid

Attachment failed​

Typical signals:

  • governanceAttachment: attachment_failed

What it means:

The hosted plan exists, but runtime initialization failed after lookup.

What to do:

  1. Check the runtime diagnostics
  2. Check the approved artifact contents
  3. Treat the runtime as degraded until attachment succeeds

Session is compromised​

Typical signals:

  • authorityState: compromised
  • bypass_detected: true

What it means:

Code bypassed session.client and called the original client path directly.

What to do:

  1. Fix the code path so all runtime calls go through session.client
  2. Start a fresh session
  3. Do not trust the compromised session as authoritative

Unresolved receipts exist​

Typical signals:

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

What it means:

A governed executor ran, but receipt submission did not complete cleanly. The runtime now has ambiguous pending work.

What to do:

  1. Assume a side effect may already have happened
  2. Reconcile before continuing
  3. Avoid treating the session as clean authority until that ambiguity is resolved

Approval preview is blocked​

Typical signals:

  • workspace snapshot is not ready_for_approval
  • approval preview contains blockers

What it means:

The Studio-side approval boundary is correctly refusing approval.

What to do:

  1. Review open judgments
  2. Review impact preview / Focus
  3. Clear blockers before retrying

Runs exist, but references are stale​

Typical signals:

  • References page shows STALE
  • comparisons are advisory

What it means:

The current trusted reference is stale and should not be treated as current enforced truth forever.

What to do:

  1. Keep submitting runs for the relevant configuration
  2. Let a replacement candidate accumulate successful runs
  3. Promote the replacement when ready

Recovery path​

There is an operator/internal recovery path for governed sessions.

You may see runtime state moving through a recovery-oriented lifecycle rather than cleanly remaining active/advisory. In that case, treat the session as operationally exceptional until recovery is complete.

What to check first​

When a governed runtime looks wrong, check in this order:

  1. governanceAttachment
  2. authorityState
  3. protectionLevel
  4. durability
  5. unresolvedReceiptCount
  6. Governance Studio approval/workspace state

That sequence usually tells you whether the problem is:

  • no approved plan
  • broken artifact
  • failed hosted lookup
  • lost authority
  • bypass
  • ambiguous governed side effects