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

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:

// 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) 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 demonstrates this propagation:

// 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.

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, while the recovery logic that consumes these values resides in packages/runtime/src/session-manager.ts.

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