@parall/agent-core 1.51.0 → 1.52.0

package/src/gateway-base.ts

@@ -38,6 +38,8 @@ import {
   type ForkSessionHandle,
   type GatewayLogger,
   type RuntimeEvent,
+  type SettledTurnOutcome,
+  type TurnOutcomeEvent,
 } from './dispatch-adapter.js';
 import {
   clearTypedDedupeForEvent,
@@ -46,11 +48,13 @@ import {
   dispatchLaneGroup,
   resolveDispatchByID,
   settleDrainedTypedGroup,
+  steerLaneMessage,
   typedLedgerEventIds,
 } from './gateway-lane-flow.js';
 import type { LaneFlowHost, TypedConsumeHooks } from './gateway-lane-flow.js';
-import { LaneLedger } from './lane-ledger.js';
+import { LaneLedger, bindLaneSession, releaseLocalMessageClaims } from './lane-ledger.js';
 import { routeTrigger } from './routing.js';
+import { redactTurnOutcome } from './redact.js';
 import { StepPersister, isRetryableStepError } from './step-persister.js';
 import { SessionLifecycleCoordinator, type TurnHandle } from './session-lifecycle.js';
 import { ForkSessionFinalizer } from './fork-session-finalizer.js';
@@ -80,6 +84,7 @@ import {
   endDispatchSpan,
   recordDispatchMetric,
   recordMissingReply,
+  recordTurnUsage,
   runWithSessionKey,
 } from './telemetry.js';
 import type { DispatchState, ParallEvent } from './types.js';
@@ -413,6 +418,9 @@ export class ParallAgentGateway {
         orgId: opts.config.org_id,
         contextDir: opts.dispatchContextDir,
         log: opts.log,
+        coverageMode: opts.dispatchAdapter.inputLifecycleMode ?? 'implicit',
+        releaseLocalClaims: (sourceIds) =>
+          releaseLocalMessageClaims(this.dispatchedMessages, sourceIds),
       });
     }
     this.SHUTDOWN_DEADLINE_MS = opts.shutdownDeadlineMs ?? 60_000;
@@ -813,18 +821,53 @@ export class ParallAgentGateway {
     if (laneKey) this.laneLedger?.renewByKey(laneKey);
   }
 
-  /** Sessions whose in-flight turn surfaced a runtime error event. */
-  private turnErrorSessions = new Set<string>();
+  /**
+   * Settled LLM-layer outcome of each session's last turn — an error to
+   * release lane members on the redrive budget, or a deferred usage-limit
+   * wait (agent-turn-outcome-design.md). Absent = clean turn.
+   */
+  private turnOutcomes = new Map<string, SettledTurnOutcome>();
 
   /**
-   * Consume (read-and-clear) the error marker for sessionKey's last turn.
+   * Consume (read-and-clear) the settled outcome for sessionKey's last turn.
    * Feeds complete's turn_outcome so an error turn's lane members are
-   * released for retry instead of no_action-swept (design §3). Consuming
-   * (rather than peeking) keeps one-shot fork session keys from accumulating
-   * in the set forever.
+   * released for retry (and a deferred turn's members re-deliver at retryAt)
+   * instead of being no_action-swept (design §3). Consuming (rather than
+   * peeking) keeps one-shot fork session keys from accumulating forever.
+   */
+  consumeTurnOutcome(sessionKey: string): SettledTurnOutcome | undefined {
+    const outcome = this.turnOutcomes.get(sessionKey);
+    this.turnOutcomes.delete(sessionKey);
+    return outcome;
+  }
+
+  /**
+   * Boolean view of consumeTurnOutcome for the typed/fork call sites, which
+   * have no deferred semantics: ANY non-clean outcome (error or deferred)
+   * counts as an errored turn there — release-for-retry beats a false
+   * "handled".
    */
   consumeTurnError(sessionKey: string): boolean {
-    return this.turnErrorSessions.delete(sessionKey);
+    return this.consumeTurnOutcome(sessionKey) !== undefined;
+  }
+
+  /**
+   * Fold turn signals into the session's settled outcome. Two sources, one
+   * precedence rule: the bridge's explicit turn_outcome classification always
+   * wins (it may refine the SAME failure a generic `error` event already
+   * reported — e.g. Claude's result frame yields both), while a bare `error`
+   * event only fills the slot when no classification exists. Wire order makes
+   * this safe: every bridge emits its error events before the turn-boundary
+   * turn_outcome.
+   */
+  private recordTurnErrorSignal(sessionKey: string): void {
+    if (!this.turnOutcomes.has(sessionKey)) {
+      this.turnOutcomes.set(sessionKey, { kind: 'error' });
+    }
+  }
+
+  private recordTurnClassification(sessionKey: string, next: SettledTurnOutcome): void {
+    this.turnOutcomes.set(sessionKey, next);
   }
 
   private async emitDispatchReceived(event: ParallEvent): Promise<void> {
@@ -906,7 +949,7 @@ export class ParallAgentGateway {
     earlier: ParallEvent[];
     captureText?: string[];
     hasMoreLocal: () => boolean;
-  }): Promise<'dispatched' | 'foreign' | 'shutdown' | 'failed'> {
+  }): Promise<'dispatched' | 'foreign' | 'shutdown' | 'failed' | 'deferred'> {
     return dispatchLaneGroup(this.laneFlowHost(), opts);
   }
 
