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

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 at line 3871:

// 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 (lines 118-119):

// 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 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 (lines 3871-3890):

// 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 (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 (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 (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 (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)
• Regenerate badge for regenerated turns (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	Implements branchFromTurn, regenerateTurn, and underlying turn-control logic
Preload bridge contract	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	UI façade forwarding branch/regenerate requests to the bridge
App-shell turn actions	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	Renders visual banner identifying branched sessions
Turn-lineage badge logic	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	Formal definition of turn-control affordances
Capability-audit spec	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	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 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.

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