# How to Enable Safe Resume for Interrupted Turns in Apache Maka

> Enable safe resume for interrupted turns in Apache Maka by setting MAKA_RUNTIME_SAFE_BOUNDARY_RESUME=1. Seamlessly continue execution from the last safe boundary after interruptions.

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

---

**Set the environment variable `MAKA_RUNTIME_SAFE_BOUNDARY_RESUME=1` before launching Maka to allow the system to repair interrupted turns and continue execution from the last safe boundary.**

Apache Maka treats every model-tool interaction as an immutable **RuntimeEvent**, creating a durable log that survives process crashes. When a turn is interrupted—such as when a tool hangs or the process terminates unexpectedly—the system defaults to preserving the crash facts without attempting continuation. To enable the **safe-boundary resume** feature that permits repairing and continuing the interrupted turn, you must configure a specific environment variable before starting the Desktop UI, CLI, or Runtime Host.

## Understanding Safe-Boundary Resume Architecture

Maka's resume capability depends on the **Runtime Host** and **session manager** evaluating whether a crashed session can be safely continued. According to the architecture documentation in [`docs/architecture/runtime-resume-architecture.md`](https://github.com/apache/maka/blob/main/docs/architecture/runtime-resume-architecture.md) (line 823), the feature is explicitly gated by the `MAKA_RUNTIME_SAFE_BOUNDARY_RESUME` flag to prevent accidental continuation of potentially corrupted states.

When enabled, the system performs three distinct actions:

- **Desktop UI**: Displays a **"Safe resume"** banner for interrupted sessions, allowing users to visually identify recoverable states.
- **CLI Interface**: Activates the `maka /resume` command and the `--resume` flag on `maka run`, enabling explicit programmatic continuation.
- **Runtime Host**: On startup, automatically attempts to repair and resume the latest interrupted run by replaying RuntimeEvents from the last safe boundary.

## Configuring the Environment Variable

The configuration requires setting `MAKA_RUNTIME_SAFE_BOUNDARY_RESUME` to `1` in the environment where Maka executes. This variable does not modify durable facts; it merely signals permission to continue after safety checks pass.

### Desktop Development Mode

For local development with the Desktop UI, export the variable before launching the dev server:

```bash
export MAKA_RUNTIME_SAFE_BOUNDARY_RESUME=1
npm run dev

```

### CLI Usage

When using the Maka CLI, set the variable to enable resume functionality for specific commands:

```bash
export MAKA_RUNTIME_SAFE_BOUNDARY_RESUME=1
maka run "Summarize the repository" --resume

```

Or use the dedicated resume command:

```bash
maka /resume

```

### Runtime Host Permanent Configuration

To enable safe resume automatically for the Runtime Host on every system startup, add the export to your shell configuration:

```bash
echo 'export MAKA_RUNTIME_SAFE_BOUNDARY_RESUME=1' >> ~/.bashrc

```

## Implementation Details in Source Code

The safe-boundary resume logic is implemented across several core packages in the Apache Maka repository.

In [`packages/runtime-host/src/server/execution-composition.ts`](https://github.com/apache/maka/blob/main/packages/runtime-host/src/server/execution-composition.ts) (line 884), the host reads the environment variable to determine whether to initialize the safe-resume context:

```typescript
const safeResume = process.env.MAKA_RUNTIME_SAFE_BOUNDARY_RESUME === '1';
if (safeResume) {
  console.log('Safe‑boundary resume enabled – allowing continuation.');
}

```

The core resume planning and safety validation occurs in [`packages/runtime/src/runtime-resume.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/runtime-resume.ts), which evaluates the immutable RuntimeEvent log to determine if the interrupted turn meets continuity criteria. The orchestration between the Desktop UI and CLI sessions is managed by [`packages/runtime/src/session-manager.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/session-manager.ts), which coordinates the repair flow when the flag is active.

As noted in [`README.md`](https://github.com/apache/maka/blob/main/README.md) (line 222), the feature defaults to **off** to prevent unintended behavior in production environments where deterministic restart might be preferred over stateful continuation.

## Verifying the Configuration

To confirm that safe resume is active:

1. Start Maka with the environment variable set
2. Check for the **"Safe resume"** banner in the Desktop UI when loading an interrupted session
3. Verify that `maka /resume` responds with available interrupted runs rather than a disabled message

If the variable is unset, Maka will record crash facts but display only the interrupted state without offering continuation options.

## Summary

- **Safe-boundary resume** allows Apache Maka to continue interrupted turns rather than abandoning them
- Enable the feature by setting `MAKA_RUNTIME_SAFE_BOUNDARY_RESUME=1` before launching any Maka component
- The flag activates Desktop UI banners, CLI resume commands, and automatic Runtime Host repair without modifying stored RuntimeEvents
- Core implementation resides in [`packages/runtime-host/src/server/execution-composition.ts`](https://github.com/apache/maka/blob/main/packages/runtime-host/src/server/execution-composition.ts), [`packages/runtime/src/runtime-resume.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/runtime-resume.ts), and [`packages/runtime/src/session-manager.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/session-manager.ts)

## Frequently Asked Questions

### What happens if I don't enable safe-boundary resume?

Without setting `MAKA_RUNTIME_SAFE_BOUNDARY_RESUME=1`, Maka will detect and record the interrupted state but will not attempt to continue the turn. The UI will display the interruption status, and you must manually restart the workflow from the beginning rather than repairing the existing session.

### Does enabling safe resume delete or modify previous run data?

No. The environment variable only permits the system to start a new continuation after passing safety checks. It does not alter or delete any durable RuntimeEvents or facts stored from previous executions. The original interrupted run remains intact in the immutable log.

### Can I enable safe resume for specific sessions only?

Yes. Because the feature is controlled by an environment variable, you can enable it for individual terminal sessions by exporting `MAKA_RUNTIME_SAFE_BOUNDARY_RESUME=1` only when needed. For permanent activation across all sessions, add the export to your shell profile or system environment configuration.

### Where does Maka check the environment variable in the source code?

The Runtime Host checks this variable in [`packages/runtime-host/src/server/execution-composition.ts`](https://github.com/apache/maka/blob/main/packages/runtime-host/src/server/execution-composition.ts) at line 884, where it validates `process.env.MAKA_RUNTIME_SAFE_BOUNDARY_RESUME === '1'` to conditionally enable the safe-resume context. The architecture documentation in [`docs/architecture/runtime-resume-architecture.md`](https://github.com/apache/maka/blob/main/docs/architecture/runtime-resume-architecture.md) (line 823) and the README (line 222) also reference this gating mechanism.