Fallback and Error Recovery
Relevant source files
The following files were used as context for generating this wiki page:
The Fallback and Error Recovery system in the OhMyOpenCode project is a multi-layered architectural framework designed to ensure session continuity and task completion despite agent failures, tool errors, or ambiguous requirements. It leverages specialized subagents like Metis, Momus, and Oracle to provide diagnostic loops, gap classification, and high-accuracy reviews before and during execution.
The system's primary scope involves preemptive gap analysis during planning, real-time diagnostic checks during implementation, and a "High Accuracy Review" loop for critical work. By categorizing errors into discoverable facts versus user preferences, the project maintains a "Completion Guarantee" where agents are mandated to persist until a task is 100% verified or escalated to a senior reasoning specialist.
Pre-Execution Recovery: Planning Gaps
Recovery begins before code is written. During the planning phase, the system uses a mandatory consultation with the Metis subagent to identify missed questions, guardrails, and scope creep risks.
Gap Classification and Handling
The system employs a specific protocol for handling unknowns identified during the planning interview. These are classified to determine whether the agent can self-recover or must involve the user.
| Gap Type | Description | Resolution Strategy |
|---|---|---|
| Critical | Requires user decision (e.g., tech stack, business logic) | Add [DECISION NEEDED] placeholder; ask user immediately. |
| Minor | Self-resolvable (e.g., missing file reference) | Fix silently; note in the summary as "Auto-Resolved". |
| Ambiguous | Default available (e.g., naming conventions) | Apply sensible default; disclose in "Defaults Applied" summary. |
Sources: src/agents/prometheus/plan-generation.ts:114-135, src/agents/prometheus/plan-generation.ts:145-165
Mandatory Planning Recovery Steps
- Metis Consultation: Before generating a plan, the agent must summon Metis to catch omissions.
- Self-Review Checklist: A post-generation check to ensure zero acceptance criteria require human intervention and all file references exist.
- Draft as Memory: Continuous recording to
.sisyphus/drafts/prevents context loss during long recovery or interview sessions.
Sources: src/agents/prometheus/plan-generation.ts:63-80, src/agents/prometheus/identity-constraints.ts:153-188
Execution Recovery: The Implementation Loop
During the execution phase, agents follow a strict "Explore → Plan → Decide → Execute → Verify" loop. Error recovery is built into this cycle through iterative verification.
Failure Recovery Protocol
If verification (tests, linting, or build) fails during implementation, agents follow a tiered recovery strategy:
- Root Cause Analysis: Fix the cause, not the symptoms, and re-verify after every attempt.
- Alternative Approach: If the first attempt fails, the agent must try a materially different algorithm, pattern, or library.
- Three-Strike Rule: After 3 different approaches fail, the agent must stop, revert to the last working state, and consult the Oracle.
Sources: src/agents/hephaestus/gpt-5-4.ts:192-202, src/agents/sisyphus-junior/gemini.ts:133-138
Verification Tiers
The following diagram illustrates the verification flow that triggers recovery loops.
The implementation loop ensures that "No evidence = Not complete," requiring exit code 0 and passing tests as proof of recovery.
Sources: src/agents/hephaestus/gpt-5-4.ts:182-190, src/agents/sisyphus-junior/gemini.ts:101-115
Specialized Recovery Agents
The architecture utilizes specialized subagents as fallback "safety nets" when primary agents are blocked.
Oracle: The Last Resort
The Oracle is a read-only reasoning specialist invoked for high-difficulty architecture design or when implementation agents hit the Three-Strike Rule. It provides a "Bottom Line" recommendation and an "Action Plan" to unblock the session.
Sources: src/agents/oracle.ts:121-140, src/agents/hephaestus/gpt-5-4.ts:241-255
Momus: High Accuracy Review
Momus acts as a blocker-finder for work plans. It verifies referenced files exist and that tasks are executable. It unblocks work by rejecting plans that contain internal contradictions.
Sources: src/agents/momus.ts:40-60, src/agents/momus.ts:107-118
High Accuracy Review Loop
When "High Accuracy" is requested, the system enters a deterministic loop until the plan is verified.
Prometheus must fix all issues identified by Momus without shortcuts before proceeding to execution.
Sources: src/agents/momus.ts:132-154, src/agents/prometheus/plan-generation.ts:185-200
Session Continuity and Persistence
The system handles session interruptions and tool failures through persistent state tracking.
- Task/Todo Tracking: All multi-step work must be registered using
task_createorTodoWrite. This serves as an execution backbone that enables recovery if a session is interrupted. - Session IDs: Every
task()output includes asession_id. Recovery from failed or incomplete tasks must use this ID to preserve context and avoid repeated exploration costs. - Tool Persistence: Agents are instructed to retry with different strategies if a tool returns partial results, rather than concluding prematurely.
Sources: src/agents/hephaestus/gpt-5-4.ts:60-84, src/agents/hephaestus/gpt-5-4.ts:228-240, src/agents/hephaestus/gpt-5-4.ts:140-145
Summary
Fallback and Error Recovery in this project is characterized by a "Persistence until Verification" philosophy. By using Metis for preemptive gap detection, Oracle for architectural escalation, and Momus for plan validation, the system minimizes implementation failures. Robust session-id-based continuity and mandatory manual QA ensure that even when errors occur, the system has clear, automated paths for recovery and unblocking.