Session Recovery & Resiliency

Relevant source files

The following files were used as context for generating this wiki page:

• src/agents/hephaestus.ts
• src/agents/sisyphus.ts
• src/agents/atlas/default.ts
• src/agents/prometheus/plan-generation.ts
• src/features/builtin-commands/templates/handoff.ts

Session Recovery and Resiliency in the OhMyOpenCode project refers to the systematic mechanisms designed to maintain execution continuity, handle failures autonomously, and preserve state across long-running or complex tasks. This system ensures that even if an agent process is interrupted or a specific approach fails, the project can resume work without losing progress or context.

The core of this resiliency lies in a multi-layered approach involving persistent Task/Todo tracking, session-based continuity for subagents, a dedicated "Handoff" mechanism for context transfer, and autonomous recovery protocols for implementation failures. By anchoring work to atomic steps and unique session identifiers, the system minimizes the need for human intervention when technical or environment-related blockers arise.

Task and Todo Discipline

The primary coordination and recovery mechanism is the strict enforcement of task management. Agents like Hephaestus and Sisyphus use this as an "execution backbone" to prevent drift and enable seamless continuation if a session is interrupted.

Mandatory Workflow

Agents must follow a strict lifecycle for every non-trivial (2+ steps) task:

1. Creation: TaskCreate or todowrite immediately upon receiving a request to define atomic steps.
2. State Management: Update status to in_progress before starting a step (one at a time) and completed immediately after.
3. Scope Changes: Update tasks/todos BEFORE proceeding with any changes to the original plan.

Sources: src/agents/hephaestus.ts:16-36, src/agents/sisyphus.ts:35-55

Resiliency Benefits

Feature	Resiliency Benefit
Execution Anchor	Prevents drift from original user request during long sessions.
Recovery	Enables resuming work exactly where it left off after an interruption.
Visibility	Provides real-time progress tracking to ensure state is always known.

Sources: src/agents/hephaestus.ts:40-42, src/agents/sisyphus.ts:59-62

Session Continuity & ID Tracking

Session continuity is achieved through the mandatory use of session_id when delegating tasks to subagents. This allows subagents to preserve full conversation context, preventing redundant file reads and setup.

A diagram showing the flow of session IDs between orchestrators and subagents to maintain state.

Sources: src/agents/sisyphus.ts:285-300, src/agents/atlas/default.ts:150-165

Critical Continuity Scenarios

Agents MUST use the session_id in the following failure or recovery scenarios:

• Task Failure: Resuming the same session with specific error instructions.
• Verification Failure: Sending failed lint or test output back to the same subagent for fixing.
• Follow-up: Asking clarification on a result without starting fresh.

Sources: src/agents/sisyphus.ts:302-307, src/agents/atlas/default.ts:153-158

Handoff Mechanism

When session context length exceeds capacity or quality degrades, the /handoff command is used to synthesize a fresh start while preserving critical information.

Handoff Phases

1. Validation: Confirming meaningful work exists to preserve.
2. Programmatic Gathering: Using session_read, todoread, and git diff to extract concrete session data.
3. Extraction: Summarizing completed work, pending tasks, and established constraints from a first-person perspective.
4. Formatting: Generating a structured HANDOFF CONTEXT block for the user to paste into a new session.

Sources: src/features/builtin-commands/templates/handoff.ts:8-50

Handoff Summary Structure

Section	Description
User Requests (AS-IS)	Verbatim requirements to ensure original intent is not lost.
Work Completed	Progress status of modified files and decisions.
Pending Tasks	Incomplete items from the current Todo list.
Key Files	Prioritized list of workspace-relative paths involved in the work.
Explicit Constraints	Verbatim rules from user or system agents.

Sources: src/features/builtin-commands/templates/handoff.ts:65-103

Autonomous Failure Recovery

Agents are equipped with a "Fix Protocol" to recover from implementation failures (e.g., failed tests or lint errors) without immediately consulting the user.

A flowchart illustrating the multi-stage autonomous recovery logic used by agents before escalating to a human user.

Sources: src/agents/hephaestus.ts:474-486, src/agents/sisyphus.ts:340-350

Recovery Thresholds

• 3-Approach Rule: Agents must try at least three meaningfully different approaches before admitting blockage.
• Reversion Protocol: If all approaches fail, the agent MUST revert to the last working state (e.g., git checkout) to ensure the codebase is never left broken.
• Oracle Consultation: Before asking a user, agents consult the "Oracle" with the full failure context for architectural or logical guidance.

Sources: src/agents/hephaestus.ts:400-415, src/agents/sisyphus.ts:352-358

Planning Resiliency (Prometheus)

The Prometheus agent provides resiliency at the planning stage by mandatory Metis consultation and gap analysis before work begins.

Plan Generation Todos

Upon triggering plan generation, the system immediately registers a recovery-focused todo list:

1. Consult Metis for gap analysis.
2. Generate work plan file.
3. Classify gaps (Critical, Minor, Ambiguous).
4. Wait for user decisions on critical gaps.
5. Guided execution start.

Sources: src/agents/prometheus/plan-generation.ts:25-40

Gap Handling Protocol

Gap Type	Recovery Action
Critical	Insert [DECISION NEEDED] placeholder and ask user.
Minor	Fix silently in the plan and note in the final summary.
Ambiguous	Apply a sensible default and disclose it to the user.

Sources: src/agents/prometheus/plan-generation.ts:79-100

Summary

Session Recovery & Resiliency in OhMyOpenCode is a robust framework that relies on persistent state tracking (Task/Todo systems), context preservation (Session IDs and Handoffs), and autonomous problem-solving (Failure Recovery protocols). By enforcing these disciplines, the system ensures that high-complexity software engineering tasks can be completed end-to-end with minimal disruption, even in the face of technical failures or context window limitations.