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

> Learn how to enable and use Apache Maka's crash recovery and resume features. Explore its immutable RuntimeEvent log and safe-boundary checkpoints for state reconstruction after termination.

- Repository: [The Apache Software Foundation/maka](https://github.com/apache/maka)
- Tags: how-to-guide
- Published: 2026-09-04

---

**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`](https://github.com/apache/maka/blob/main/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:

```bash
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`](https://github.com/apache/maka/blob/main/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:

```typescript
// 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`](https://github.com/apache/maka/blob/main/packages/runtime-host/src/protocol/operations.ts) govern this exchange.

### Executing the Resume

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

```typescript
// 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:

```bash

# 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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/.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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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.