# Session Status Lifecycles in Apache Maka: Complete Technical Guide

> Understand Apache Maka session status lifecycles. Explore active, running, waiting_for_user, blocked, and aborted states managed by the Session Manager's state machine. Master Maka's session flow.

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

---

**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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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:

```typescript
// 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:

```typescript
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`](https://github.com/apache/maka/blob/main/packages/ui/src/session-status-presentation.ts):

```tsx
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`](https://github.com/apache/maka/blob/main/packages/core/src/session.ts): active, running, waiting_for_user, blocked, and aborted.
- The **SessionManager** in [`packages/runtime/src/session-manager.ts`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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.