# Session Branching, Turn Regeneration, and Retry Mechanisms in Apache Maka

> Master session branching, turn regeneration, and retry mechanisms in Apache Maka. Recover from errors, re-run turns, and split conversations with immutable history.

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

---

**Apache Maka provides three orthogonal controls—session branching, turn regeneration, and retry mechanisms—that let users recover from errors, re-run turns, or split conversations into new sessions while preserving immutable history.**

Apache Maka's architecture treats a **session** as the top-level execution context containing a series of **turns** (user-assistant exchanges). Understanding how to manipulate these turns through branching, regeneration, and retry operations is essential for building robust conversational workflows. This guide explains each mechanism, how they interact, and where to find them in the Apache Maka source code.

## Session Branching in Apache Maka

**Session branching** creates a brand-new session that inherits the state of a chosen turn while leaving the original session unchanged.

### How Branching Works

When you branch from a turn, Apache Maka:

1. Copies the turn's workspace, current working directory (`cwd`), and tool catalog
2. Duplicates the turn's artifacts
3. Records `branchOfTurnId` and `parentSessionId` for lineage tracking
4. Displays a **branch banner** in the UI

The core implementation lives in [`packages/runtime/src/session-manager.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/session-manager.ts) at line 3871:

```typescript
// SessionManager.branchFromTurn implementation
// Source: https://github.com/apache/maka/blob/main/packages/runtime/src/session-manager.ts#L3871

```

The desktop UI invokes this through the work-bar "Branch from turn" command, defined in [`apps/desktop/src/renderer/platform/desktop/create-workbar-services.ts`](https://github.com/apache/maka/blob/main/apps/desktop/src/renderer/platform/desktop/create-workbar-services.ts) (lines 118-119):

```typescript
// Bridge service registration for branchFromTurn
// bridge.sessions.branchFromTurn
// Source: https://github.com/apache/maka/blob/main/apps/desktop/src/renderer/platform/desktop/create-workbar-services.ts#L118-L119

```

The visual branch banner rendering is handled in [`apps/desktop/src/renderer/features/session-navigation/model/branch-banner.ts`](https://github.com/apache/maka/blob/main/apps/desktop/src/renderer/features/session-navigation/model/branch-banner.ts) at line 47, which reads the `branchOfTurnId` field to construct the UI element.

## Turn Regeneration Mechanism

**Turn regeneration** re-generates the assistant's response for an already-submitted user turn, producing a **sibling turn** that references the original via `regeneratedFromTurnId`.

### Regeneration preserves immutability

The original turn stays completely unchanged. The new turn contains:

- Fresh content from the model provider
- A `regeneratedFromTurnId` pointer to the source turn
- Independent runtime state and artifacts

The `SessionManager.regenerateTurn` method implements this logic, also located in [`packages/runtime/src/session-manager.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/session-manager.ts) (lines 3871-3890):

```typescript
// SessionManager.regenerateTurn implementation
// Source: https://github.com/apache/maka/blob/main/packages/runtime/src/session-manager.ts#L3871-L3890

```

