Environment Variables to Enable Crash Recovery in Apache Maka

Set MAKA_RUNTIME_SAFE_BOUNDARY_RESUME=1 to enable the safe-resume feature for production workloads, and use the MAKA_RUNTIME_RESUME_* variable family to orchestrate deterministic crash-recovery tests.

Apache Maka’s deterministic execution engine relies on specific environment variables to activate crash recovery mechanisms in both production deployments and automated test harnesses. Understanding these variables is essential for operators enabling fault tolerance and developers verifying resume behavior across unexpected termination scenarios. The runtime host evaluates these flags during execution composition to decide whether to surface resume options in the Desktop UI and CLI.

Core Environment Variables for Crash Recovery

Maka distinguishes between production safe-resume functionality and test harness crash simulation through two distinct categories of environment variables.

Production Safe-Resume Flag

The primary environment variable to enable crash recovery in Apache Maka is MAKA_RUNTIME_SAFE_BOUNDARY_RESUME. When set to 1, this flag activates the safe-resume capability that powers the Desktop "Safe resume" button, the CLI /resume command, and automatic startup resume.

Without this flag, the runtime host disables crash recovery entirely. According to the source code in packages/runtime-host/src/server/execution-composition.ts at line 928, the runtime host checks this variable when creating the execution composition to determine whether to expose resume functionality. The architecture guide at docs/architecture/runtime-resume-architecture.md (line 846) documents this behavior as the gatekeeper for all user-visible resume features.

# Enable safe-resume for desktop or CLI sessions

export MAKA_RUNTIME_SAFE_BOUNDARY_RESUME=1

Test Harness Crash Simulation Variables

For testing crash recovery deterministically, Maka uses a family of MAKA_RUNTIME_RESUME_* variables defined in packages/runtime/src/__tests__/runtime-resume-crash.test.ts. These variables allow the test harness to spawn child processes that simulate crashes after writing committed event prefixes.

The complete set includes:

• MAKA_RUNTIME_RESUME_CRASH_CHILD=1 — Signals the child process to simulate a crash after writing a committed prefix (lines 40–41).
• MAKA_RUNTIME_RESUME_WORKSPACE — Specifies the temporary workspace path where the child writes runtime events (lines 57–58).
• MAKA_RUNTIME_RESUME_SESSION — Provides the session identifier whose events require recovery (lines 24–25).
• MAKA_RUNTIME_RESUME_RUN — Identifies the specific run (invocation) being recovered (lines 25–26).
• MAKA_RUNTIME_RESUME_FINALLY_MARKER — Defines a file path the child writes in its finally block; the parent verifies this file does not exist after killing the child, confirming the crash occurred before finalization (lines 26–27).
• MAKA_RUNTIME_RESUME_EVENTS — Base-64-encoded JSON array of RuntimeEvent objects the child appends before crashing (lines 60–63).

Practical Implementation

To enable crash recovery in production, set the safe-boundary flag before launching the runtime host:

// Enable safe-resume for a desktop or CLI session
process.env.MAKA_RUNTIME_SAFE_BOUNDARY_RESUME = '1';

In test environments, the harness spawns a child process with the crash-simulation variables:

// In a test harness – spawn a child that will crash after committing events
const child = spawn(process.execPath, [testFileUrl], {
  env: {
    ...process.env,
    MAKA_RUNTIME_RESUME_CRASH_CHILD: '1',
    MAKA_RUNTIME_RESUME_WORKSPACE: workspaceRoot,
    MAKA_RUNTIME_RESUME_SESSION: sessionId,
    MAKA_RUNTIME_RESUME_RUN: runId,
    MAKA_RUNTIME_RESUME_FINALLY_MARKER: markerPath,
    MAKA_RUNTIME_RESUME_EVENTS: Buffer.from(JSON.stringify(events), 'utf8')
      .toString('base64'),
  },
});

