# How Maka Attributes Sandbox Boundary Restarts to Specific Runs: Session Recovery Explained

> Maka attributes sandbox boundary restarts to specific runs by persisting host_restarted reason in session store. Learn how this recovery process tags affected turns and invocations.

- Repository: [The Apache Software Foundation/maka](https://github.com/apache/maka)
- Tags: internals
- Published: 2026-09-08

---

**Maka attributes sandbox boundary restarts to specific runs by persisting the closure reason `host_restarted` in the durable session store, then mapping this reason to the error class `sandbox_boundary_closed_by_restart` during recovery to tag the affected turn and invocation.**

When a host process restarts while a sandbox-boundary request remains pending, the Apache Maka framework must reliably trace that interruption back to the exact run that was awaiting a boundary decision. The system accomplishes this through a durable persistence layer and a deterministic recovery protocol that transforms low-level closure reasons into user-facing error classifications.

## Persisting the Closure Reason in the Session Store

When a restart occurs during an active sandbox-boundary request, Maka settles the pending request row in the session store with a specific closure reason. This durable record ensures that the interruption survives the process restart and remains available for subsequent recovery logic.

The closure reason constant is defined in [`packages/core/src/sandbox-boundary.ts`](https://github.com/apache/maka/blob/main/packages/core/src/sandbox-boundary.ts):

```typescript
// packages/core/src/sandbox-boundary.ts
export const SANDBOX_BOUNDARY_RESTART_CLOSURE_CLASS = 'sandbox_boundary_closed_by_restart';
export const SANDBOX_BOUNDARY_HOST_RESTART_CLOSURE_REASON = 'host_restarted';

```

During a restart, any pending sandbox-boundary request receives the `outcomeReason` value of `host_restored`. This internal marker serves as the definitive signal that the session was interrupted by a host restart rather than a policy denial or timeout.

## Recovery and Attribution Logic in SessionManager

Upon restarting, the runtime executes `SessionManager.recoverInterruptedSessions()` (implemented in [`packages/runtime/src/session-manager.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/session-manager.ts)) to scan for interrupted sessions. This method queries the durable request rows and identifies candidates where the `status` is `denied` and the `outcomeReason` exactly matches `host_restarted`.

When the recovery logic detects this combination, it treats the associated turn as a failure and initiates the attribution process. The mapping from the internal closure reason to the public error class occurs at this stage, ensuring that downstream consumers receive a stable, semantic identifier rather than an implementation-specific reason string.

## Tagging Specific Runs, Turns, and Invocations

To complete the attribution, Maka assigns the failure class to two specific entities that represent the run's execution context:

- The **turn** object receives the error class via the `turn?.errorClass` property
- The **invocation's terminal event** receives the classification via `runtimeInvocationFailureClass`

This dual assignment ensures that both the conversational context (turn) and the runtime execution record (invocation) consistently reflect the restart failure. The value assigned in both cases is the constant `sandbox_boundary_closed_by_restart`, creating a deterministic link between the restart event and the specific run that was blocked awaiting a boundary decision.

The integration test in [`packages/runtime/src/__tests__/sandbox-boundary-restart-recovery.test.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/__tests__/sandbox-boundary-restart-recovery.test.ts) demonstrates this propagation:

```typescript
// packages/runtime/src/__tests__/sandbox-boundary-restart-recovery.test.ts
await withStores(root, async (stores) => {
  await manager(stores).recoverInterruptedSessions();   // Recovery pass
});

const [turn] = await manager(stores).listTurns(session.id);
assert.equal(turn?.errorClass, 'sandbox_boundary_closed_by_restart'); // Attribution

const [invocation] = await runtimeEvents.listSessionInvocations(session.id);
assert.equal(
  invocation && runtimeInvocationFailureClass(invocation),
  'sandbox_boundary_closed_by_restart',
);

```

## Idempotency Guarantees

The recovery mechanism is designed to be idempotent. If the host restarts multiple times, the `recoverInterruptedSessions()` method re-reads the same durable closure records without creating duplicate terminal states. As demonstrated in lines 31–45 of the test suite, subsequent recovery passes detect that the error class has already been assigned and leave the turn and invocation unchanged, preventing spurious duplicate error entries.

## Summary

- **Durable persistence**: Pending sandbox-boundary requests are settled with `host_restarted` in the session store upon process restart.
- **Semantic mapping**: The internal reason `host_restarted` maps to the public error class `sandbox_boundary_closed_by_restart` during recovery.
- **Precise attribution**: `SessionManager.recoverInterruptedSessions()` tags both the **turn** (`errorClass`) and the **invocation** (`runtimeInvocationFailureClass`) with the restart failure class.
- **Idempotent recovery**: Multiple restarts do not create duplicate terminal events; the system reliably maintains the original attribution.

## Frequently Asked Questions

### What error class does Maka use for sandbox boundary restarts?

Maka exposes the error class `sandbox_boundary_closed_by_restart` to user-facing layers. This constant is defined as `SANDBOX_BOUNDARY_RESTART_CLOSURE_CLASS` in [`packages/core/src/sandbox-boundary.ts`](https://github.com/apache/maka/blob/main/packages/core/src/sandbox-boundary.ts).

### How does Maka determine that a restart caused a sandbox boundary failure?

During recovery, `SessionManager.recoverInterruptedSessions()` checks for request rows with `status: 'denied'` and `outcomeReason: 'host_restarted'`. This specific combination indicates the request was pending when the host process terminated.

### What happens to the turn when a host restarts during a sandbox boundary request?

The turn's `errorClass` property is set to `sandbox_boundary_closed_by_restart`, and the associated invocation receives the same classification via `runtimeInvocationFailureClass`. This permanently attributes the restart to that specific execution context.

### Where is the restart closure reason defined in the codebase?

The closure reason string `host_restarted` and the corresponding error class are defined in [`packages/core/src/sandbox-boundary.ts`](https://github.com/apache/maka/blob/main/packages/core/src/sandbox-boundary.ts), while the recovery logic that consumes these values resides in [`packages/runtime/src/session-manager.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/session-manager.ts).