@@ -1075,7 +1118,14 @@ export class ParallAgentGateway {
                         }
                       : event.type === 'approval'
                         ? { approval_id: event.messageId }
-                        : { message_id: event.messageId },
+                        : {
+                            message_id: event.messageId,
+                            // Thread context for the session→chat backlink:
+                            // a thread reply can only be navigated to with
+                            // its thread root (the chat surface rejects
+                            // bare thread-message targets).
+                            ...(event.threadRootId ? { thread_root_id: event.threadRootId } : {}),
+                          },
         sender_id: event.senderId,
         sender_name: event.senderName,
         summary: event.body.substring(0, 200),
@@ -1336,6 +1386,7 @@ export class ParallAgentGateway {
     bodyForAgent: string,
     earlierEvents: ParallEvent[] = [],
     captureText?: string[],
+    inputLifecycle?: import('./dispatch-adapter.js').DispatchInputLifecycle,
   ): Promise<boolean> {
     // Graceful shutdown: once SIGTERM has fired we stop accepting new work.
     // In-flight dispatches that started before the flag flipped keep running
@@ -1353,7 +1404,7 @@ export class ParallAgentGateway {
     }
 
     resetDispatchMetrics(sessionKey);
-    this.turnErrorSessions.delete(sessionKey);
+    this.turnOutcomes.delete(sessionKey);
     return runWithSessionKey(sessionKey, async () => {
       let dispatchSpan: ReturnType<typeof startDispatchSpan> = null;
 
@@ -1418,6 +1469,8 @@ export class ParallAgentGateway {
       let inputStepsCreated = false;
       let turnHandle: TurnHandle | undefined;
       let dispatchError: unknown;
+      let turnOutcomeEvent: TurnOutcomeEvent | undefined;
+      let sawErrorEvent = false;
       const pendingSendCallIds = new Set<string>();
       // Turn boundary: must complete one bounded active reconciliation
       // BEFORE this turn's first AgentStep persists — a reused idle session
@@ -1437,6 +1490,7 @@ export class ParallAgentGateway {
           bodyForAgent,
           sessionKey,
           context: dispatchContext,
+          inputLifecycle,
         })) {
           if (runtimeEvent.type === 'runtime_session') {
             const priorAgentSessionId = binding?.agentSessionId;
@@ -1446,6 +1500,13 @@ export class ParallAgentGateway {
               contextFilePath,
               laneContextFilePath,
             );
+            if (activeLane) {
+              // Session attribution for the lane's complete sweep (the server
+              // validates ownership; informational). bindLaneSession flips
+              // sticky-ambiguous on a session rotation instead of blaming
+              // the newest session.
+              bindLaneSession(activeLane, binding.agentSessionId);
+            }
             if (
               event.targetType === 'channel_conversation' &&
               binding.agentSessionId !== priorAgentSessionId
@@ -1480,6 +1541,73 @@ export class ParallAgentGateway {
             continue;
           }
 
+          if (runtimeEvent.type === 'turn_outcome') {
+            // Turn-boundary summary (at most one per turn): capture for the
+            // finally-block telemetry, fold non-ok classes into the settled
+            // outcome the ledger complete consumes, and surface non-ok turns
+            // as an error step so limit/auth failures are visible in the
+            // session panel instead of vanishing as a silent no_action
+            // (agent-turn-outcome-design.md §5).
+            // detail/raw echo provider error bodies — redact before the event
+            // reaches any sink (step, log, telemetry).
+            const outcomeEvent = redactTurnOutcome(runtimeEvent, [this.opts.config.api_key]);
+            turnOutcomeEvent = outcomeEvent;
+            if (outcomeEvent.outcome === 'ok') {
+              // Authoritative boundary verdict: an explicit ok clears any
+              // generic error-event marker recorded earlier this turn (e.g.
+              // codex's broadcast `error` notification followed by a
+              // successful turn/completed) — completing the lane as an error
+              // would redrive successfully handled work.
+              this.turnOutcomes.delete(sessionKey);
+              continue;
+            }
+            this.recordTurnClassification(
+              sessionKey,
+              outcomeEvent.outcome === 'usage_limit'
+                ? {
+                    kind: 'deferred',
+                    outcomeClass: outcomeEvent.outcome,
+                    ...(outcomeEvent.retryAt ? { retryAt: outcomeEvent.retryAt } : {}),
+                  }
+                : { kind: 'error', outcomeClass: outcomeEvent.outcome },
+            );
+            const retryNote = outcomeEvent.retryAt ? `, retry at ${outcomeEvent.retryAt}` : '';
+            this.opts.log?.warn(
+              `turn outcome: ${outcomeEvent.outcome}${retryNote}${outcomeEvent.detail ? ` — ${outcomeEvent.detail}` : ''}`,
+            );
+            if (binding) {
+              // Same lifecycle ordering as every other step-producing event:
+              // the turn must have begun and the input steps must exist
+              // before the outcome step persists — an outcome-first turn
+              // (e.g. openclaw pushing the classification as its only event
+              // on a reused session) must not write a step into an idle
+              // session (review round 2 P2).
+              await ensureTurnBegun();
+              if (!inputStepsCreated) {
+                if (earlierEvents.length > 0) {
+                  await this.createInputStepsForEarlierEvents(
+                    binding.agentSessionId,
+                    earlierEvents,
+                  );
+                }
+                await this.createInputStep(binding.agentSessionId, event);
+                inputStepsCreated = true;
+              }
+              await this.createRuntimeStep(
+                binding.agentSessionId,
+                event,
+                {
+                  type: 'error',
+                  message: `LLM turn ${outcomeEvent.outcome}${retryNote}${outcomeEvent.detail ? `: ${outcomeEvent.detail}` : ''}`,
+                },
+                stepIdFilePath,
+                contextFilePath,
+                laneContextFilePath,
+              );
+            }
+            continue;
+          }
+
           if (!binding) {
             const detail = runtimeEvent.type === 'error' ? `: ${runtimeEvent.message}` : '';
             throw new Error(`runtime emitted ${runtimeEvent.type} before runtime_session${detail}`);
@@ -1518,7 +1646,11 @@ export class ParallAgentGateway {
             recordMessageSend(sessionKey, !runtimeEvent.error);
           }
           if (runtimeEvent.type === 'error') {
-            this.turnErrorSessions.add(sessionKey);
+            sawErrorEvent = true;
+            // Legacy signal (runtimes without a turn_outcome event, and the
+            // pre-boundary error frames of runtimes with one). Fills the
+            // settled slot only when no explicit classification exists.
+            this.recordTurnErrorSignal(sessionKey);
           }
           await this.createRuntimeStep(
             binding.agentSessionId,
@@ -1589,8 +1721,14 @@ export class ParallAgentGateway {
         const metricsSnapshot = getDispatchMetrics(sessionKey);
         const durationMs = metricsSnapshot ? Date.now() - metricsSnapshot.started_at : 0;
 
-        endDispatchSpan(dispatchSpan, metricsSnapshot, dispatchError);
-        recordDispatchMetric(event, this.opts.runtimeType, durationMs);
+        // Effective outcome for telemetry: the bridge's turn_outcome wins;
+        // otherwise a thrown dispatch / legacy error event classifies as
+        // runtime_crash, and a quiet turn is ok.
+        const effectiveOutcome =
+          turnOutcomeEvent?.outcome ?? (dispatchError || sawErrorEvent ? 'runtime_crash' : 'ok');
+        endDispatchSpan(dispatchSpan, metricsSnapshot, dispatchError, turnOutcomeEvent);
+        recordDispatchMetric(event, this.opts.runtimeType, durationMs, effectiveOutcome);
+        recordTurnUsage(turnOutcomeEvent?.usage, this.opts.runtimeType);
 
         if (
           metricsSnapshot &&
@@ -1602,7 +1740,7 @@ export class ParallAgentGateway {
           metricsSnapshot.message_send_successes === 0 &&
           !metricsSnapshot.no_reply_called
         ) {
-          recordMissingReply(this.opts.runtimeType);
+          recordMissingReply(this.opts.runtimeType, effectiveOutcome);
         }
 
         clearDispatchMetrics(sessionKey);
@@ -1730,11 +1868,12 @@ export class ParallAgentGateway {
               for (const item of items) item.resolve(false);
               break;
             }
-            if (outcome === 'failed') {
-              // Error turn: complete(error) already released the members for
-              // redelivery. Do NOT push them to processedEvents — the redrive
-              // must not arrive wearing an "already handled" prefix. Keep
-              // draining; the released work rejoins the next claim.
+            if (outcome === 'failed' || outcome === 'deferred') {
+              // Error/deferred turn: the settlement already released (or
+              // scheduled) the members for redelivery. Do NOT push them to
+              // processedEvents — the redelivery must not arrive wearing an
+              // "already handled" prefix. Keep draining; the released work
+              // rejoins the next claim.
               for (const item of items) item.resolve(false);
               continue;
             }
@@ -1794,10 +1933,10 @@ export class ParallAgentGateway {
         remaining.resolve(false);
       }
     } finally {
-      // One-shot fork keys are never dispatched again — drop any error marker
-      // the legacy (non-ledger) path left unconsumed, or the set grows with
-      // every failed ephemeral fork.
-      this.turnErrorSessions.delete(fork.fork.sessionKey);
+      // One-shot fork keys are never dispatched again — drop any settled
+      // outcome the legacy (non-ledger) path left unconsumed, or the map
+      // grows with every failed ephemeral fork.
+      this.turnOutcomes.delete(fork.fork.sessionKey);
       if (fork.deadlineTimer) {
         clearTimeout(fork.deadlineTimer);
         fork.deadlineTimer = null;
@@ -1913,7 +2052,7 @@ export class ParallAgentGateway {
           this.opts.runtimeKey,
         );
         if (this.usesLaneLedger(event)) {
-          let outcome: 'dispatched' | 'foreign' | 'shutdown' | 'failed';
+          let outcome: 'dispatched' | 'foreign' | 'shutdown' | 'failed' | 'deferred';
           try {
             outcome = await this.dispatchLaneGroup({
               events,
@@ -1940,10 +2079,10 @@ export class ParallAgentGateway {
             this.dispatchState.pendingForkResults.unshift(...pendingFork);
             continue;
           }
-          if (outcome === 'failed') {
-            // Error turn settled with complete(error) — members released for
-            // redelivery. The fork results were not consumed by the failed
-            // turn; keep them for the next real dispatch.
+          if (outcome === 'failed' || outcome === 'deferred') {
+            // Error/deferred turn settled with a non-ok complete — members
+            // released (or scheduled) for redelivery. The fork results were
+            // not consumed by that turn; keep them for the next real dispatch.
             this.dispatchState.pendingForkResults.unshift(...pendingFork);
             continue;
           }
@@ -2109,7 +2248,7 @@ export class ParallAgentGateway {
         if (this.usesLaneLedger(event)) {
           // Ledger flow: claim replaces mark-received; complete/reply replace
           // acks. A foreign incumbent leaves the event pending for re-drive.
-          let outcome: 'dispatched' | 'foreign' | 'shutdown' | 'failed' = 'shutdown';
+          let outcome: 'dispatched' | 'foreign' | 'shutdown' | 'failed' | 'deferred' = 'shutdown';
           try {
             try {
               outcome = await this.dispatchLaneGroup({
@@ -2225,16 +2364,9 @@ export class ParallAgentGateway {
           if (
             !typedAheadInBuffer &&
             this.mainCurrentGroupKey === this.dispatchGroupKey(event) &&
-            this.opts.dispatchAdapter.enqueueDuringDispatch != null &&
-            (await this.laneLedger?.steerLive(event)) &&
-            (await this.opts.dispatchAdapter.enqueueDuringDispatch(
-              this.opts.runtimeKey,
-              buildEventBody(event),
-            ))
+            this.opts.dispatchAdapter.enqueueDuringDispatch != null
           ) {
-            this.opts.log?.info(
-              `steer folded+injected for ${event.messageId} (will drain for bookkeeping)`,
-            );
+            await steerLaneMessage(this.laneFlowHost(), event);
           }
         } else if (
           // Message events only. A typed event (task_comment/schedule/…)

package/src/gateway-lane-flow.ts

@@ -1,6 +1,12 @@
 import { ApiError } from '@parall/sdk';
 import type { ParallClient } from '@parall/sdk';
-import type { DispatchAdapter, GatewayLogger } from './dispatch-adapter.js';
+import type {
+  DispatchAdapter,
+  DispatchInputLifecycle,
+  GatewayLogger,
+  SettledTurnOutcome,
+} from './dispatch-adapter.js';
+import { buildEventBody } from './event-format.js';
 import type { DispatchableMessage, MessageDispatchDecision } from './gateway-base.js';
 import { LedgerUnsupportedError } from './lane-ledger.js';
 import type { LaneLedger } from './lane-ledger.js';
@@ -26,6 +32,7 @@ export interface LaneFlowHost {
   shuttingDown: boolean;
   dispatchedMessages: Set<string>;
   dispatchedTasks: Set<string>;
+  dispatchState: { mainBuffer: ParallEvent[] };
   /**
    * Per-WorkItem failure backoff for typed dispatch consumption. A consume
    * that ends without an ack re-arms the entry; the next attempt for the
@@ -41,11 +48,13 @@ export interface LaneFlowHost {
     config: { org_id: string };
     dispatchAdapter: DispatchAdapter;
     agentUserId: string;
+    runtimeKey: string;
   };
   disableLedger(reason: string): void;
   usesLaneLedger(event: ParallEvent): boolean;
   emitDispatchReceived(event: ParallEvent): Promise<void>;
   consumeTurnError(sessionKey: string): boolean;
+  consumeTurnOutcome(sessionKey: string): SettledTurnOutcome | undefined;
   noteSessionLane(sessionKey: string, laneKey: string | null): void;
   runDispatch(
     event: ParallEvent,
@@ -53,6 +62,7 @@ export interface LaneFlowHost {
     bodyForAgent: string,
     earlierEvents?: ParallEvent[],
     captureText?: string[],
+    inputLifecycle?: DispatchInputLifecycle,
   ): Promise<boolean>;
   tryClaimMessage(id: string): boolean;
   buildMessageDispatchDecision(
@@ -62,6 +72,23 @@ export interface LaneFlowHost {
   handleInboundEvent(event: ParallEvent): Promise<boolean>;
 }
 
+export async function steerLaneMessage(host: LaneFlowHost, event: ParallEvent): Promise<void> {
+  const { laneLedger: ledger, opts } = host;
+  const adapter = opts.dispatchAdapter;
+  if (!ledger || !adapter.enqueueDuringDispatch) return;
+  const folded = await ledger.steerLive(event);
+  if (
+    folded &&
+    (await adapter.enqueueDuringDispatch(
+      opts.runtimeKey,
+      buildEventBody(event),
+      folded.inputLifecycle,
+    ))
+  ) {
+    opts.log?.info(`steer folded+injected for ${event.messageId} (will drain for bookkeeping)`);
+  }
+}
+
 /**
  * Dispatch one group of same-lane message events under the ledger contract:
  * claim (or reuse) the lane, run the dispatch, then complete when no local
@@ -78,7 +105,7 @@ export async function dispatchLaneGroup(
     captureText?: string[];
     hasMoreLocal: () => boolean;
   },
-): Promise<'dispatched' | 'foreign' | 'shutdown' | 'failed'> {
+): Promise<'dispatched' | 'foreign' | 'shutdown' | 'failed' | 'deferred'> {
   const ledger = host.laneLedger!;
   const event = opts.events[opts.events.length - 1];
   let lane: Awaited<ReturnType<LaneLedger['ensureLane']>>;
@@ -121,12 +148,14 @@ export async function dispatchLaneGroup(
   host.noteSessionLane(opts.sessionKey, lane.laneKey);
   let dispatched = false;
   try {
+    const inputLifecycle = ledger.inputLifecycle(lane, [...opts.earlier, event]);
     dispatched = await host.runDispatch(
       event,
       opts.sessionKey,
       opts.body,
       opts.earlier,
       opts.captureText,
+      inputLifecycle,
     );
   } catch (err) {
     // Failed turn: hand the members back so the retry (this pod or the
@@ -141,20 +170,32 @@ export async function dispatchLaneGroup(
     // Shutdown short-circuit — shutdown() releases all active lanes.
     return 'shutdown';
   }
-  if (host.consumeTurnError(opts.sessionKey)) {
-    // An error turn must not no_action-sweep its members — settle the lane
-    // NOW with an error complete so they release for retry on the redrive
-    // budget (dispatch-convergence-design.md §3). Settling immediately (even
-    // with same-lane work still buffered) is deliberate: carrying the error
-    // across buffered turns would let a later reply broad-cover the failed
-    // member, or requeue the later turn's successful work. Released members
-    // rejoin the next claim, merged with whatever was buffered. Dropping the
-    // local dedupe claims lets the server's re-drive hint retrigger the
-    // messages immediately instead of waiting out the renotify pacing.
-    ledger.markTurnError(lane.laneKey);
+  const settled = host.consumeTurnOutcome(opts.sessionKey);
+  if (settled) {
+    // A non-clean turn must not no_action-sweep its members — settle the lane
+    // NOW (even with same-lane work still buffered; deliberate — carrying the
+    // outcome across buffered turns would let a later reply broad-cover the
+    // failed member, or requeue the later turn's successful work):
+    //   - error → error complete; members release for retry on the redrive
+    //     budget (dispatch-convergence-design.md §3).
+    //   - deferred (usage_limit) → deferred complete; members re-deliver at
+    //     retryAt WITHOUT burning redrive budget (agent-turn-outcome-design.md
+    //     §6) — the runtime's LLM lane is limit-choked, so an instant retry
+    //     would just burn a failed turn per redrive cycle.
+    // Released members rejoin the next claim, merged with whatever was
+    // buffered. Dropping the local dedupe claims lets the re-delivery
+    // retrigger the messages when it comes.
+    if (settled.kind === 'deferred') {
+      ledger.markTurnDeferred(lane.laneKey, {
+        outcomeClass: settled.outcomeClass,
+        ...(settled.retryAt ? { retryAt: settled.retryAt } : {}),
+      });
+    } else {
+      ledger.markTurnError(lane.laneKey);
+    }
     // Clear dedupe for EVERY lane member, not just this batch: an earlier
     // successful batch may have deferred its complete via hasMoreLocal, so
-    // the error complete below releases those members too — their redrive
+    // the settlement below releases those members too — their re-delivery
     // would be permanently blocked by a stale local claim.
     for (const msgId of lane.folded.keys()) {
       host.dispatchedMessages.delete(msgId);
@@ -167,13 +208,14 @@ export async function dispatchLaneGroup(
     try {
       host.opts.dispatchAdapter.abortDispatch?.(opts.sessionKey);
     } catch {
-      // best-effort — a throwing abort must not block the error settlement
+      // best-effort — a throwing abort must not block the settlement
     }
     await ledger.completeIfIdle(lane.laneKey, false);
-    // 'failed' — callers must NOT record these events as handled: the server
-    // just released them for redelivery, and an "already handled" fork prefix
-    // (or a consumed fork summary) on the redrive would be a lie.
-    return 'failed';
+    // Non-'dispatched' — callers must NOT record these events as handled: the
+    // server just released (or scheduled) them for redelivery, and an
+    // "already handled" fork prefix (or a consumed fork summary) on the
+    // redrive would be a lie.
+    return settled.kind === 'deferred' ? 'deferred' : 'failed';
   }
   const pendingInjections =
     host.opts.dispatchAdapter.hasPendingInjections?.(opts.sessionKey) ?? false;
@@ -552,6 +594,10 @@ export async function consumeMessageWorkItem(
 ): Promise<void> {
   if (host.shuttingDown) return;
   if (!host.tryClaimMessage(item.source_id)) return;
+  // A failed soft-steer releases the server row before its original local
+  // buffer copy drains. The immediate dispatch.new is only a wake-up: keep
+  // the newly reacquired local claim and let that one buffered copy retry.
+  if (host.dispatchState.mainBuffer.some((event) => event.messageId === item.source_id)) return;
   // Administrative drop (deleted source / self-sender / skip decision): on
   // the ledger path the by-id complete closes the pending row terminally and
   // refuses (409) a row a live lane owns — the owner's turn resolves it. The

package/src/index.ts

@@ -9,8 +9,11 @@ export * from './event-format.js';
 export * from './prompt-fragments.js';
 export * from './bridge-workspace.js';
 export * from './dispatch-adapter.js';
+export * from './redact.js';
 export { createLogger, childLogger } from './logger.js';
 export * from './gateway-base.js';
+export { bindLaneSession } from './lane-ledger.js';
+export type { ActiveLane } from './lane-ledger.js';
 export { configureHttpKeepAlive } from './http-keepalive.js';
 // StepPersister / StepRetryQueue / SessionLifecycleCoordinator /
 // ForkSessionFinalizer are internal gateway collaborators — deliberately NOT