# How to Enable Resuming an Interrupted Turn in Apache Maka

> Enable Maka's interrupted turn resume feature by setting MAKA_RUNTIME_SAFE_BOUNDARY_RESUME=1. Restart Maka to use UI, CLI, or API for seamless continuation.

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

---

**Set the environment variable `MAKA_RUNTIME_SAFE_BOUNDARY_RESUME=1` and restart Maka to enable safe resumption of interrupted turns via the Desktop UI banner, CLI `/resume` command, or programmatic API.**

The ability to enable resuming an interrupted turn in Apache Maka prevents wasted tokens and lost progress when crashes or unexpected shutdowns occur mid-conversation. By default, this safety feature is disabled to prevent accidental model invocations, but once activated, the runtime can continue from the last committed state rather than re-executing completed tool calls.

## Configure the Safe-Boundary Resume Feature

Enabling resumption requires activating the safe-boundary flag and restarting the application so the `SessionManager` can detect interrupted Runs.

### Set the Environment Variable

The `MAKA_RUNTIME_SAFE_BOUNDARY_RESUME` flag controls whether the runtime host permits planning continuations for interrupted sessions. Export this variable before launching Maka:

```bash
export MAKA_RUNTIME_SAFE_BOUNDARY_RESUME=1   # Bash, zsh, etc.

```

On Windows PowerShell:

```powershell
$env:MAKA_RUNTIME_SAFE_BOUNDARY_RESUME = "1"

```

According to the source code in [`packages/runtime-host/src/server/execution-composition.ts`](https://github.com/apache/maka/blob/main/packages/runtime-host/src/server/execution-composition.ts), this flag is read during host initialization to determine whether safe-boundary resume capabilities should be registered.

### Restart the Application

After setting the variable, restart the Desktop app, CLI process, or runtime-host server. During startup, the `SessionManager` automatically scans for Runs left in a `running` state and prepares safe continuation plans when the flag is active.

## Resume an Interrupted Turn in the Desktop UI

When the feature is enabled and Maka detects an interrupted session, a banner appears in the Desktop interface. Clicking **Safe resume** triggers the continuation flow through the IPC bridge.

The renderer process invokes the resume method via [`apps/desktop/src/renderer/use-shell-resume.ts`](https://github.com/apache/maka/blob/main/apps/desktop/src/renderer/use-shell-resume.ts):

```typescript
const result = await window.maka.sessions.resumeLatest(sessionId);

```

This IPC call routes to [`apps/desktop/src/main/runtime-host-session-execution-ipc-main.ts`](https://github.com/apache/maka/blob/main/apps/desktop/src/main/runtime-host-session-execution-ipc-main.ts), which delegates to `runtimeHost.resumeLatest(sessionId)`. The host creates a new Run that preserves all previously committed `RuntimeEvent` facts while skipping already-completed tool executions.

## Resume via CLI or TUI

For terminal-based workflows, Apache Maka exposes the `/resume` command through the CLI driver defined in [`packages/cli/src/runtime-host-run-command.ts`](https://github.com/apache/maka/blob/main/packages/cli/src/runtime-host-run-command.ts).

### Basic Resume Commands

To resume the default session:

```bash
maka /resume

```

To target a specific session:

```bash
maka /resume --session mySessionId

```

### Implementation Details

The CLI driver checks the environment flag before streaming resumed events:

```typescript
async resumeLatest(sessionId: string): Promise<AsyncIterable<SessionEvent> | null> {
  const plan = await this.#planner.planLatestAuthoritativeSafeBoundaryContinuation(sessionId);
  return plan.disposition === 'ready' ? this.#driver.resumeLatest() : null;
}

```

If the flag is disabled, the planner returns a disposition other than `'ready'`, and the command exits without creating a new Run or invoking the model.

## Programmatic Resume with the SessionManager API

For custom integrations, invoke the resume logic directly through the `SessionManager` API. The core implementation in [`packages/runtime/src/session-manager.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/session-manager.ts) handles safety validation:

```typescript
if (process.env.MAKA_RUNTIME_SAFE_BOUNDARY_RESUME === '1') {
  const plan = await this.planLatestAuthoritativeSafeBoundaryContinuation(sessionId);
  if (plan.disposition === 'ready') {
    await this.runtimeKernel.resumeSafeBoundaryContinuation(plan);
  }
}

```

The companion logic in [`packages/runtime/src/runtime-resume.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/runtime-resume.ts) performs the actual repair of old Runs and validates the continuation plan against the authoritative event history before the kernel resumes execution.

## Error Handling When Disabled

If you attempt to resume without setting the environment variable, Apache Maka throws a `SafeBoundaryResumeParkedError`. The Desktop UI displays a notice such as "Safe resume is disabled," while the CLI terminates without streaming events. This prevents unintended token consumption when the model might be invoked unexpectedly.

The architecture documentation in [`docs/architecture/runtime-resume-architecture.md`](https://github.com/apache/maka/blob/main/docs/architecture/runtime-resume-architecture.md) details the planner, resolver, and safety check phases that enforce this behavior when the flag is inactive.

## Summary

- **Enable the feature** by setting `MAKA_RUNTIME_SAFE_BOUNDARY_RESUME=1` in your environment variables before starting Apache Maka.
- **Desktop users** can click the interrupted-turn banner to trigger `sessions:resumeLatest` via the IPC bridge in [`apps/desktop/src/renderer/use-shell-resume.ts`](https://github.com/apache/maka/blob/main/apps/desktop/src/renderer/use-shell-resume.ts).
- **CLI users** run `maka /resume` or `maka /resume --session <id>` to continue from the last committed state without redundant tool execution.
- **Programmatic access** is available through `SessionManager.planLatestAuthoritativeSafeBoundaryContinuation()` and `runtimeKernel.resumeSafeBoundaryContinuation()` in [`packages/runtime/src/session-manager.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/session-manager.ts).
- **Safety enforcement**: Without the flag, resumption attempts fail with `SafeBoundaryResumeParkedError` to prevent unintended model token usage.

## Frequently Asked Questions

### What happens if I try to resume without setting the environment variable?

Apache Maka will block the operation and return a `SafeBoundaryResumeParkedError`. The Desktop UI will display a notice stating that safe resume is disabled, while the CLI command will exit without streaming events. This safety mechanism prevents accidental token consumption when you might not expect the model to be invoked.

### Does resuming re-execute tool calls that already completed?

No. The safe-boundary resume feature creates a new Run that preserves all committed `RuntimeEvent` facts from the interrupted session. According to the implementation in [`packages/runtime/src/runtime-resume.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/runtime-resume.ts), the planner validates the existing event history and only schedules continuation from the last safe boundary, avoiding redundant tool executions and preserving idempotency.

### Can I resume a session programmatically from my own Node.js application?

Yes. Import the `SessionManager` from [`packages/runtime/src/session-manager.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/session-manager.ts) and call `planLatestAuthoritativeSafeBoundaryContinuation(sessionId)` followed by `runtimeKernel.resumeSafeBoundaryContinuation(plan)`. Ensure your process has `MAKA_RUNTIME_SAFE_BOUNDARY_RESUME=1` set, as the kernel checks this flag before authorizing the continuation to prevent unauthorized model calls.

### Is there a performance cost to leaving the resume feature enabled?

The primary cost is token usage when resumption actually occurs, as the model must process the conversation context to continue. However, simply having the flag enabled incurs minimal overhead during normal operation. The `SessionManager` performs lightweight state checks during startup to detect interrupted Runs, but this impact is negligible unless a resume is actively triggered.