Skip to content

Accountability infrastructure for autonomous engineering

DoneState documentation

Guides, concepts, complete references, security boundaries, and operating help.

Hosted liveSource

DoneState docs / Troubleshooting

Treat the state as evidence before choosing the retry

The safest recovery action depends on what DoneState can prove happened. Do not collapse every non-VERIFIED result into 'run it again'.

Your first attempt stopped: choose the next action

Connected, but execution cannot start
Inspect credential status and the recorded capability failure. A stored key does not prove API credit or a usable project. Check the API account behind that key; replace it only through a fresh secure setup link. Do not repeat execution to test funding.
Repository access refused
Check which GitHub identity authorised DoneState, its push permission and the exact base branch. Public visibility alone does not grant write access. Private execution requires the separately supported selected-App path; do not broaden permissions as a guess.
FAILED_SAFE with a provider funding or configuration error
Correct the recorded cause first. Inspect whether the run is resumable; use the same run only when its state permits it. A terminal failed run needs a deliberate new objective after correction, not a blind replay of the old one.
PR exists, but verification is pending
Keep the existing PR and sealed head. Check required CI and whether the trusted verifier has access to this exact repository. Request a fresh independent observation when appropriate; do not rerun implementation merely to obtain proof, or describe pending evidence as VERIFIED.
Publication result is unknown
Inspect the expected GitHub branch, commit and PR against the recorded run before retrying. AMBIGUOUS_EFFECT preserves uncertainty; a timeout is not proof that publication failed.

Common states and first actions

BLOCKED_AUTHORITY
The requested consequence is outside current authority. Check objective authorities, selected-repository mode, and identity restrictions before changing access.
BLOCKED_CAPABILITY
A required capability is unavailable. Typical causes include no execution credential, private-repository access without the selected App path, or a missing configured integration.
BLOCKED_SAFETY
A safety invariant stopped work. Inspect the recorded reason and change budget/policy only when the broader consequence is intentional.
AMBIGUOUS_EFFECT
A consequential external effect may or may not have happened. Inspect GitHub/provider state before any retry.
FAILED_SAFE
Execution failed without claiming success. Inspect the exact failure and decide whether resume or a corrected new objective is appropriate.
AWAITING_VERIFICATION
Not an execution failure. The run is sealed and needs an independent verifier response before terminal VERIFIED.

Execution credential problems

  1. 01

    Check status first

    Call get_openai_credential_status. Do not ask the user to paste the API key into the MCP conversation.
  2. 02

    Create a fresh setup link

    If the credential is absent or needs replacement, usecreate_openai_credential_setup. Setup links are short-lived and single-use.
  3. 03

    Cancel active work before credential deletion

    The service fails closed rather than deleting a credential while an active objective is using it.

OAuth or setup-link problems

If DoneState says the setup origin is invalid, reconnect the MCP service from its canonical HTTPS origin and request a new setup link. If a link reports expired or invalid, do not reuse it; create a new one.

The canonical hosted endpoint ishttps://donestate.proofandstate.com/mcp.

Repository access problems

Public repository
The authenticated GitHub identity must be able to push when the objective requires remote publication.
Private repository
Use a selected DoneState GitHub App installation in pr_only mode. OAuth alone is not the private execution path.
Observe-only selection
A repository selected in observe mode cannot be silently promoted to PR-only repair by starting an objective.

When an effect is ambiguous

Local CLI and agent recovery

  1. 01

    Inspect before retrying

    Run donestate status RUN_ID and donestate verify-log RUN_ID. Agents should consume the structured JSON state rather than infer success from terminal text.
  2. 02

    Check local GitHub capability

    Publication and maintenance use the locally authenticated gh CLI. Confirm gh auth status and repository access rather than trying to recreate hosted OAuth locally.
  3. 03

    Resolve dirty-worktree refusal deliberately

    Local publication and maintenance repair require a clean starting repository. Commit, stash, or deliberately remove unrelated work; DoneState will not guess which local changes are safe.
  4. 04

    Delete only settled state

    Use donestate cancel RUN_ID when cancellation is eligible, then donestate delete RUN_ID --confirm. Deleting local DoneState state does not delete remote branches, pull requests, or repository history.

Verification does not complete

Confirm the run is actually AWAITING_VERIFICATION, that the sealed head still exists, and that the configured verifier is reachable. For new hosted objectives and newly published local CLI subjects, the verifier must return the complete v2 response; an attestation-only legacy payload is insufficient. Local users can run donestate verify-opstruth RUN_ID --endpoint URL or validate an offline bundle with donestate verify-response --file FILE.