How to Enable Resuming an Interrupted Turn in Apache Maka

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:

export MAKA_RUNTIME_SAFE_BOUNDARY_RESUME=1   # Bash, zsh, etc.

On Windows PowerShell:

$env:MAKA_RUNTIME_SAFE_BOUNDARY_RESUME = "1"

According to the source code in 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:

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

This IPC call routes to 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.

Basic Resume Commands

To resume the default session:

maka /resume

To target a specific session:

maka /resume --session mySessionId

Implementation Details

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

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 handles safety validation:

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 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 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.
• 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.
• 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, 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 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.

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