@parall/agent-core 1.36.1 → 1.38.0

package/src/gateway-base.ts

@@ -7,6 +7,8 @@ import type {
   AgentNewSessionData,
   AgentSessionDB,
   Approval,
+  ChannelConversation,
+  ChannelMessage,
   Chat,
   ChatUpdateData,
   Comment,
@@ -34,6 +36,13 @@ import type {
   GatewayLogger,
   RuntimeEvent,
 } from './dispatch-adapter.js';
+import {
+  consumeMessageWorkItem,
+  consumeTypedDispatch,
+  dispatchLaneGroup,
+} from './gateway-lane-flow.js';
+import type { LaneFlowHost } from './gateway-lane-flow.js';
+import { LaneLedger } from './lane-ledger.js';
 import { routeTrigger } from './routing.js';
 import {
   clearDispatchMessageId,
@@ -87,7 +96,7 @@ type ActiveForkState = {
   deadlineExceeded: boolean;
 };
 
-type DispatchableMessage = {
+export type DispatchableMessage = {
   id: string;
   sender_id: string;
   sender?: { display_name?: string | null };
@@ -99,7 +108,7 @@ type DispatchableMessage = {
   created_at?: string;
 };
 
-type MessageDispatchDecision =
+export type MessageDispatchDecision =
   | { action: 'dispatch'; event: ParallEvent }
   | { action: 'skip' }
   | { action: 'retry' };
@@ -131,6 +140,13 @@ export type ParallGatewayOptions = {
   contextFilePathForSession?: (sessionKey: string) => string | undefined;
   /** @deprecated Use contextFilePathForSession. Kept for runtimes that haven't migrated. */
   stepIdFilePathForSession?: (sessionKey: string) => string | undefined;
+  /**
+   * PRLL_CONTEXT_DIR contract root (per-agent stateDir, never the workspace).
+   * When set, chat-message dispatches ride the server dispatch ledger
+   * (claim → steer → complete) and per-lane context files are written under
+   * this directory. Absent → legacy received/ack flow (openclaw / hermes).
+   */
+  dispatchContextDir?: string;
   onConfigUpdate?: (data: AgentConfigUpdateData) => Promise<void> | void;
   onSessionReady?: (state: {
     activeSessionId?: string;
@@ -198,6 +214,9 @@ function resolveStepTarget(event: ParallEvent): { target_type: string; target_id
   if (event.type === 'external_trigger' || event.targetId.startsWith('xtr_')) {
     return { target_type: 'external_trigger', target_id: event.targetId };
   }
+  if (event.type === 'channel_message' || event.targetId.startsWith('chv_')) {
+    return { target_type: 'channel_conversation', target_id: event.targetId };
+  }
   if (event.type === 'wiki_comment') {
     // target_id is the full wiki target_uri (scheme-stripped routing key). The
     // server stores target_type freely and only publishes step WS events /
@@ -269,6 +288,9 @@ async function fetchAllChats(
 export class ParallAgentGateway {
   private readonly chatInfoMap = new Map<string, ChatInfo>();
   private readonly dispatchedTasks = new Set<string>();
+  // connection id → provider alias, for channel_message prompt labeling
+  // (stable mapping; avoids one connection fetch per inbound message).
+  private readonly channelConnectionProviders = new Map<string, string>();
   private readonly dispatchedMessages = new Set<string>();
   private readonly forkStates = new Map<string, ActiveForkState>();
   private readonly dispatchState: DispatchState = {
@@ -295,6 +317,15 @@ export class ParallAgentGateway {
   private drainResolvers: Array<() => void> = [];
   private pendingRestartNotification: string | null = null;
 
+  private readonly laneLedger?: LaneLedger;
+  // Sticky fallback: flipped when the server predates the ledger (claim
+  // endpoint 404) so every subsequent dispatch uses the legacy flow.
+  private ledgerDisabled = false;
+  // Group key of the group currently being dispatched on main — lane-aware
+  // (targetId + thread), unlike mainCurrentTargetId which stays chat-level
+  // for fork routing decisions.
+  private mainCurrentGroupKey?: string;
+
   private readonly DISPATCHED_MESSAGES_CAP = 5000;
   // SHUTDOWN_DEADLINE_MS is read by waitForDrain via the configured value
   // below — kept as instance state so per-runtime configs can override it
@@ -304,6 +335,14 @@ export class ParallAgentGateway {
   private readonly DISPATCH_DEADLINE_MS: number;
 
   constructor(private readonly opts: ParallGatewayOptions) {
+    if (opts.dispatchContextDir) {
+      this.laneLedger = new LaneLedger({
+        client: opts.client,
+        orgId: opts.config.org_id,
+        contextDir: opts.dispatchContextDir,
+        log: opts.log,
+      });
+    }
     this.SHUTDOWN_DEADLINE_MS = opts.shutdownDeadlineMs ?? 60_000;
     this.FORK_DEADLINE_MS = opts.forkDeadlineMs ?? 2 * 60 * 60_000;
     this.DISPATCH_DEADLINE_MS = opts.dispatchDeadlineMs ?? 20 * 60_000;
@@ -387,15 +426,30 @@ export class ParallAgentGateway {
       if (data.assignee_id !== this.opts.agentUserId) return;
       if (data.status !== 'todo' && data.status !== 'in_progress') return;
       try {
-        const dispatched = await this.handleTaskAssignment(data, data.id);
-        if (dispatched) {
-          this.opts.client
-            .ackDispatch(this.opts.config.org_id, {
-              source_type: 'task_activity',
-              source_id: data.id,
-            })
-            .catch(() => {});
-        }
+        // Prefer the exact WorkItem id the server threads through the event —
+        // a task PATCH can enqueue sibling task_assign + task_update rows
+        // under the same (task_activity, task_id) source tuple, and source-
+        // level claim/ack would consume or clear the wrong sibling.
+        await this.consumeTypedDispatch(
+          data.dispatch_event_id
+            ? { dispatchEventId: data.dispatch_event_id }
+            : { sourceType: 'task_activity', sourceId: data.id },
+          (dispatchEventId) => this.handleTaskAssignment(data, data.id, dispatchEventId),
+          (dispatchEventId) => {
+            if (dispatchEventId) {
+              this.opts.client
+                .ackDispatchByID(this.opts.config.org_id, dispatchEventId)
+                .catch(() => {});
+              return;
+            }
+            this.opts.client
+              .ackDispatch(this.opts.config.org_id, {
+                source_type: 'task_activity',
+                source_id: data.id,
+              })
+              .catch(() => {});
+          },
+        );
       } catch (err) {
         this.opts.log?.error(`task dispatch failed for ${data.id}: ${String(err)}`);
       }
@@ -405,15 +459,19 @@ export class ParallAgentGateway {
       if (data.event_type === 'task_comment') {
         if (!data.source_id || !data.task_id) return;
         try {
-          const dispatched = await this.handleTaskComment(
-            data.source_id,
-            data.task_id,
-            data.actor_id,
-            data.delivery_reason,
+          await this.consumeTypedDispatch(
+            { dispatchEventId: data.id },
+            () =>
+              this.handleTaskComment(
+                data.source_id,
+                data.task_id ?? '',
+                data.actor_id,
+                data.delivery_reason,
+              ),
+            () => {
+              this.opts.client.ackDispatchByID(this.opts.config.org_id, data.id).catch(() => {});
+            },
           );
-          if (dispatched) {
-            this.opts.client.ackDispatchByID(this.opts.config.org_id, data.id).catch(() => {});
-          }
         } catch (err) {
           this.opts.log?.error(
             `task comment dispatch failed for ${data.source_id}: ${String(err)}`,
@@ -422,14 +480,13 @@ export class ParallAgentGateway {
       } else if (data.event_type === 'wiki_comment') {
         if (!data.source_id) return;
         try {
-          const dispatched = await this.handleWikiComment(
-            data.source_id,
-            data.actor_id,
-            data.delivery_reason,
+          await this.consumeTypedDispatch(
+            { dispatchEventId: data.id },
+            () => this.handleWikiComment(data.source_id, data.actor_id, data.delivery_reason),
+            () => {
+              this.opts.client.ackDispatchByID(this.opts.config.org_id, data.id).catch(() => {});
+            },
           );
-          if (dispatched) {
-            this.opts.client.ackDispatchByID(this.opts.config.org_id, data.id).catch(() => {});
-          }
         } catch (err) {
           this.opts.log?.error(
             `wiki comment dispatch failed for ${data.source_id}: ${String(err)}`,
@@ -438,24 +495,30 @@ export class ParallAgentGateway {
       } else if (data.event_type === 'task_update') {
         if (!data.task_id) return;
         try {
-          const dispatched = await this.handleTaskDispatch(
-            data.task_id,
-            data.source_id ?? data.task_id,
-            { allowCreator: true },
+          await this.consumeTypedDispatch(
+            { dispatchEventId: data.id },
+            (dispatchEventId) =>
+              this.handleTaskDispatch(data.task_id ?? '', data.source_id ?? data.task_id ?? '', {
+                allowCreator: true,
+                dispatchEventId,
+              }),
+            () => {
+              this.opts.client.ackDispatchByID(this.opts.config.org_id, data.id).catch(() => {});
+            },
           );
-          if (dispatched) {
-            this.opts.client.ackDispatchByID(this.opts.config.org_id, data.id).catch(() => {});
-          }
         } catch (err) {
           this.opts.log?.error(`task update dispatch failed for ${data.task_id}: ${String(err)}`);
         }
       } else if (data.event_type === 'schedule.fire') {
         if (!data.source_id) return;
         try {
-          const dispatched = await this.fetchAndHandleScheduleFire(data.source_id, data.actor_id);
-          if (dispatched) {
-            this.opts.client.ackDispatchByID(this.opts.config.org_id, data.id).catch(() => {});
-          }
+          await this.consumeTypedDispatch(
+            { dispatchEventId: data.id },
+            () => this.fetchAndHandleScheduleFire(data.source_id, data.actor_id),
+            () => {
+              this.opts.client.ackDispatchByID(this.opts.config.org_id, data.id).catch(() => {});
+            },
+          );
         } catch (err) {
           this.opts.log?.error(
             `schedule fire dispatch failed for ${data.source_id}: ${String(err)}`,
@@ -464,31 +527,67 @@ export class ParallAgentGateway {
       } else if (data.event_type === 'external_trigger') {
         if (!data.source_id) return;
         try {
-          const dispatched = await this.fetchAndHandleExternalTriggerRun(data.source_id);
-          if (dispatched) {
-            this.opts.client.ackDispatchByID(this.opts.config.org_id, data.id).catch(() => {});
-          }
+          await this.consumeTypedDispatch(
+            { dispatchEventId: data.id },
+            () => this.fetchAndHandleExternalTriggerRun(data.source_id),
+            () => {
+              this.opts.client.ackDispatchByID(this.opts.config.org_id, data.id).catch(() => {});
+            },
+          );
         } catch (err) {
           this.opts.log?.error(
             `external trigger dispatch failed for ${data.source_id}: ${String(err)}`,
           );
         }
+      } else if (data.event_type === 'channel_message') {
+        if (!data.source_id) return;
+        try {
+          await this.consumeTypedDispatch(
+            { dispatchEventId: data.id },
+            () => this.fetchAndHandleChannelMessage(data.source_id),
+            () => {
+              this.opts.client.ackDispatchByID(this.opts.config.org_id, data.id).catch(() => {});
+            },
+          );
+        } catch (err) {
+          this.opts.log?.error(
+            `channel message dispatch failed for ${data.source_id}: ${String(err)}`,
+          );
+        }
       } else if (data.event_type === 'approval_decided') {
         if (!data.source_id) return;
         try {
-          const dispatched = await this.fetchAndHandleApprovalDecided(
-            data.source_id,
-            data.actor_id,
-            data.chat_id ?? null,
+          await this.consumeTypedDispatch(
+            { dispatchEventId: data.id },
+            () =>
+              this.fetchAndHandleApprovalDecided(
+                data.source_id,
+                data.actor_id,
+                data.chat_id ?? null,
+              ),
+            () => {
+              this.opts.client.ackDispatchByID(this.opts.config.org_id, data.id).catch(() => {});
+            },
           );
-          if (dispatched) {
-            this.opts.client.ackDispatchByID(this.opts.config.org_id, data.id).catch(() => {});
-          }
         } catch (err) {
           this.opts.log?.error(
             `approval decided dispatch failed for ${data.source_id}: ${String(err)}`,
           );
         }
+      } else if (
+        data.event_type === 'message' &&
+        this.laneLedger &&
+        data.source_id &&
+        data.chat_id
+      ) {
+        // Ledger re-drive hint: a pending message WorkItem re-published after
+        // a same-target lane completed (claim previously refused, or a steer
+        // failed). Live first delivery stays on the message.new handler.
+        try {
+          await this.handleMessageRedrive(data);
+        } catch (err) {
+          this.opts.log?.error(`message re-drive failed for ${data.source_id}: ${String(err)}`);
+        }
       } else if (data.event_type !== 'message' && data.event_type !== 'task_assign') {
         // Truly unknown event_type — log so a newly-added dispatch type
         // not yet wired here surfaces during runtime testing. "message"
@@ -536,6 +635,61 @@ export class ParallAgentGateway {
     });
   }
 
+  /** True when this event's lifecycle is owned by the dispatch lane ledger. */
+  private usesLaneLedger(event: ParallEvent): boolean {
+    return this.laneLedger != null && !this.ledgerDisabled && this.laneLedger.handles(event);
+  }
+
+  private disableLedger(reason: string) {
+    if (this.ledgerDisabled) return;
+    this.ledgerDisabled = true;
+    this.opts.log?.warn(
+      `dispatch ledger unavailable (${reason}) — falling back to legacy received/ack flow`,
+    );
+  }
+
+  /**
+   * Buffer grouping key. Lane-ledger message events group by full lane
+   * identity (chat + thread) so a channel lane and a thread lane in the same
+   * chat dispatch as separate turns with separate claims; everything else
+   * keeps the historical chat-level grouping.
+   */
+  private dispatchGroupKey(event: ParallEvent): string {
+    if (this.usesLaneLedger(event)) {
+      // MUST be the lane identity itself (lane-key SSOT): the mid-turn
+      // injection gate compares this against mainCurrentGroupKey, and a
+      // grouping key that drifted from lane identity would fold two lanes
+      // into one turn.
+      return this.laneLedger!.laneKeyFor(event);
+    }
+    return event.targetId;
+  }
+
+  // Lane-flow protocols live in gateway-lane-flow.ts; these thin delegates
+  // keep call sites and tests on the class surface.
+  private laneFlowHost(): LaneFlowHost {
+    return this as unknown as LaneFlowHost;
+  }
+
+  private dispatchLaneGroup(opts: {
+    events: ParallEvent[];
+    sessionKey: string;
+    body: string;
+    earlier: ParallEvent[];
+    captureText?: string[];
+    hasMoreLocal: () => boolean;
+  }): Promise<'dispatched' | 'foreign' | 'shutdown'> {
+    return dispatchLaneGroup(this.laneFlowHost(), opts);
+  }
+
+  private consumeTypedDispatch(
+    ref: { dispatchEventId?: string; sourceType?: string; sourceId?: string },
+    run: (dispatchEventId?: string) => Promise<boolean>,
+    ack: (dispatchEventId?: string) => void,
+  ): Promise<void> {
+    return consumeTypedDispatch(this.laneFlowHost(), ref, run, ack);
+  }
+
   private buildDispatchContext(event: ParallEvent, sessionKey: string): DispatchContext {
     const binding = this.sessionBindings.get(sessionKey);
     return {
@@ -552,6 +706,7 @@ export class ParallAgentGateway {
       noReply: event.noReply ?? false,
       contextFilePath: this.opts.contextFilePathForSession?.(sessionKey),
       stepIdFilePath: this.opts.stepIdFilePathForSession?.(sessionKey),
+      contextDirPath: this.opts.dispatchContextDir,
       client: this.opts.client,
       log: this.opts.log,
     };
@@ -588,9 +743,11 @@ export class ParallAgentGateway {
                       ? 'schedule_fire'
                       : event.type === 'external_trigger'
                         ? 'external_trigger'
-                        : event.type === 'approval'
-                          ? 'approval_decided'
-                          : 'mention',
+                        : event.type === 'channel_message'
+                          ? 'channel_message'
+                          : event.type === 'approval'
+                            ? 'approval_decided'
+                            : 'mention',
             trigger_ref:
               event.type === 'task'
                 ? { task_id: event.targetId }
@@ -607,9 +764,16 @@ export class ParallAgentGateway {
                             connection_id: event.externalConnectionId,
                             ingress_event_id: event.externalIngressEventId,
                           }
-                        : event.type === 'approval'
-                          ? { approval_id: event.messageId }
-                          : { message_id: event.messageId },
+                        : event.type === 'channel_message'
+                          ? {
+                              conversation_id: event.targetId,
+                              channel_message_id: event.messageId,
+                              provider: event.channelProvider,
+                              external_conversation_id: event.channelExternalConversationId,
+                            }
+                          : event.type === 'approval'
+                            ? { approval_id: event.messageId }
+                            : { message_id: event.messageId },
             sender_id: event.senderId,
             sender_name: event.senderName,
             summary: event.body.substring(0, 200),
@@ -629,6 +793,7 @@ export class ParallAgentGateway {
     runtimeEvent: RuntimeEvent,
     stepIdFilePath?: string,
     contextFilePath?: string,
+    laneContextFilePath?: string,
   ) {
     const target = resolveStepTarget(event);
     try {
@@ -692,6 +857,9 @@ export class ParallAgentGateway {
           } else if (stepIdFilePath) {
             this.writeStepIdFile(stepIdFilePath, step.id);
           }
+          if (laneContextFilePath) {
+            this.updateContextFileStepId(laneContextFilePath, step.id);
+          }
           break;
         }
 
@@ -720,6 +888,9 @@ export class ParallAgentGateway {
           } else if (stepIdFilePath) {
             this.clearStepIdFile(stepIdFilePath);
           }
+          if (laneContextFilePath) {
+            this.updateContextFileStepId(laneContextFilePath, null);
+          }
           break;
 
         case 'error':
@@ -803,6 +974,7 @@ export class ParallAgentGateway {
     sessionKey: string,
     runtimeEvent: Extract<RuntimeEvent, { type: 'runtime_session' }>,
     contextFilePath?: string,
+    laneContextFilePath?: string,
   ): Promise<AgentSessionBinding> {
     const runtimeLaneKey = runtimeEvent.runtimeLaneKey || sessionKey;
     const existing = this.sessionBindings.get(sessionKey);
@@ -864,6 +1036,9 @@ export class ParallAgentGateway {
     if (contextFilePath) {
       this.updateContextFileSessionId(contextFilePath, session.id);
     }
+    if (laneContextFilePath) {
+      this.updateContextFileSessionId(laneContextFilePath, session.id);
+    }
     await this.opts.onSessionBinding?.(binding);
     return binding;
   }
@@ -907,14 +1082,33 @@ export class ParallAgentGateway {
       const contextFilePath = dispatchContext.contextFilePath;
       const stepIdFilePath = dispatchContext.stepIdFilePath;
 
+      // Per-lane context (PRLL_CONTEXT_DIR contract): additive dispatch/lane
+      // fields ride along in both files; the per-session file stays as the
+      // PRLL_CONTEXT_FILE compat read path.
+      const activeLane = this.ledgerDisabled ? undefined : this.laneLedger?.getForEvent(event);
+      const laneContextFilePath = activeLane
+        ? this.laneLedger?.laneContextPath(activeLane)
+        : undefined;
+      const contextBody = {
+        session_id: dispatchContext.sessionId ?? null,
+        chat_id: dispatchContext.chatId ?? null,
+        trigger_message_id: dispatchContext.triggerMessageId ?? null,
+        no_reply: dispatchContext.noReply,
+        step_id: null,
+        dispatch_event_id:
+          activeLane?.typedDispatchEventId ?? activeLane?.folded.get(event.messageId) ?? null,
+        lane: activeLane?.lane ?? null,
+        target_uri: activeLane?.targetUri ?? null,
+        thread_root_id: activeLane?.threadRootId ?? null,
+        // Typed binding hint for the CLI: which task this dispatch is about
+        // (parall task update attaches the typed effect only on a match).
+        task_id: event.type === 'task' ? event.targetId : null,
+      };
       if (contextFilePath) {
-        this.writeContextFile(contextFilePath, {
-          session_id: dispatchContext.sessionId ?? null,
-          chat_id: dispatchContext.chatId ?? null,
-          trigger_message_id: dispatchContext.triggerMessageId ?? null,
-          no_reply: dispatchContext.noReply,
-          step_id: null,
-        });
+        this.writeContextFile(contextFilePath, contextBody);
+      }
+      if (laneContextFilePath) {
+        this.writeContextFile(laneContextFilePath, contextBody);
       }
 
       // sync: no await between the shuttingDown check above and this increment
@@ -951,7 +1145,32 @@ export class ParallAgentGateway {
           context: dispatchContext,
         })) {
           if (runtimeEvent.type === 'runtime_session') {
-            binding = await this.bindRuntimeSession(sessionKey, runtimeEvent, contextFilePath);
+            const priorAgentSessionId = binding?.agentSessionId;
+            binding = await this.bindRuntimeSession(
+              sessionKey,
+              runtimeEvent,
+              contextFilePath,
+              laneContextFilePath,
+            );
+            if (
+              event.targetType === 'channel_conversation' &&
+              binding.agentSessionId !== priorAgentSessionId
+            ) {
+              // Record the durable chv_ ↔ ase_ mapping (ops drill-down from a
+              // conversation into its session). Best-effort bookkeeping —
+              // never fail the dispatch over it.
+              try {
+                await this.opts.client.setChannelConversationSession(
+                  this.opts.config.org_id,
+                  event.targetId,
+                  binding.agentSessionId,
+                );
+              } catch (err) {
+                this.opts.log?.warn(
+                  `failed to record session mapping for channel conversation ${event.targetId}: ${String(err)}`,
+                );
+              }
+            }
             if (!inputStepsCreated) {
               // Persist input steps for "earlier events" (batched events that arrived
               // while a dispatch was in flight) inside the in-flight window so a
@@ -988,6 +1207,12 @@ export class ParallAgentGateway {
             await this.createInputStep(binding.agentSessionId, event);
             inputStepsCreated = true;
           }
+          // Long-turn keepalive: any runtime activity renews the lane lease
+          // (throttled in the ledger) so a legitimately long turn is not
+          // dethroned at TTL.
+          if (activeLane && !this.ledgerDisabled) {
+            this.laneLedger?.maybeRenew(activeLane);
+          }
           if (captureText && runtimeEvent.type === 'text' && runtimeEvent.text) {
             captureText.push(runtimeEvent.text);
           }
@@ -1013,6 +1238,7 @@ export class ParallAgentGateway {
             runtimeEvent,
             stepIdFilePath,
             contextFilePath,
+            laneContextFilePath,
           );
         }
         if (!binding) {
@@ -1041,6 +1267,7 @@ export class ParallAgentGateway {
               },
               stepIdFilePath,
               contextFilePath,
+              laneContextFilePath,
             );
           } catch (stepErr) {
             if (this.isSessionNotLiveError(stepErr)) staleDetected = true;
@@ -1105,6 +1332,9 @@ export class ParallAgentGateway {
         } else if (stepIdFilePath) {
           this.clearStepIdFile(stepIdFilePath);
         }
+        if (laneContextFilePath) {
+          this.updateContextFileStepId(laneContextFilePath, null);
+        }
         this.inFlightDispatches--;
         if (this.inFlightDispatches === 0 && this.drainResolvers.length > 0) {
           const resolvers = this.drainResolvers.splice(0);
@@ -1174,19 +1404,47 @@ export class ParallAgentGateway {
           for (const item of fork.queue.splice(0)) item.resolve(false);
           break;
         }
-        const items = fork.queue.splice(0);
+        // Lane-ledger message events batch per lane identity (chat + thread)
+        // so a fork's claim/steer/complete always addresses one lane.
+        let items: ForkQueueItem[];
+        const head = fork.queue[0];
+        if (head && this.usesLaneLedger(head.event)) {
+          const headKey = this.dispatchGroupKey(head.event);
+          const splitAt = fork.queue.findIndex((it) => this.dispatchGroupKey(it.event) !== headKey);
+          items = splitAt === -1 ? fork.queue.splice(0) : fork.queue.splice(0, splitAt);
+        } else {
+          items = fork.queue.splice(0);
+        }
         const events = items.map((item) => item.event);
         const last = events[events.length - 1];
         const earlier = events.slice(0, -1);
         try {
           const batchText: string[] = [];
-          const dispatched = await this.runDispatch(
-            last,
-            fork.fork.sessionKey,
-            buildForkScopePrefix(last) + buildEventBody(last),
-            earlier,
-            batchText,
-          );
+          let dispatched: boolean;
+          if (this.usesLaneLedger(last)) {
+            const outcome = await this.dispatchLaneGroup({
+              events,
+              sessionKey: fork.fork.sessionKey,
+              body: buildForkScopePrefix(last) + buildEventBody(last),
+              earlier,
+              captureText: batchText,
+              hasMoreLocal: () => fork.queue.length > 0,
+            });
+            if (outcome === 'foreign') {
+              // Another pod owns the lane — the events stay pending server-side.
+              for (const item of items) item.resolve(false);
+              break;
+            }
+            dispatched = outcome === 'dispatched';
+          } else {
+            dispatched = await this.runDispatch(
+              last,
+              fork.fork.sessionKey,
+              buildForkScopePrefix(last) + buildEventBody(last),
+              earlier,
+              batchText,
+            );
+          }
           if (!dispatched) {
             // Shutdown short-circuit — resolve un-acked so the server requeues
             // for the replacement pod and stop draining further items.
@@ -1306,9 +1564,12 @@ export class ParallAgentGateway {
           break;
         }
 
-        const targetId = this.dispatchState.mainBuffer[0].targetId;
+        const groupKey = this.dispatchGroupKey(this.dispatchState.mainBuffer[0]);
         const events: ParallEvent[] = [];
-        while (this.dispatchState.mainBuffer[0]?.targetId === targetId) {
+        while (
+          this.dispatchState.mainBuffer[0] &&
+          this.dispatchGroupKey(this.dispatchState.mainBuffer[0]) === groupKey
+        ) {
           events.push(this.dispatchState.mainBuffer.shift()!);
         }
 
@@ -1321,9 +1582,42 @@ export class ParallAgentGateway {
           : this.dispatchState.pendingForkResults.splice(0);
         const forkPrefix = buildForkResultPrefix(pendingFork);
         this.dispatchState.mainCurrentTargetId = event.targetId;
+        this.mainCurrentGroupKey = groupKey;
         this.dispatchState.mainPreDispatchBranchPoint = this.opts.dispatchAdapter.getBranchPoint?.(
           this.opts.runtimeKey,
         );
+        if (this.usesLaneLedger(event)) {
+          let outcome: 'dispatched' | 'foreign' | 'shutdown';
+          try {
+            outcome = await this.dispatchLaneGroup({
+              events,
+              sessionKey: this.opts.runtimeKey,
+              body: forkPrefix + buildEventBody(event),
+              earlier,
+              hasMoreLocal: () =>
+                this.dispatchState.mainBuffer.some((e) => this.dispatchGroupKey(e) === groupKey),
+            });
+          } catch (err) {
+            // The lane was released inside dispatchLaneGroup — members are
+            // pending again server-side; drop them locally and move on.
+            this.opts.log?.error(`lane dispatch failed for ${event.messageId}: ${String(err)}`);
+            this.dispatchState.pendingForkResults.unshift(...pendingFork);
+            for (const ev of events) this.dispatchedMessages.delete(ev.messageId);
+            continue;
+          }
+          if (outcome === 'shutdown') {
+            this.dispatchState.mainBuffer.unshift(...events);
+            this.dispatchState.pendingForkResults.unshift(...pendingFork);
+            break;
+          }
+          if (outcome === 'foreign') {
+            this.dispatchState.pendingForkResults.unshift(...pendingFork);
+            continue;
+          }
+          // Dispatched — resolution happened server-side (reply cover or
+          // no_action sweep); no legacy acks.
+          continue;
+        }
         try {
           await this.emitDispatchReceived(event);
         } catch (err) {
@@ -1365,6 +1659,7 @@ export class ParallAgentGateway {
       this.draining = false;
       this.dispatchState.mainDispatching = false;
       this.dispatchState.mainCurrentTargetId = undefined;
+      this.mainCurrentGroupKey = undefined;
       this.dispatchState.mainPreDispatchBranchPoint = undefined;
       if (!this.shuttingDown && this.dispatchState.mainBuffer.length > 0) {
         // Opportunistic re-drain — best-effort, not a recovery deadline, so it
@@ -1397,18 +1692,50 @@ export class ParallAgentGateway {
         const forkPrefix = buildForkResultPrefix(pendingFork);
         this.dispatchState.mainDispatching = true;
         this.dispatchState.mainCurrentTargetId = event.targetId;
+        this.mainCurrentGroupKey = this.dispatchGroupKey(event);
         // Snapshot the on-disk branch point BEFORE runDispatch starts writing
         // to the session file. Fork sessions created while main is in-flight
         // use this to branch from the clean pre-dispatch state.
         this.dispatchState.mainPreDispatchBranchPoint = this.opts.dispatchAdapter.getBranchPoint?.(
           this.opts.runtimeKey,
         );
+        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' = 'shutdown';
+          try {
+            try {
+              outcome = await this.dispatchLaneGroup({
+                events: [event],
+                sessionKey: this.opts.runtimeKey,
+                body: forkPrefix + buildEventBody(event),
+                earlier: [],
+                hasMoreLocal: () =>
+                  this.dispatchState.mainBuffer.some(
+                    (e) => this.dispatchGroupKey(e) === this.dispatchGroupKey(event),
+                  ),
+              });
+            } catch (err) {
+              // Same failure contract as the buffered-group path: accumulated
+              // fork results must survive a failed turn for later replay.
+              this.dispatchState.pendingForkResults.unshift(...pendingFork);
+              throw err;
+            }
+            if (outcome !== 'dispatched') {
+              this.dispatchState.pendingForkResults.unshift(...pendingFork);
+            }
+          } finally {
+            await this.drainMainBuffer();
+          }
+          return outcome === 'dispatched';
+        }
         try {
           await this.emitDispatchReceived(event);
         } catch (err) {
           this.opts.log?.warn?.(`mark-received failed, leaving unacked for retry: ${String(err)}`);
           this.dispatchState.mainDispatching = false;
           this.dispatchState.mainCurrentTargetId = undefined;
+          this.mainCurrentGroupKey = undefined;
           this.dispatchState.mainPreDispatchBranchPoint = undefined;
           this.dispatchState.pendingForkResults.unshift(...pendingFork);
           return false;
@@ -1439,7 +1766,26 @@ export class ParallAgentGateway {
         // arrival order is preserved and the event cannot be orphaned in a
         // gap between the steer await and the push.
         this.dispatchState.mainBuffer.push(event);
-        if (
+        if (this.usesLaneLedger(event)) {
+          // Ledger flow: fold into the live lane server-side FIRST, then
+          // inject. An un-folded injection is forbidden (the pending WorkItem
+          // would re-drive after complete and be handled twice); a failed
+          // fold leaves the event buffered — the drain claims it as its own
+          // turn. Injection requires an exact lane match (same chat AND same
+          // thread) — a thread message never rides a channel turn.
+          if (
+            this.mainCurrentGroupKey === this.dispatchGroupKey(event) &&
+            (await this.laneLedger?.steerLive(event)) &&
+            (await this.opts.dispatchAdapter.enqueueDuringDispatch?.(
+              this.opts.runtimeKey,
+              buildEventBody(event),
+            ))
+          ) {
+            this.opts.log?.info(
+              `steer folded+injected for ${event.messageId} (will drain for bookkeeping)`,
+            );
+          }
+        } else if (
           this.dispatchState.mainCurrentTargetId === event.targetId &&
           (await this.opts.dispatchAdapter.enqueueDuringDispatch?.(
             this.opts.runtimeKey,
@@ -1649,9 +1995,13 @@ export class ParallAgentGateway {
     try {
       const dispatched = await this.handleInboundEvent(event);
       if (dispatched) {
-        this.opts.client
-          .ackDispatch(this.opts.config.org_id, { source_type: 'message', source_id: data.id })
-          .catch(() => {});
+        // Ledger events resolve server-side (reply cover / no_action sweep);
+        // the legacy by-source ack is only for non-ledger runtimes.
+        if (!this.usesLaneLedger(event)) {
+          this.opts.client
+            .ackDispatch(this.opts.config.org_id, { source_type: 'message', source_id: data.id })
+            .catch(() => {});
+        }
       } else {
         this.dispatchedMessages.delete(data.id);
       }
@@ -1661,7 +2011,30 @@ export class ParallAgentGateway {
     }
   }
 
-  private async handleTaskAssignment(task: Task, ackSourceId?: string): Promise<boolean> {
+  // Ledger re-drive consumption: dispatch.new message hints re-enter the
+  // shared WorkItem consumption path (same protocol as catch-up).
+  private async handleMessageRedrive(item: DispatchNewData): Promise<void> {
+    if (!item.chat_id || !item.source_id) return;
+    await this.consumeMessageWorkItem({
+      id: item.id,
+      source_id: item.source_id,
+      chat_id: item.chat_id,
+    });
+  }
+
+  private consumeMessageWorkItem(item: {
+    id: string;
+    source_id: string;
+    chat_id: string;
+  }): Promise<void> {
+    return consumeMessageWorkItem(this.laneFlowHost(), item);
+  }
+
+  private async handleTaskAssignment(
+    task: Task,
+    ackSourceId?: string,
+    dispatchEventId?: string,
+  ): Promise<boolean> {
     if (this.shuttingDown) return false; // drain window — let server requeue via catch-up
     const dedupeKey = `${task.id}:${task.updated_at}`;
     if (this.dispatchedTasks.has(dedupeKey)) {
@@ -1689,6 +2062,7 @@ export class ParallAgentGateway {
       sentAt: task.updated_at ?? task.created_at,
       ackSourceType: 'task_activity',
       ackSourceId,
+      dispatchEventId,
     };
 
     const dispatched = await this.handleInboundEvent(event);
@@ -1701,7 +2075,7 @@ export class ParallAgentGateway {
   private async handleTaskDispatch(
     taskId: string,
     ackSourceId?: string,
-    opts: { allowCreator?: boolean } = {},
+    opts: { allowCreator?: boolean; dispatchEventId?: string } = {},
   ): Promise<boolean> {
     let task: Awaited<ReturnType<typeof this.opts.client.getTask>> | null = null;
     try {
@@ -1719,7 +2093,7 @@ export class ParallAgentGateway {
       );
       return true;
     }
-    return this.handleTaskAssignment(task, ackSourceId);
+    return this.handleTaskAssignment(task, ackSourceId, opts.dispatchEventId);
   }
 
   private async handleTaskComment(
@@ -1976,6 +2350,98 @@ export class ParallAgentGateway {
     return this.handleExternalTriggerRun(run);
   }
 
+  // fetchAndHandleChannelMessage resolves a channel_message dispatch to its
+  // durable ChannelMessage + conversation and hands it to the inbound
+  // pipeline. targetId = the ChannelConversation id, so per-conversation
+  // multi-turn continuity rides the same per-target session mechanics as
+  // chats. Design: docs/engineering-design/external-im-channel-design.md.
+  private async fetchAndHandleChannelMessage(messageId: string): Promise<boolean> {
+    if (this.shuttingDown) return false;
+    // Capped dedupe (the chat-message path, not the unbounded task set): a busy
+    // external IM conversation would otherwise retain one key per message ever
+    // handled on a long-lived agent. On a RETRYABLE failure the claim is
+    // released so a later dispatch.new / catch-up re-fetches (matching the
+    // chat-message path); a 404/stale result keeps the claim and acks.
+    const claimKey = `channel_message:${messageId}`;
+    if (!this.tryClaimMessage(claimKey)) return false;
+
+    let msg: ChannelMessage | null = null;
+    let conv: ChannelConversation | null = null;
+    try {
+      msg = await this.opts.client.getChannelMessage(this.opts.config.org_id, messageId);
+      conv = await this.opts.client.getChannelConversation(
+        this.opts.config.org_id,
+        msg.conversation_id,
+      );
+    } catch (err: unknown) {
+      const status = (err as { status?: number })?.status;
+      if (status === 404) {
+        this.opts.log?.warn(
+          `channel message ${messageId} not accessible (404), acking stale dispatch`,
+        );
+        return true;
+      }
+      this.dispatchedMessages.delete(claimKey);
+      this.opts.log?.warn(
+        `channel message fetch failed for ${messageId}, leaving pending: ${String(err)}`,
+      );
+      return false;
+    }
+    if (!msg || !conv) {
+      return true;
+    }
+    this.opts.log?.info(`channel message: ${msg.id} (conversation ${conv.id})`);
+
+    // Resolve the provider from the conversation's connection for prompt
+    // labeling + the reply-clip hint. The connection id → provider mapping
+    // is stable, so a tiny cache avoids one fetch per message.
+    let provider = this.channelConnectionProviders.get(conv.connection_id);
+    if (!provider) {
+      try {
+        const connection = await this.opts.client.getChannelConnection(
+          this.opts.config.org_id,
+          conv.connection_id,
+        );
+        provider = connection.provider;
+        this.channelConnectionProviders.set(conv.connection_id, provider);
+      } catch {
+        provider = undefined; // label degrades; reply hint still names the clip generically
+      }
+    }
+
+    const event: ParallEvent = {
+      type: 'channel_message',
+      targetId: conv.id,
+      targetName: conv.external_user_name || conv.external_conversation_id,
+      targetType: 'channel_conversation',
+      senderId: msg.external_user_id || 'external',
+      senderName: msg.external_user_name || msg.external_user_id || 'external user',
+      messageId: msg.id,
+      body: msg.text,
+      sentAt: msg.received_at,
+      channelProvider: provider,
+      channelConversationType: conv.conversation_type || undefined,
+      channelExternalConversationId: conv.external_conversation_id,
+      channelExternalMessageId: msg.external_message_id,
+      ackSourceType: 'channel_message',
+      ackSourceId: msg.id,
+    };
+
+    // Release the claim if the event isn't actually dispatched (or throws) so
+    // a retry can re-attempt — same contract as the chat-message path.
+    let dispatched: boolean;
+    try {
+      dispatched = await this.handleInboundEvent(event);
+    } catch (err) {
+      this.dispatchedMessages.delete(claimKey);
+      throw err;
+    }
+    if (!dispatched) {
+      this.dispatchedMessages.delete(claimKey);
+    }
+    return dispatched;
+  }
+
   private async handleExternalTriggerRun(run: ExternalTriggerRun): Promise<boolean> {
     if (this.shuttingDown) return false;
     const dedupeKey = `external_trigger_run:${run.id}`;
@@ -2129,12 +2595,22 @@ export class ParallAgentGateway {
 
         processed++;
         try {
-          let dispatched = false;
+          const ackItem = () => {
+            this.opts.client.ackDispatchByID(this.opts.config.org_id, item.id).catch(() => {});
+          };
           if (item.event_type === 'task_assign' && item.task_id) {
             try {
-              dispatched = await this.handleTaskDispatch(
-                item.task_id,
-                item.source_id ?? item.task_id,
+              await this.consumeTypedDispatch(
+                { dispatchEventId: item.id },
+                (dispatchEventId) =>
+                  this.handleTaskDispatch(
+                    item.task_id ?? '',
+                    item.source_id ?? item.task_id ?? '',
+                    {
+                      dispatchEventId,
+                    },
+                  ),
+                ackItem,
               );
             } catch (err: unknown) {
               this.opts.log?.warn(
@@ -2144,10 +2620,18 @@ export class ParallAgentGateway {
             }
           } else if (item.event_type === 'task_update' && item.task_id) {
             try {
-              dispatched = await this.handleTaskDispatch(
-                item.task_id,
-                item.source_id ?? item.task_id,
-                { allowCreator: true },
+              await this.consumeTypedDispatch(
+                { dispatchEventId: item.id },
+                (dispatchEventId) =>
+                  this.handleTaskDispatch(
+                    item.task_id ?? '',
+                    item.source_id ?? item.task_id ?? '',
+                    {
+                      allowCreator: true,
+                      dispatchEventId,
+                    },
+                  ),
+                ackItem,
               );
             } catch (err: unknown) {
               this.opts.log?.warn(
@@ -2156,70 +2640,58 @@ export class ParallAgentGateway {
               continue;
             }
           } else if (item.event_type === 'task_comment' && item.source_id && item.task_id) {
-            dispatched = await this.handleTaskComment(
-              item.source_id,
-              item.task_id,
-              item.actor_id,
-              item.delivery_reason,
+            await this.consumeTypedDispatch(
+              { dispatchEventId: item.id },
+              () =>
+                this.handleTaskComment(
+                  item.source_id,
+                  item.task_id ?? '',
+                  item.actor_id,
+                  item.delivery_reason,
+                ),
+              ackItem,
             );
           } else if (item.event_type === 'wiki_comment' && item.source_id) {
-            dispatched = await this.handleWikiComment(
-              item.source_id,
-              item.actor_id,
-              item.delivery_reason,
+            await this.consumeTypedDispatch(
+              { dispatchEventId: item.id },
+              () => this.handleWikiComment(item.source_id, item.actor_id, item.delivery_reason),
+              ackItem,
             );
           } else if (item.event_type === 'schedule.fire' && item.source_id) {
-            dispatched = await this.fetchAndHandleScheduleFire(item.source_id, item.actor_id);
+            await this.consumeTypedDispatch(
+              { dispatchEventId: item.id },
+              () => this.fetchAndHandleScheduleFire(item.source_id, item.actor_id),
+              ackItem,
+            );
           } else if (item.event_type === 'external_trigger' && item.source_id) {
-            dispatched = await this.fetchAndHandleExternalTriggerRun(item.source_id);
+            await this.consumeTypedDispatch(
+              { dispatchEventId: item.id },
+              () => this.fetchAndHandleExternalTriggerRun(item.source_id),
+              ackItem,
+            );
+          } else if (item.event_type === 'channel_message' && item.source_id) {
+            await this.consumeTypedDispatch(
+              { dispatchEventId: item.id },
+              () => this.fetchAndHandleChannelMessage(item.source_id),
+              ackItem,
+            );
           } else if (item.event_type === 'approval_decided' && item.source_id) {
-            dispatched = await this.fetchAndHandleApprovalDecided(
-              item.source_id,
-              item.actor_id,
-              item.chat_id ?? null,
+            await this.consumeTypedDispatch(
+              { dispatchEventId: item.id },
+              () =>
+                this.fetchAndHandleApprovalDecided(
+                  item.source_id,
+                  item.actor_id,
+                  item.chat_id ?? null,
+                ),
+              ackItem,
             );
           } else if (item.event_type === 'message' && item.source_id && item.chat_id) {
-            if (!this.tryClaimMessage(item.source_id)) continue;
-            let msg: Awaited<ReturnType<typeof this.opts.client.getMessage>> | null = null;
-            let msgFetchFailed = false;
-            try {
-              msg = await this.opts.client.getMessage(item.source_id);
-            } catch (err: unknown) {
-              const status = (err as { status?: number })?.status;
-              if (status === 404) {
-                msg = null;
-              } else {
-                msgFetchFailed = true;
-                this.opts.log?.warn(
-                  `catch-up message fetch failed for ${item.source_id}, leaving pending: ${String(err)}`,
-                );
-              }
-            }
-            if (msgFetchFailed) {
-              this.dispatchedMessages.delete(item.source_id);
-              continue;
-            }
-            if (!msg || msg.sender_id === this.opts.agentUserId) {
-              this.dispatchedMessages.delete(item.source_id);
-              this.opts.client.ackDispatchByID(this.opts.config.org_id, item.id).catch(() => {});
-              continue;
-            }
-
-            const decision = await this.buildMessageDispatchDecision(item.chat_id, msg);
-            if (decision.action === 'retry') {
-              this.dispatchedMessages.delete(item.source_id);
-              continue;
-            }
-            if (decision.action === 'skip') {
-              this.dispatchedMessages.delete(item.source_id);
-              this.opts.client.ackDispatchByID(this.opts.config.org_id, item.id).catch(() => {});
-              continue;
-            }
-
-            dispatched = await this.handleInboundEvent(decision.event);
-          }
-          if (dispatched) {
-            this.opts.client.ackDispatchByID(this.opts.config.org_id, item.id).catch(() => {});
+            await this.consumeMessageWorkItem({
+              id: item.id,
+              source_id: item.source_id,
+              chat_id: item.chat_id,
+            });
           }
         } catch (err) {
           this.opts.log?.warn(
@@ -2307,6 +2779,20 @@ export class ParallAgentGateway {
         this.abortFork(targetId, 'ws reconnect');
       }
     }
+    // Reconnect with nothing in flight: interrupted turns can't resume, so
+    // hand their lane members back to the pending pool before catch-up
+    // re-claims (an in-flight turn keeps its lanes — it is still the owner).
+    if (this.laneLedger && this.inFlightDispatches === 0 && this.laneLedger.activeCount > 0) {
+      log?.info(`releasing ${this.laneLedger.activeCount} stale lane(s) on reconnect`);
+      await this.laneLedger.releaseAll();
+    }
+    // Re-probe the ledger each connection: a sticky downgrade from a
+    // transient edge 404 during a rolling deploy must not outlive the
+    // connection that observed it.
+    if (this.laneLedger && this.ledgerDisabled) {
+      log?.info('re-probing dispatch ledger after reconnect (was disabled)');
+      this.ledgerDisabled = false;
+    }
     const intervalSec = data.heartbeat_interval > 0 ? data.heartbeat_interval : 30;
     try {
       const count = await fetchAllChats(client, config.org_id, this.chatInfoMap);
@@ -2391,6 +2877,14 @@ export class ParallAgentGateway {
 
     if (this.heartbeatTimer) clearInterval(this.heartbeatTimer);
 
+    // Completed turns already released their lanes; whatever is left belongs
+    // to interrupted work — hand the members back so the replacement pod
+    // re-claims immediately instead of waiting out the lease.
+    if (this.laneLedger && this.laneLedger.activeCount > 0) {
+      this.opts.log?.info(`releasing ${this.laneLedger.activeCount} lane(s) on shutdown`);
+      await this.laneLedger.releaseAll();
+    }
+
     await this.opts.onBeforeDisconnect?.();
 
     this.opts.ws.disconnect();