Inside the child process, the runtime checks for MAKA_RUNTIME_RESUME_CRASH_CHILD to enter the crash simulation branch. The child writes events to the durable runtime.sqlite store using the provided workspace, session, and run identifiers, then awaits termination:

// Inside the crashing child (runtime-resume-crash.test.ts)
if (process.env.MAKA_RUNTIME_RESUME_CRASH_CHILD === '1') {
  const workspace = requiredEnv('MAKA_RUNTIME_RESUME_WORKSPACE');
  const session = requiredEnv('MAKA_RUNTIME_RESUME_SESSION');
  const run = requiredEnv('MAKA_RUNTIME_RESUME_RUN');
  const events = JSON.parse(
    Buffer.from(requiredEnv('MAKA_RUNTIME_RESUME_EVENTS'), 'base64').toString('utf8')
  );
  const store = createWorkspaceRuntimeStore(workspace);
  for (const ev of events) {
    await store.appendRuntimeEvent(session, run, ev);
  }
  // Signal readiness, then wait to be SIGKILL-ed
  process.stdout.write('READY\n');
  await new Promise(() => {}); // keep alive until parent kills us
}

After the parent kills the child, Maka reopens the durable store, verifies that only the committed prefix survived, and rebuilds a deterministic ResumePlan to continue execution.

Summary

• MAKA_RUNTIME_SAFE_BOUNDARY_RESUME=1 is the single environment variable required to enable crash recovery in production Apache Maka deployments, activating Desktop and CLI resume features.
• Six test-specific variables (MAKA_RUNTIME_RESUME_CRASH_CHILD, MAKA_RUNTIME_RESUME_WORKSPACE, MAKA_RUNTIME_RESUME_SESSION, MAKA_RUNTIME_RESUME_RUN, MAKA_RUNTIME_RESUME_FINALLY_MARKER, and MAKA_RUNTIME_RESUME_EVENTS) orchestrate deterministic crash simulation in the test harness defined in packages/runtime/src/__tests__/runtime-resume-crash.test.ts.
• The runtime host evaluates these flags during execution composition, as implemented in packages/runtime-host/src/server/execution-composition.ts, to decide whether to offer safe-resume options.
• These variables enable Maka to detect crash scenarios, provide full context to child processes, and verify that committed event prefixes survive unexpected termination.

Frequently Asked Questions

What is the minimum configuration to enable crash recovery in Apache Maka?

Set the environment variable MAKA_RUNTIME_SAFE_BOUNDARY_RESUME=1 before starting the runtime host. This single flag enables the safe-resume feature in both the Desktop interface and CLI, allowing users to resume executions from the last committed boundary after an unexpected crash.

How does Apache Maka test crash recovery deterministically?

The test harness uses MAKA_RUNTIME_RESUME_CRASH_CHILD=1 to spawn child processes that intentionally crash after writing specific events. The harness passes workspace paths, session identifiers, and base64-encoded event arrays via MAKA_RUNTIME_RESUME_WORKSPACE, MAKA_RUNTIME_RESUME_SESSION, MAKA_RUNTIME_RESUME_RUN, and MAKA_RUNTIME_RESUME_EVENTS. After killing the child, the parent verifies that MAKA_RUNTIME_RESUME_FINALLY_MARKER was never written, confirming the crash occurred before finalization.

Where does Apache Maka check for the safe-resume environment variable?

The runtime host checks for MAKA_RUNTIME_SAFE_BOUNDARY_RESUME in packages/runtime-host/src/server/execution-composition.ts at line 928 when constructing the execution composition. This check determines whether to expose resume commands in the UI and CLI, as documented in the architecture guide at docs/architecture/runtime-resume-architecture.md.

What happens if MAKA_RUNTIME_SAFE_BOUNDARY_RESUME is not set?

Without this environment variable, Apache Maka disables crash recovery entirely. The runtime host will not offer the "Safe resume" button in the Desktop application, the /resume command will be unavailable in the CLI, and automatic startup resume will not function, even if durable runtime stores contain recoverable event data.

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