@makaio/framework 1.0.0-dev-1783705652236 → 1.0.0-dev-1783973359164

package/dist/{index-BvTd61i5.d.mts → index-T96ydgVk.d.mts}

@@ -1,5 +1,5 @@
 import { IMakaioBus } from "@makaio/framework/bus";
-import { IMakaioSession, MakaioSessionAgent, Message, MessageInput, ResponseSchemaDescriptor, SessionContext, TurnInitiator } from "@makaio/framework/contracts";
+import { IMakaioSession, MakaioSessionAgent, Message, MessageInput, MessageOutcome, ResponseSchemaDescriptor, SessionContext, TurnInitiator } from "@makaio/framework/contracts";
 
 //#region services/core/src/session/entities/turn.d.ts
 /**
@@ -11,13 +11,17 @@ interface TurnResult {
   /** Error messages from agents that failed */
   errors: string[];
 }
-/**
- * State change returned by Turn mutation methods.
- * Orchestrator uses this to decide whether to emit turn.completed.
- */
-type TurnStateChange = {
+/** Terminal outcome stored for one admitted message/agent delivery. */
+type TurnPairTerminalOutcome = MessageOutcome;
+/** Result of atomically recording one message/agent terminal transition. */
+type TurnPairStateChange = {
+  accepted: false;
+  turnComplete: false;
+} | {
+  accepted: true;
   turnComplete: false;
 } | {
+  accepted: true;
   turnComplete: true;
   result: TurnResult;
 };
@@ -62,13 +66,13 @@ interface TurnConfig {
  * - No bus dependency (testable in isolation)
  * @example
  * ```typescript
- * const turn = new Turn({ sessionId: 'sess1', agentIds: ['agent1', 'agent2'] });
+ * const turn = new Turn({ sessionId: 'sess1', agentIds: ['agent1', 'agent2'], turnNumber: 1 });
  * turn.addMessage('msg1');
  *
- * const change = turn.markAgentCompleted('agent1');
+ * const change = turn.recordPairTerminal('msg1', 'agent1', 'completed');
  * // change.turnComplete === false (agent2 still pending)
  *
- * const change2 = turn.markAgentCompleted('agent2');
+ * const change2 = turn.recordPairTerminal('msg1', 'agent2', 'completed');
  * // change2.turnComplete === true, change2.result.success === true
  * ```
  */
@@ -85,14 +89,14 @@ declare class Turn$1 {
   private readonly _initiator;
   /** Agents participating in this turn (immutable after creation) */
   private readonly _agentIds;
-  /** Messages sent during this turn */
+  /** Messages durably admitted during this turn. */
   private readonly _messageIds;
-  /** Message IDs currently claiming this turn while their storage append is in-flight. */
-  private readonly _pendingMessageAppends;
-  /** Agents that have completed successfully */
-  private readonly _completedAgents;
-  /** Agents that errored (agentId → error message) */
-  private readonly _erroredAgents;
+  /** Targeted agents for each admitted message.  This is the authoritative turn ledger. */
+  private readonly admittedTargetsByMessageId;
+  /** Terminal outcome for each admitted `{messageId, agentId}` pair. */
+  private readonly terminalPairs;
+  /** Message admissions whose append/lifecycle setup has not committed yet. */
+  private readonly pendingMessageAdmissions;
   constructor(config: TurnConfig);
   /**
    * Agents participating in this turn.
@@ -115,16 +119,6 @@ declare class Turn$1 {
    * @returns True when at least one message append is in-flight
    */
   get hasPendingMessageAppends(): boolean;
-  /**
-   * Agents that have completed successfully.
-   * @returns Read-only set of completed agent IDs
-   */
-  get completedAgents(): ReadonlySet<string>;
-  /**
-   * Agents that errored.
-   * @returns Read-only map of agent ID to error message
-   */
-  get erroredAgents(): ReadonlyMap<string, string>;
   /**
    * Add a message to this turn.
    * @param messageId - The message ID to add
@@ -141,18 +135,43 @@ declare class Turn$1 {
    */
   releaseMessageAppend(messageId: string): void;
   /**
-   * Mark an agent as completed successfully.
-   * @param agentId - The agent that completed
-   * @returns State change indicating if turn is now complete
+   * Admit a message and its complete fanout into this turn's immutable ledger.
+   * Completion may only terminalize pairs admitted through this method.
+   * @param messageId - Stable user-message identity.
+   * @param agentIds - Immutable participant subset targeted by this delivery.
+   */
+  admitMessage(messageId: string, agentIds: readonly string[]): void;
+  /**
+   * Commit a durable pre-dispatch message admission.
+   * @param messageId - Admitted message whose setup became durable.
    */
-  markAgentCompleted(agentId: string): TurnStateChange;
+  commitMessageAdmission(messageId: string): void;
   /**
-   * Mark an agent as errored.
-   * @param agentId - The agent that errored
-   * @param error - Error message
-   * @returns State change indicating if turn is now complete
+   * Roll back an admission whose append or lifecycle setup failed before dispatch.
+   * @param messageId - Unrouted message admission to remove.
    */
-  markAgentErrored(agentId: string, error: string): TurnStateChange;
+  rollbackMessageAdmission(messageId: string): void;
+  /**
+   * Record one terminal outcome for an admitted delivery pair.
+   * @param messageId - Exact admitted message identity.
+   * @param agentId - Exact targeted agent identity.
+   * @param outcome - Canonical terminal delivery outcome.
+   * @param error - Optional provider or routing error.
+   * @returns Whether the pair was accepted and completed the turn.
+   */
+  recordPairTerminal(messageId: string, agentId: string, outcome: TurnPairTerminalOutcome, error?: string): TurnPairStateChange;
+  /**
+   * Whether a concrete admitted delivery pair exists.
+   * @param messageId - Message identity to inspect.
+   * @param agentId - Agent identity to inspect.
+   * @returns Whether the exact delivery pair was admitted.
+   */
+  hasAdmittedPair(messageId: string, agentId: string): boolean;
+  /** @returns Snapshot of every admitted delivery pair for barriers and diagnostics. */
+  get admittedPairs(): readonly {
+    messageId: string;
+    agentId: string;
+  }[];
   /**
    * Check if an agent is part of this turn.
    * @param agentId - The agent ID to check
@@ -160,8 +179,8 @@ declare class Turn$1 {
    */
   hasAgent(agentId: string): boolean;
   /**
-   * Check if the turn is complete (all agents finished).
-   * @returns True if all agents have completed or errored
+   * Check whether every admitted delivery pair reached a terminal outcome.
+   * @returns True when the turn has at least one committed admission and all of its pairs are terminal
    */
   isComplete(): boolean;
   /**
@@ -183,22 +202,48 @@ declare class Turn$1 {
    */
   getContextForMessage(messageId: string): TurnContext;
   /**
-   * Return the recorded terminal outcome for an agent, if any.
-   * @param agentId - Agent ID to inspect.
-   * @returns Terminal outcome already recorded for the agent.
-   */
-  private getAgentTerminalOutcome;
-  /**
-   * Check if turn should complete and return appropriate state change.
-   * @returns State change indicating completion status and result if complete
+   * Return a collision-free in-memory key for a ledger pair.
+   * @param messageId - Message component of the pair.
+   * @param agentId - Agent component of the pair.
+   * @returns Collision-free composite key.
    */
-  private checkCompletion;
+  private pairKey;
 }
 //#endregion
-//#region services/core/src/session/session-turn-manager.d.ts
-/**
- * Result of a completed turn.
- */
+//#region services/core/src/session/turn-slot-registry.d.ts
+declare const turnReservationBrand: unique symbol;
+/** Opaque exclusive claim on a session's next routable turn slot. */
+interface TurnReservation {
+  /** Session whose turn slot is exclusively reserved. */
+  readonly sessionId: string;
+  /** Prevents callers from fabricating reservations outside this module. */
+  readonly [turnReservationBrand]: true;
+}
+/** Result of atomically acquiring a session turn for normal message delivery. */
+interface TurnAcquisition {
+  /** Routable turn acquired for the caller. */
+  readonly turn: Turn$1;
+  /** Whether this caller created the turn rather than joining an existing one. */
+  readonly isNew: boolean;
+}
+/** Atomic pre-dispatch ownership of one admitted message fanout. */
+interface TurnMessageAdmissionLease {
+  readonly turn: Turn$1;
+  readonly messageId: string;
+  readonly agentIds: readonly string[];
+  /** Finalize the durable append/lifecycle setup and permit terminal outcomes. */
+  commit(): void;
+  /** Remove an un-routed admission after pre-dispatch setup failed. */
+  rollback(): Promise<void>;
+}
+/** Admission lease composed with the turn's one-time durable preparation gate. */
+interface PreparedTurnMessageAdmissionLease extends TurnMessageAdmissionLease {
+  readonly isPreparationOwner: boolean;
+  rollback(errorCode?: string): Promise<void>;
+}
+//#endregion
+//#region services/core/src/session/turn-completion.d.ts
+/** Result of a completed turn. */
 interface TurnCompletionResult {
   /** Whether all agents completed successfully. */
   success: boolean;
@@ -206,11 +251,13 @@ interface TurnCompletionResult {
   errors: string[];
 }
 /**
- * Callback invoked when a turn completes (all agents finished).
- * @param turn - The completed turn
- * @param result - Success/error status with error messages
+ * Callback invoked when every agent participating in a turn has finished.
+ * @param turn - Completed turn.
+ * @param result - Canonical success and error result.
  */
 type TurnCompleteCallback = (turn: Turn$1, result: TurnCompletionResult) => Promise<void>;
+//#endregion
+//#region services/core/src/session/session-turn-manager.d.ts
 /**
  * Composable turn lifecycle manager.
  *
@@ -225,28 +272,39 @@ type TurnCompleteCallback = (turn: Turn$1, result: TurnCompletionResult) => Prom
  * locally. When `TurnStorageSubjects.complete` is unhandled, the turn is
  * still cleared from memory and `session.turn.completed` is emitted.
  *
- * **Persist-before-emit barrier:** `session.turn.completed` promises the
- * four-point consumer contract, including messages being queryable via
- * `storage:message.getByTurn`. Message persistence (SessionBridge) and turn
- * completion both react to `agent.complete`, and the bus runs event handlers
- * in parallel — so before emitting, `completeTurn` awaits
- * `storage:message.stored` confirmations for the turn's assistant messages
- * (bus-mediated: the manager holds no reference to SessionBridge). The wait
- * is bounded by {@link TURN_COMPLETION_PERSISTENCE_TIMEOUT_MS} and skipped
- * entirely in ephemeral mode.
+ * **Persist-before-emit barrier:** successful assistant-message writes finish
+ * before consumers observe `session.turn.completed`. Message persistence
+ * (SessionBridge) and turn completion both react to `agent.complete`, and the
+ * bus runs event handlers in parallel — so before emitting, `completeTurn` awaits
+ * `session.turn.assistantPersistenceSettled` confirmations for every agent in
+ * the turn (bus-mediated: the manager holds no reference to SessionBridge).
+ * The wait is bounded by {@link TURN_COMPLETION_PERSISTENCE_TIMEOUT_MS} as a
+ * missing-bridge fallback and skipped entirely in ephemeral mode.
  */
 declare class SessionTurnManager {
   private readonly bus;
-  /** Active turns keyed by sessionId (one turn per session). */
-  private readonly activeTurns;
+  /** Owns routable turn slots and reservations across asynchronous setup. */
+  private readonly turnSlots;
   /** Per-turn usage accumulators, keyed by turnId. */
   private readonly usageAccumulators;
   /** Turns currently persisting completion (prevents concurrent writes). */
   private readonly completingTurnIds;
+  /** Shared completion work so slot gates can await an already-finalizing turn. */
+  private readonly completionPromises;
   /** Completing turns retained for usage correlation after active routing is cleared. */
   private readonly completingTurns;
+  /**
+   * Turns whose terminal usage snapshot is closed. Completion correlation may
+   * remain retryable after this point, but a retry must never reopen usage
+   * admission and mutate the snapshot already selected for lifecycle output.
+   */
+  private readonly closedUsageAdmissions;
   /** Pending terminal completions keyed by turnId; value records whether turn storage handled the transition. */
   private readonly pendingTerminalCompletions;
+  /** Canonical terminal result retained while a finalizing turn needs an explicit retry. */
+  private readonly pendingTerminalResults;
+  /** Setup-failed turns block new admission until their terminal write reconciles. */
+  private readonly setupFinalizingTurnIds;
   /** Usage events received while completion persistence is in-flight. */
   private readonly bufferedUsageDuringCompletion;
   /**
@@ -258,18 +316,8 @@ declare class SessionTurnManager {
    * the counter and cause duplicate turn numbers if the session continues.
    */
   private readonly syntheticTurnCounters;
-  /**
-   * Stored assistant messages per turnId, counted from `storage:message.stored`.
-   *
-   * Populated continuously (from construction) so messages persisted before
-   * `completeTurn` runs are counted. FIFO-capped at
-   * {@link ASSISTANT_PERSISTENCE_COUNTER_CAP}; a turn's entry is deleted when
-   * its completion emits, so late `stored` events for an already-emitted turn
-   * merely recreate a short-lived entry that the cap eventually evicts.
-   */
-  private readonly assistantStoredCounts;
-  /** Pending persist-before-emit barrier waiters, keyed by turnId. */
-  private readonly assistantPersistenceWaiters;
+  /** Bus-mediated assistant-message persistence barrier. */
+  private readonly assistantPersistenceBarrier;
   /** Bus subscription cleanup functions. */
   private readonly cleanups;
   /**
@@ -277,7 +325,68 @@ declare class SessionTurnManager {
    */
   constructor(bus: IMakaioBus);
   /**
-   * Create a new turn, tracking it as active.
+   * Acquire the routable turn for an ordinary message send.
+   *
+   * Concurrent sends either join the existing turn or await the same reserved
+   * creation. They can never each create and overwrite a turn after storage
+   * assignment has awaited.
+   * @param sessionId - Session receiving the message.
+   * @param agentIds - Agents participating when a new turn is needed.
+   * @param initiator - Turn origin metadata for a new turn.
+   * @param turnId - Optional pre-assigned identifier for a new turn.
+   * @returns Existing or newly created routable turn plus its acquisition mode.
+   */
+  acquireTurn(sessionId: string, agentIds: string[], initiator?: TurnInitiator, turnId?: string): Promise<TurnAcquisition>;
+  /**
+   * Reserve an otherwise idle session turn slot for an exclusive setup flow.
+   *
+   * Attach uses this before starting its idle agent, so an initial-message
+   * attach is rejected before it can create a second provider lifecycle for a
+   * session already routing work.
+   * @param sessionId - Session whose next turn slot is reserved.
+   * @returns Opaque reservation consumed by {@link createReservedTurn}.
+   */
+  reserveTurn(sessionId: string): Promise<TurnReservation>;
+  /**
+   * Release an unused exclusive turn reservation.
+   * @param reservation - Reservation previously returned by {@link reserveTurn}.
+   */
+  releaseTurnReservation(reservation: TurnReservation): void;
+  /**
+   * Atomically acquire a routable turn and admit the complete message fanout.
+   * When a concurrent terminal transition wins, acquisition retries rather than
+   * returning a turn whose completion can no longer see this message.
+   * @param sessionId - Session receiving the message.
+   * @param agentIds - Immutable participant subset targeted by the message.
+   * @param messageId - Stable message identity.
+   * @param initiator - Optional turn origin metadata.
+   * @param turnId - Optional preassigned turn identity.
+   * @returns Prepared admission lease after first-message ordering is satisfied.
+   */
+  acquireMessageAdmission(sessionId: string, agentIds: string[], messageId: string, initiator?: TurnInitiator, turnId?: string): Promise<PreparedTurnMessageAdmissionLease>;
+  /**
+   * Admit a message to an exclusively reserved attach turn.
+   * @param turn - Exclusively reserved attach turn.
+   * @param messageId - Stable initial-message identity.
+   * @param agentIds - Attach target participant set.
+   * @returns Prepared admission lease for the attach message.
+   */
+  admitReservedMessage(turn: Turn$1, messageId: string, agentIds: string[]): PreparedTurnMessageAdmissionLease;
+  /**
+   * Create a reserved turn once an exclusive setup flow knows its participants.
+   *
+   * Calls `TurnStorageSubjects.create` via `requestOptional`. If no storage
+   * handler is registered (ephemeral mode), generates a synthetic UUID turn ID
+   * and a per-session incrementing turn number.
+   * @param reservation - Exclusive slot claim returned by {@link reserveTurn}.
+   * @param agentIds - Agents participating in the new turn.
+   * @param initiator - Turn origin metadata (user, plugin, system).
+   * @param turnId - Optional pre-assigned turn ID passed to storage.
+   * @returns Newly created and activated turn.
+   */
+  createReservedTurn(reservation: TurnReservation, agentIds: string[], initiator?: TurnInitiator, turnId?: string): Promise<Turn$1>;
+  /**
+   * Create a new exclusive turn, tracking it as active.
    *
    * Calls `TurnStorageSubjects.create` via `requestOptional`. If no storage
    * handler is registered (ephemeral mode), generates a synthetic UUID turn ID
@@ -296,11 +405,23 @@ declare class SessionTurnManager {
    * @param turn - Newly created active turn to discard
    */
   discardActiveTurn(turn: Turn$1): void;
+  /**
+   * Mark a newly created turn as failed before provider dispatch and discard its active state.
+   *
+   * A user message may already be durable when a later pre-dispatch lifecycle
+   * step fails. No provider turn has been accepted in either case, so the
+   * manager can terminalize the turn directly without waiting for assistant
+   * persistence.
+   * @param turn - Active turn whose setup failed before provider dispatch
+   * @param error - Durable error code to store on the terminal turn
+   */
+  failActiveTurnBeforeDispatch(turn: Turn$1, error: string): Promise<void>;
   /**
    * Mark an unclaimed newly created turn as failed and discard its active in-memory state.
    *
-   * This preserves the durable turn lifecycle invariant when setup fails after
-   * `storage:turn.create` has already assigned a turn number.
+   * Concurrent sends may have claimed the turn by the time their sibling's
+   * append fails. Those turns remain routable; callers that own the entire
+   * pre-dispatch sequence should use {@link failActiveTurnBeforeDispatch}.
    * @param turn - Newly created active turn whose setup failed before any message claimed it
    * @param error - Durable error code to store on the terminal turn
    */
@@ -311,6 +432,7 @@ declare class SessionTurnManager {
    * @returns Whether the turn owned and cleared the active routing slot
    */
   private clearActiveRoutingTurn;
+  private composeAdmissionWithPreparation;
   /**
    * Register bus listeners for `agent.usage` and `agent.complete` events.
    *
@@ -329,18 +451,33 @@ declare class SessionTurnManager {
    * Usage is snapshotted before the storage call. Any usage events that arrive
    * while persistence is in-flight are buffered and merged into a second
    * `TurnStorageSubjects.complete` call. State is cleared only after durable
-   * persistence succeeds; if persistence fails, the state remains intact so
-   * completion can be retried.
+   * persistence succeeds; if persistence fails, non-routable finalization
+   * state remains available to {@link retryTurnCompletion}.
    *
-   * Before the event fires, the persist-before-emit barrier waits for the
-   * turn's assistant messages to be stored (see class docs), then a
-   * `turn.completed` lifecycle row is appended to `session_events` — so both
-   * message rows and the lifecycle row are durable before consumers observe
-   * `session.turn.completed`.
+   * Before the event fires, the persist-before-emit barrier waits for every
+   * agent's assistant-persistence decision to settle (see class docs), then a
+   * `turn.completed` lifecycle row is appended to `session_events`. Successful
+   * message writes and the lifecycle row are therefore durable before consumers
+   * observe `session.turn.completed`.
    * @param turn - The turn to complete
    * @param result - Turn result (success status and error messages)
+   * @returns Promise resolved after durable finalization and emission.
    */
   completeTurn(turn: Turn$1, result: TurnCompletionResult): Promise<void>;
+  private completeTurnInternal;
+  /**
+   * Retry a retained non-routable completion after durable storage failed.
+   * @param turnId - Identifier of the finalizing turn to retry.
+   */
+  retryTurnCompletion(turnId: string): Promise<void>;
+  /**
+   * Retry retained durable finalization before a session accepts new work.
+   *
+   * A provider normally emits one terminal event, so an ordinary later send is
+   * the reachable owner trigger for a completion whose storage response failed.
+   * @param sessionId - Session about to acquire a new routable turn.
+   */
+  retryRetainedCompletionsForSession(sessionId: string): Promise<void>;
   /**
    * Clear in-memory state retained only while a turn completion is in progress.
    * @param turn - Turn whose completion state should be removed
@@ -353,15 +490,6 @@ declare class SessionTurnManager {
    * @returns Active turn, or `undefined` if no turn is in progress
    */
   getActiveTurn(sessionId: string): Turn$1 | undefined;
-  /**
-   * Expose the active turns map for handlers that need direct access.
-   *
-   * Used by `registerAttachHandler` which tracks turns started via
-   * `session.agent.attach` (with an `initialMessage`) in the shared map so
-   * that the completion handler can detect when the attached turn finishes.
-   * @returns Reference to the internal active turns map
-   */
-  getActiveTurnsMap(): Map<string, Turn$1>;
   /**
    * Find an active turn by turn ID (scans all sessions).
    *
@@ -383,12 +511,16 @@ declare class SessionTurnManager {
    * Marks the agent on the turn, emits `user_message.completed` for each
    * message in the turn, then calls `onTurnComplete` when all agents are done.
    * @param agentId - The agent that completed
-   * @param success - Whether the agent completed successfully
+   * @param messageId - Exact admitted message identity.
+   * @param outcome - Canonical provider or routing outcome.
    * @param error - Error message if the agent failed
    * @param onTurnComplete - Callback to invoke when the turn is complete
-   * @param completionTurnId - Turn identifier supplied by the adapter completion event
+   * @param completionTurnId - Explicit turn identifier supplied by the adapter completion event
+   * @returns Promise resolved after pair observation and any terminal finalization.
    */
-  private handleAgentCompletion;
+  recordAgentCompletion(agentId: string, messageId: string, outcome: MessageOutcome, error: string | undefined, onTurnComplete: TurnCompleteCallback, completionTurnId: string): Promise<void>;
+  private completionEventHooks;
+  private beginFinalization;
   /**
    * Buffer a usage event that arrived while turn completion persistence is in-flight.
    * @param turnId - Turn whose completion is currently being persisted
@@ -407,64 +539,6 @@ declare class SessionTurnManager {
    * @returns Active or completing turn, if completion can still be correlated
    */
   private findTurnForCompletion;
-  /**
-   * Find the active turn for a legacy completion event without turnId.
-   * @param agentId - Agent ID from the completion event.
-   * @returns Active turn to mutate, or undefined when the event is ambiguous.
-   */
-  private findTurnForUncorrelatedCompletion;
-  /**
-   * Check whether a terminal outcome has already been recorded for an agent.
-   * @param turn - Turn being completed.
-   * @param agentId - Agent ID from the terminal event.
-   * @returns Whether the agent already has a terminal outcome on the turn.
-   */
-  private hasTerminalOutcome;
-  /**
-   * Persist a turn's terminal status and optional usage snapshot.
-   * @param turn - Turn being completed
-   * @param result - Completion result to persist
-   * @param usage - Usage snapshot to include, when available
-   * @param expectedStatus - Optional status guard for the first terminal transition
-   * @returns Whether turn storage handled the request and terminalized the turn
-   */
-  private persistTurnCompletion;
-  /**
-   * Merge buffered usage and persist the updated snapshot.
-   * @param turn - Turn whose buffered usage should be merged
-   * @param result - Completion result for the turn
-   * @param usageAccumulator - Usage accumulator captured by the completing turn
-   * @param currentUsage - Current completed usage snapshot
-   * @returns Updated usage snapshot
-   */
-  private flushBufferedUsageDuringCompletion;
-  /**
-   * Subscribe to `storage:message.stored` and count stored assistant messages
-   * per turnId, resolving any pending barrier waiter on each increment.
-   *
-   * Registered from the constructor (not `registerCompletionHandlers`) so the
-   * barrier also works for callers that drive `completeTurn` directly without
-   * wiring the agent-event handlers.
-   */
-  private registerAssistantPersistenceCounter;
-  /**
-   * Persist-before-emit barrier: wait until the turn's assistant messages are
-   * durably stored (one per agent) or the bounded timeout elapses.
-   *
-   * Resolution paths, in order:
-   * 1. The continuous `storage:message.stored` counter already reached the
-   *    expected count (messages stored before `completeTurn` ran).
-   * 2. `storage:message.getByTurn` is unhandled — no message storage exists,
-   *    nothing can be waited for (skip).
-   * 3. A queryable-state probe already shows the expected assistant messages
-   *    (covers messages persisted before this manager was constructed).
-   * 4. A waiter resolved by the counter reaching the expected count, bounded
-   *    by {@link TURN_COMPLETION_PERSISTENCE_TIMEOUT_MS} — the timeout is
-   *    mandatory because SessionBridge persists nothing for agents with zero
-   *    blocks and no error, and swallows write errors.
-   * @param turn - The completing turn (expected count = its agent count)
-   */
-  private awaitAssistantPersistence;
 }
 //#endregion
 //#region services/core/src/session/handlers/abandon-handler.d.ts
@@ -488,11 +562,11 @@ declare function registerAbandonHandler(bus: IMakaioBus): () => void;
  * For branching conversations (fork), use session.fork to create a new session
  * with copied history, then attach agents to the new session.
  * @param bus - Bus instance for communication
- * @param activeTurns - Shared turn state map
+ * @param turnManager - Shared owner of session turn lifecycle state
  * @param machineId - Optional machine ID for deterministic adapter resolution
  * @returns Cleanup function to unsubscribe
  */
-declare function registerAttachHandler(bus: IMakaioBus, activeTurns: Map<string, Turn$1>, machineId?: string): () => void;
+declare function registerAttachHandler(bus: IMakaioBus, turnManager: SessionTurnManager, machineId?: string): () => void;
 //#endregion
 //#region services/core/src/session/handlers/compress-handler.d.ts
 /**
@@ -528,6 +602,12 @@ declare function registerForkHandler(bus: IMakaioBus, machineId?: string): () =>
  */
 declare function registerMergeHandler(bus: IMakaioBus): () => void;
 //#endregion
+//#region services/core/src/session/handlers/routing-lifecycle.d.ts
+/** Narrow ledger transition owned by SessionTurnManager and injected into routing. */
+interface TurnCompletionRecorder {
+  recordAgentCompletion(agentId: string, messageId: string, outcome: MessageOutcome, error: string | undefined, onTurnComplete: TurnCompleteCallback, turnId: string): Promise<void>;
+}
+//#endregion
 //#region services/core/src/session/handlers/route-to-agents.d.ts
 /**
  * Interface for turn context enrichment.
@@ -563,6 +643,8 @@ interface RouteToAgentsOptions {
     success: boolean;
     errors: string[];
   }) => Promise<void>;
+  /** Shared turn ledger owner. */
+  readonly turnManager: TurnCompletionRecorder;
   /** Session context with curated messageHistory and decision signals. */
   readonly sessionContext?: SessionContext;
   /** Optional enricher for immediate message context. */
@@ -596,6 +678,19 @@ interface RouteToAgentsOptions {
 declare function routeToAgents(options: RouteToAgentsOptions): Promise<void>;
 //#endregion
 //#region services/core/src/session/handlers/route-to-agents-core.d.ts
+/** Durable result of one agent's core-routing dispatch attempt. */
+type AgentDispatchOutcome = {
+  readonly agentId: string;
+  readonly kind: 'dispatched';
+} | {
+  readonly agentId: string;
+  readonly kind: 'cancelled';
+  readonly error: unknown;
+} | {
+  readonly agentId: string;
+  readonly kind: 'failed';
+  readonly error: unknown;
+};
 /**
  * Route a message to target agents using a single shared session context.
  *
@@ -616,9 +711,14 @@ declare function routeToAgents(options: RouteToAgentsOptions): Promise<void>;
  * @param turn - Turn tracking object
  * @param deliveryMode - How to deliver the message to the agent
  * @param onTurnComplete - Callback invoked when the turn completes (all agents done)
+ * @param turnManager - Required ledger owner for direct terminal outcomes
  * @param sessionContext - Optional shared session context forwarded to all agents
  * @param responseSchema - Optional structured output descriptor for the turn
+ * @returns Durable dispatch outcomes after direct routing failures terminalize.
  */
-declare function routeToAgentsCore(bus: IMakaioBus, session: IMakaioSession, agents: MakaioSessionAgent[], message: MessageInput, messageId: string, turn: Turn$1, deliveryMode: 'enqueue' | 'immediate' | undefined, onTurnComplete: TurnCompleteCallback, sessionContext?: SessionContext, responseSchema?: ResponseSchemaDescriptor): Promise<void>;
+declare function routeToAgentsCore(bus: IMakaioBus, session: IMakaioSession, agents: ReadonlyArray<{
+  agentId: string;
+  adapterId: string;
+}>, message: MessageInput, messageId: string, turn: Turn$1, deliveryMode: 'enqueue' | 'immediate' | undefined, onTurnComplete: TurnCompleteCallback, turnManager: TurnCompletionRecorder, sessionContext?: SessionContext, responseSchema?: ResponseSchemaDescriptor): Promise<readonly AgentDispatchOutcome[]>;
 //#endregion
-export { registerCompressHandler as a, SessionTurnManager as c, Turn$1 as d, TurnConfig as f, TurnStateChange as h, registerForkHandler as i, TurnCompleteCallback as l, TurnResult as m, routeToAgents as n, registerAttachHandler as o, TurnContext as p, registerMergeHandler as r, registerAbandonHandler as s, routeToAgentsCore as t, TurnCompletionResult as u };
+export { registerCompressHandler as a, SessionTurnManager as c, TurnContext as d, TurnPairStateChange as f, registerForkHandler as i, Turn$1 as l, TurnResult as m, routeToAgents as n, registerAttachHandler as o, TurnPairTerminalOutcome as p, registerMergeHandler as r, registerAbandonHandler as s, routeToAgentsCore as t, TurnConfig as u };

package/dist/{index-DLNRgZPo2.d.mts → index-j2YlW_Fc.d.mts}

@@ -1,4 +1,4 @@
-import { t as ContractStorageNamespaceDefinition } from "./storage-namespace-definition-BffdI5Bz.mjs";
+import { t as ContractStorageNamespaceDefinition } from "./storage-namespace-definition-BZJGSaX3.mjs";
 import * as _$zod from "zod";
 import { z } from "zod";
 import * as _$_makaio_core0 from "@makaio/framework/core";