How to Enable Safe Resume for Interrupted Turns in Apache Maka

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 (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:

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:

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

Or use the dedicated resume command:

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:

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 (line 884), the host reads the environment variable to determine whether to initialize the safe-resume context:

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, 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, which coordinates the repair flow when the flag is active.

As noted in 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, packages/runtime/src/runtime-resume.ts, and 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 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 (line 823) and the README (line 222) also reference this gating mechanism.

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