The desktop UI exposes this through `sessions:regenerateTurn`, mapped in the same work-bar services file (lines 159-160). The turn header rendering follows the design-system specification in [`docs/archive/design-system-v0.2-wave-10.md`](https://github.com/apache/maka/blob/main/docs/archive/design-system-v0.2-wave-10.md) (lines 1338-1340).

## Retry Mechanism in Apache Maka

**Retry** executes a fresh turn after a failure (timeout, provider error, etc.) while preserving the original turn's lineage.

### Retry vs. Regeneration

| Aspect | Regeneration | Retry |
|--------|-----------|-------|
| Trigger | User-initiated re-run | Automatic or manual recovery from failure |
| Legacy field | `regeneratedFromTurnId` | `retriedFromTurnId` |
| Implementation path | `SessionManager.regenerateTurn` | Same path with `fallbackTurnId` parameter |

Modern Apache Maka reuses the regeneration infrastructure for retries. The client passes a `fallbackTurnId` that the runtime interprets as a retry signal, as documented in [`docs/archive/maka-capability-audit-v1-2026-05.md`](https://github.com/apache/maka/blob/main/docs/archive/maka-capability-audit-v1-2026-05.md) (lines 348-356):

```

// Retry flow using fallbackTurnId
// Source: https://github.com/apache/maka/blob/main/docs/archive/maka-capability-audit-v1-2026-05.md#L348-L356

```

The "Retry" button UI specification appears in [`docs/archive/design-system-v0.2-wave-10.md`](https://github.com/apache/maka/blob/main/docs/archive/design-system-v0.2-wave-10.md) (lines 767-775).

## How the Three Mechanisms Interact

Apache Maka's session branching, turn regeneration, and retry mechanisms share common architectural foundations that ensure safe, predictable behavior.

### Fresh ID isolation

Both branching and regeneration schedule new **Run** and **Invocation** instances with **fresh IDs**, guaranteeing complete isolation from the source turn's runtime state. This prevents contamination between original and derived executions.

### Safe-Boundary validation

The **Safe-Boundary contract (Phase 1)** validates that the source ledger is complete before any continuation is created. This contract, defined in [`docs/architecture/runtime-resume-phase1-safe-boundary-contract.md`](https://github.com/apache/maka/blob/main/docs/architecture/runtime-resume-phase1-safe-boundary-contract.md) (lines 58-73), prevents operations on corrupted or incomplete session state.

### Idempotency through durable claims

Before invoking any model provider, both branching and regeneration persist:

- `continuationSource` for resumes
- `branchSource` for branches

This ensures concurrent planners **park** rather than duplicate work, preventing race conditions in distributed or multi-window scenarios.

### UI feedback lineage

The work-bar renders contextual indicators:

- **Branch banner** for branched sessions ([`session-branch-banner.ts`](https://github.com/apache/maka/blob/main/session-branch-banner.ts))
- **Regenerate badge** for regenerated turns ([`derive-turn-lineage-badges.ts`](https://github.com/apache/maka/blob/main/derive-turn-lineage-badges.ts))

These visual cues keep users aware that original data remains immutable while new execution proceeds in parallel.

## Key Source Files Reference

| Component | Path | Role |
|-----------|------|------|
| **SessionManager core** | [`packages/runtime/src/session-manager.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/session-manager.ts) | Implements `branchFromTurn`, `regenerateTurn`, and underlying turn-control logic |
| **Preload bridge contract** | [`apps/desktop/src/preload/bridge-contract.d.ts`](https://github.com/apache/maka/blob/main/apps/desktop/src/preload/bridge-contract.d.ts) | Declares IPC methods `sessions:branchFromTurn` and `sessions:regenerateTurn` |
| **Work-bar services** | [`apps/desktop/src/renderer/platform/desktop/create-workbar-services.ts`](https://github.com/apache/maka/blob/main/apps/desktop/src/renderer/platform/desktop/create-workbar-services.ts) | UI façade forwarding branch/regenerate requests to the bridge |
| **App-shell turn actions** | [`apps/desktop/src/renderer/app-shell-turn-actions.ts`](https://github.com/apache/maka/blob/main/apps/desktop/src/renderer/app-shell-turn-actions.ts) | Desktop entry point for "Branch" and "Regenerate" buttons |
| **Branch banner UI** | [`apps/desktop/src/renderer/features/session-navigation/model/branch-banner.ts`](https://github.com/apache/maka/blob/main/apps/desktop/src/renderer/features/session-navigation/model/branch-banner.ts) | Renders visual banner identifying branched sessions |
| **Turn-lineage badge logic** | [`apps/desktop/src/renderer/derive-turn-lineage-badges.ts`](https://github.com/apache/maka/blob/main/apps/desktop/src/renderer/derive-turn-lineage-badges.ts) | Shows badges for retry/regenerate lineage |
| **Design-system spec** | [`docs/archive/design-system-v0.2-wave-10.md`](https://github.com/apache/maka/blob/main/docs/archive/design-system-v0.2-wave-10.md) | Formal definition of turn-control affordances |
| **Capability-audit spec** | [`docs/archive/maka-capability-audit-v1-2026-05.md`](https://github.com/apache/maka/blob/main/docs/archive/maka-capability-audit-v1-2026-05.md) | API contract for `turns:branch`, `turns:regenerate`, and related fields |
| **Safe-Boundary resume contract** | [`docs/architecture/runtime-resume-phase1-safe-boundary-contract.md`](https://github.com/apache/maka/blob/main/docs/architecture/runtime-resume-phase1-safe-boundary-contract.md) | Guarantees safe continuation when resuming interrupted sessions |

## Summary

- **Session branching** creates isolated session copies with full state inheritance via `SessionManager.branchFromTurn`, tracked through `branchOfTurnId` and visualized with branch banners.

- **Turn regeneration** produces immutable sibling turns with `regeneratedFromTurnId` linkage, implemented in `SessionManager.regenerateTurn` and exposed through the work-bar UI.

- **Retry mechanisms** leverage the regeneration infrastructure with `fallbackTurnId` and `retriedFromTurnId` for failure recovery while preserving lineage.

- All three mechanisms enforce **fresh ID isolation**, **Safe-Boundary validation**, and **idempotent durable claims** to ensure reliable, race-free execution.

## Frequently Asked Questions

### What is the difference between session branching and turn regeneration in Apache Maka?

Session branching creates a **new session** with copied state, leaving the original session untouched. Turn regeneration creates a **sibling turn within the same session**, producing an alternative assistant response while preserving the original turn. Branching is for splitting conversation history; regeneration is for revising a single response.

### Can I retry a turn that has already been regenerated?

Yes. Apache Maka's immutable turn model allows arbitrary chaining of operations. A retried turn can reference a regenerated turn as its source, and the badge logic in [`derive-turn-lineage-badges.ts`](https://github.com/apache/maka/blob/main/derive-turn-lineage-badges.ts) will display the appropriate lineage indicators. The runtime treats each operation independently through fresh Run/Invocation IDs.

### Where does Apache Maka store the relationship between original and derived turns?

Branch relationships are stored in `branchOfTurnId` and `parentSessionId` fields on the new session. Regeneration relationships use `regeneratedFromTurnId` on the new turn. Retry operations populate `retriedFromTurnId` for backward compatibility. These fields enable the UI to render banners and badges that visualize turn lineage.