How to Enable and Use Crash Recovery and Resume Features in Apache Maka

Apache Maka provides crash recovery and session resume capabilities through an immutable RuntimeEvent log and safe-boundary checkpoints that allow applications to reconstruct state after unexpected process termination.

Apache Maka is an open-source AI agent runtime that persists every model message, tool invocation, and permission decision to a durable SQLite log. By leveraging this append-only event store, developers can enable crash recovery and resume features in Apache Maka to restore interrupted sessions without losing progress. The system uses safe-boundary markers to identify consistent states from which execution can safely continue.

Enabling Safe-Boundary Resume

Before invoking recovery APIs, developers must opt into the resume capability via an environment variable. According to the Apache Maka source code in apps/desktop/src/main/runtime-host-boot.ts, safe-boundary resume is disabled by default to prevent unintended behavior in production environments.

Set the following environment variable to enable the feature:

export MAKA_RUNTIME_SAFE_BOUNDARY_RESUME=1

Once enabled, the RuntimeHost exposes resume commands through the desktop UI, CLI /resume command, and automatic startup resume functionality. This toggle activates the crash-boundary detection logic that monitors for unfinished turn boundaries when a process exits unexpectedly.

How Crash Recovery Works Under the Hood

The recovery mechanism relies on three core components implemented in the Maka runtime:

• RuntimeEvent Log: Every operation is recorded as an immutable event in runtime.sqlite (located in the local data directory). This append-only log serves as the source of truth for state reconstruction.
• Safe-Boundary Markers: When a turn completes successfully, the system writes a safe-boundary record to the log. These markers designate valid resumption points that maintain model context integrity.
• Checkpoint Recovery: On restart, the RuntimeHost loads the latest safe-boundary checkpoint, validates the stored model-context hash, and replays subsequent events to restore the exact session state.

If the process crashes during an active turn, the host detects the unfinished boundary in runtime.sqlite and prepares a resume plan using the persisted log entries.

Implementing Resume Functionality

Applications interact with the recovery system through the preload bridge exposed in apps/desktop/src/preload/preload.ts. The implementation follows a two-phase pattern: planning and execution.

Requesting a Resume Plan

Before resuming, query the RuntimeHost to validate that a safe resume is possible. The resumePlan() function accepts session, execution, and turn identifiers to locate the appropriate boundary:

// Request a resume plan from the preload bridge
const plan = await window.maka.preload.resumePlan(
  "session-123",    // Session ID
  "execution-abc",  // Execution ID  
  "turn-7"          // Target turn ID for resumption
);

This method communicates with the host process via invokeSessionRuntimeHost and returns a plan containing the exact turn that can be replayed, along with required model context hashes. The protocol verbs turn.resume.query and turn.resume.start defined in packages/runtime-host/src/protocol/operations.ts govern this exchange.

Executing the Resume

Once validated, trigger the actual resumption using the resume() method:

// Execute the resume for the specified session
await window.maka.preload.resume("session-123");

The RuntimeHost re-instantiates the model, re-issues stored tool calls, and continues the turn from the safe boundary. If the model does not support the required resume head or resume boundary protocols, the operation fails gracefully with a user-facing notification.

Command-Line Interface

For CLI and background worker scenarios, Maka exposes the resume capability through the /resume command:

# Inside a Maka workspace directory

maka /resume

This command asks the host to resume the latest safe turn without requiring manual session ID specification.

Handling Resume Failures and UI Feedback

Not all crashes permit automatic resumption. The UI layer in packages/ui/src/runtime-resume-copy.ts translates various failure conditions into localized toast messages. Common failure scenarios include:

• Missing candidate: No valid safe-boundary exists in the log.
• Unsupported model: The target model lacks resume head/boundary capabilities.
• Cycle detection: The resume plan would create a circular dependency in the execution graph.

When the RuntimeHost rejects a resume request, the preload bridge surfaces these error codes to the UI, which formats them using the localization keys defined in the runtime-resume-copy module.

Testing Crash Recovery

Apache Maka includes comprehensive test coverage for crash scenarios. The test suite in packages/storage/src/sqlite-runtime-crash.test.ts forces real process crashes to verify snapshot loading and state restoration. Additionally, the GitHub Actions workflow defined in .github/workflows/windows-recovery.yml runs a matrix of crash-recovery tests on Windows environments to ensure cross-platform reliability.

These tests simulate unexpected termination during active turns, verify that runtime.sqlite maintains consistency, and confirm that the resume path restores the exact pre-crash state without data loss.

Summary

• Enable recovery by setting MAKA_RUNTIME_SAFE_BOUNDARY_RESUME=1 before starting the RuntimeHost.
• Architecture foundation relies on immutable RuntimeEvent logs stored in runtime.sqlite with safe-boundary checkpoints.
• Implementation pattern requires calling resumePlan() to validate resumption feasibility, followed by resume() to reconstruct state.
• CLI access is available via the /resume command for non-desktop environments.
• Failure handling is managed through packages/ui/src/runtime-resume-copy.ts, which provides localized explanations when resumption is impossible.
• Verification is supported by automated crash-recovery tests in sqlite-runtime-crash.test.ts and Windows-specific CI workflows.

Frequently Asked Questions

What happens if I don't enable the safe-boundary environment variable?

Without MAKA_RUNTIME_SAFE_BOUNDARY_RESUME=1, the RuntimeHost does not expose resume commands or maintain the necessary checkpoint metadata. While the RuntimeEvent log still records events to runtime.sqlite, the system treats every termination as final and will not attempt to reconstruct interrupted sessions on restart.

Can I resume any turn in the session history?

No. Resumption is only possible at safe-boundary records—specific points where a turn completed successfully and the model context was validated. The resumePlan() function checks packages/runtime-host/src/protocol/operations.ts to ensure the target turn supports the resume protocol before allowing execution to continue.

Why does my resume fail with an "unsupported model" error?

This occurs when the AI model provider does not implement the required resume head or resume boundary interfaces. According to the implementation in apps/desktop/src/preload/preload.ts, the RuntimeHost validates model capabilities before reconstructing the session. If the model cannot accept the stored context hash or replay tool calls deterministically, the UI displays a localized message from packages/ui/src/runtime-resume-copy.ts explaining the incompatibility.

How does Maka ensure data integrity during a crash?

The system uses SQLite transactions to write RuntimeEvents durably to runtime.sqlite before acknowledging operations. The safe-boundary mechanism in runtime-host-boot.ts ensures that only consistent states are marked as resumption points. During recovery, the host validates context hashes against the model state before replaying events, preventing corruption of the execution graph.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}