Session Status Lifecycles in Apache Maka: Complete Technical Guide

Apache Maka manages conversational sessions through five distinct statuses—active, running, waiting_for_user, blocked, and aborted—orchestrated via a durable, append-only state machine centered in the Session Manager.

The session status lifecycle governs execution flow in Apache Maka, determining when AI turns run, pause for input, or terminate. These states are defined in packages/core/src/session.ts as the SESSION_STATUSES enumeration and enforced by the SessionManager class in the runtime package.

The Five Canonical Session Statuses

Maka models every session as a durable record that transitions through exactly five statuses. Each status represents a specific execution phase with defined entry and exit conditions.

active

The active status represents an idle session that exists but has no turn currently executing. This is the default baseline state for newly created sessions.

Typical transitions include moving to running when the Runtime Host launches a turn, or to aborted if the user cancels before any execution begins. When a turn finishes successfully without blocks, the session returns to active.

running

The running status indicates that a turn is actively executing within the Runtime Host. During this phase, the model generates output or invokes tools.

Transitions from running include:

• waiting_for_user when a tool call requires explicit user confirmation
• blocked if a permission or authorization problem stops progress
• active after the turn completes successfully

waiting_for_user

The waiting_for_user status pauses execution because a tool call or sandbox boundary request requires explicit user approval. This state creates a checkpoint where the session cannot proceed without human intervention.

Once the user responds, the session transitions back to running (if approved), moves to blocked (if denied), or shifts to aborted if the user cancels the entire session.

blocked

The blocked status indicates the session cannot continue due to a specific obstruction stored in the blockedReason field of the session header. According to packages/core/src/session.ts, valid SessionBlockedReason values include auth, permission_required, and tool_failed.

Sessions exit blocked by returning to running after the obstruction clears (such as user re-authorization), or transition to aborted if the user terminates the session while blocked.

aborted

The aborted status represents permanent termination. Once entered, the session becomes read-only and accepts no further turns. This final state triggers on explicit user cancellation or unrecoverable runtime errors.

Session Lifecycle Execution Flow

The Session Manager in packages/runtime/src/session-manager.ts orchestrates transitions through the setSessionStatus() method. The lifecycle follows this deterministic sequence:

1. Creation: New sessions initialize with status active
2. Execution Start: SessionManager.setSessionStatus(sessionId, 'running') invokes when the Runtime launches the first turn
3. Interaction Point: Tool calls requiring approval trigger waiting_for_user
4. Failure Handling: Permission denials or tool errors set blocked with a populated blockedReason
5. Completion: Successful turn execution returns the session to active
6. Termination: Any explicit cancel or unrecoverable error sets aborted, making the session read-only

Programmatic Status Management

Updating Session Status in the Runtime

The Session Manager provides the primary API for persisting status changes. All modifications append to the session's immutable history:

// In SessionManager (packages/runtime/src/session-manager.ts)
await this.setSessionStatus(sessionId, 'running');           // start execution
await this.setSessionStatus(sessionId, 'waiting_for_user'); // pause for confirmation
await this.setSessionStatus(sessionId, 'blocked', 'auth');   // block due to auth issue
await this.setSessionStatus(sessionId, 'active');           // turn completed
await this.setSessionStatus(sessionId, 'aborted');          // user aborts

Validating Session Status in Client Code

The core session module exports type guards for safe status checking:

import { isSessionStatus, SessionStatus } from '@maka/core/session';

function handleStatus(status: unknown) {
  if (!isSessionStatus(status)) {
    throw new Error('Invalid session status');
  }

  switch (status) {
    case 'active':
      console.log('Session is idle');
      break;
    case 'running':
      console.log('Session is executing a turn');
      break;
    case 'waiting_for_user':
      console.log('Awaiting user confirmation');
      break;
    case 'blocked':
      console.log('Session is blocked – inspect blockedReason');
      break;
    case 'aborted':
      console.log('Session has been terminated');
      break;
  }
}

Rendering Status in the UI Layer

The presentation layer maps raw statuses to human-readable interfaces via packages/ui/src/session-status-presentation.ts:

import { presentSessionStatus } from '@maka/ui/session-status-presentation';
import type { SessionSummary } from '@maka/core/session';

export const SessionStatusBadge = ({ summary }: { summary: SessionSummary }) => {
  const presentation = presentSessionStatus(summary.status, summary.blockedReason);
  return (
    <span title={presentation.label}>
      <StatusDot variant={presentation.variant} />
      {presentation.label}
    </span>
  );
};

Summary

• Apache Maka defines five session statuses in packages/core/src/session.ts: active, running, waiting_for_user, blocked, and aborted.
• The SessionManager in packages/runtime/src/session-manager.ts controls all transitions through the setSessionStatus() method.
• Blocked sessions carry a blockedReason field explaining the obstruction, while aborted sessions are permanently read-only.
• The UI presentation layer translates technical statuses into visual indicators using presentSessionStatus().
• Type guards like isSessionStatus() enforce runtime type safety when handling session states.

Frequently Asked Questions

What is the initial status when creating a new Maka session?

Every new session begins with the active status. This idle state indicates the session exists in the database but has no turn currently executing. The Session Manager sets this default during session initialization before any Runtime Host attaches.

What causes a session to transition from running to blocked?

A session enters blocked status when a permission check fails, authentication expires, or a tool invocation errors irrecoverably. The Session Manager populates the blockedReason field with specific codes like auth or permission_required. Unlike waiting_for_user, which anticipates user interaction, blocked represents an unexpected obstruction that may require external resolution.

How does the Maka UI reflect session status changes?

The UI layer consumes status updates through the SessionStatusPresentation component in packages/ui/src/session-status-presentation.ts. This pure function maps the technical status enum (and optional blocked reason) to a human-readable label, icon variant, and tooltip. The desktop renderer in apps/desktop/src/renderer/session-status-presentation.ts implements this mapping as visual badges with color-coded status dots.

Can a blocked or aborted session be resumed?

A blocked session can resume if the obstruction clears—transitioning back to running via setSessionStatus(). However, an aborted session is terminal and cannot resume; the state machine design treats abortion as permanent archival, making the session record read-only for audit purposes but rejecting new execution turns.

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