@parall/agent-core 1.36.1 → 1.38.0

package/dist/gateway-base.js

@@ -3,6 +3,8 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { ApiError, MENTION_ALL_USER_ID } from '@parall/sdk';
 import { buildEventBody, buildEventBodyForForkResult, buildForkResultPrefix, buildForkScopePrefix, } from './event-format.js';
+import { consumeMessageWorkItem, consumeTypedDispatch, dispatchLaneGroup, } from './gateway-lane-flow.js';
+import { LaneLedger } from './lane-ledger.js';
 import { routeTrigger } from './routing.js';
 import { clearDispatchMessageId, clearDispatchMetrics, clearDispatchNoReply, clearSessionMessageId, getDispatchMetrics, recordDeliverText, recordMessageSend, recordNoReply, recordToolCall, resetDispatchMetrics, setDispatchMessageId, setDispatchNoReply, setSessionChatId, setSessionMessageId, } from './session-state.js';
 import { isParallSendCommand, isParallNoReplyCommand, extractShellCommand, } from './bridge-workspace.js';
@@ -53,6 +55,9 @@ function resolveStepTarget(event) {
     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 /
@@ -115,6 +120,9 @@ export class ParallAgentGateway {
     opts;
     chatInfoMap = new Map();
     dispatchedTasks = new Set();
+    // connection id → provider alias, for channel_message prompt labeling
+    // (stable mapping; avoids one connection fetch per inbound message).
+    channelConnectionProviders = new Map();
     dispatchedMessages = new Set();
     forkStates = new Map();
     dispatchState = {
@@ -137,6 +145,14 @@ export class ParallAgentGateway {
     inFlightDispatches = 0;
     drainResolvers = [];
     pendingRestartNotification = null;
+    laneLedger;
+    // Sticky fallback: flipped when the server predates the ledger (claim
+    // endpoint 404) so every subsequent dispatch uses the legacy flow.
+    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.
+    mainCurrentGroupKey;
     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
@@ -146,6 +162,14 @@ export class ParallAgentGateway {
     DISPATCH_DEADLINE_MS;
     constructor(opts) {
         this.opts = opts;
+        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;
@@ -222,15 +246,26 @@ export class ParallAgentGateway {
             if (data.status !== 'todo' && data.status !== 'in_progress')
                 return;
             try {
-                const dispatched = await this.handleTaskAssignment(data, data.id);
-                if (dispatched) {
+                // 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)}`);
@@ -241,10 +276,9 @@ export class ParallAgentGateway {
                 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);
-                    if (dispatched) {
+                    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(() => { });
-                    }
+                    });
                 }
                 catch (err) {
                     this.opts.log?.error(`task comment dispatch failed for ${data.source_id}: ${String(err)}`);
@@ -254,10 +288,9 @@ export class ParallAgentGateway {
                 if (!data.source_id)
                     return;
                 try {
-                    const dispatched = await this.handleWikiComment(data.source_id, data.actor_id, data.delivery_reason);
-                    if (dispatched) {
+                    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(() => { });
-                    }
+                    });
                 }
                 catch (err) {
                     this.opts.log?.error(`wiki comment dispatch failed for ${data.source_id}: ${String(err)}`);
@@ -267,10 +300,12 @@ export class ParallAgentGateway {
                 if (!data.task_id)
                     return;
                 try {
-                    const dispatched = await this.handleTaskDispatch(data.task_id, data.source_id ?? data.task_id, { allowCreator: true });
-                    if (dispatched) {
+                    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(() => { });
-                    }
+                    });
                 }
                 catch (err) {
                     this.opts.log?.error(`task update dispatch failed for ${data.task_id}: ${String(err)}`);
@@ -280,10 +315,9 @@ export class ParallAgentGateway {
                 if (!data.source_id)
                     return;
                 try {
-                    const dispatched = await this.fetchAndHandleScheduleFire(data.source_id, data.actor_id);
-                    if (dispatched) {
+                    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)}`);
@@ -293,28 +327,52 @@ export class ParallAgentGateway {
                 if (!data.source_id)
                     return;
                 try {
-                    const dispatched = await this.fetchAndHandleExternalTriggerRun(data.source_id);
-                    if (dispatched) {
+                    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);
-                    if (dispatched) {
+                    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(() => { });
-                    }
+                    });
                 }
                 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"
@@ -357,6 +415,43 @@ export class ParallAgentGateway {
             source_id: sourceId,
         });
     }
+    /** True when this event's lifecycle is owned by the dispatch lane ledger. */
+    usesLaneLedger(event) {
+        return this.laneLedger != null && !this.ledgerDisabled && this.laneLedger.handles(event);
+    }
+    disableLedger(reason) {
+        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.
+     */
+    dispatchGroupKey(event) {
+        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.
+    laneFlowHost() {
+        return this;
+    }
+    dispatchLaneGroup(opts) {
+        return dispatchLaneGroup(this.laneFlowHost(), opts);
+    }
+    consumeTypedDispatch(ref, run, ack) {
+        return consumeTypedDispatch(this.laneFlowHost(), ref, run, ack);
+    }
     buildDispatchContext(event, sessionKey) {
         const binding = this.sessionBindings.get(sessionKey);
         return {
@@ -373,6 +468,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,
         };
@@ -400,9 +496,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 }
                         : event.type === 'task_comment'
@@ -418,9 +516,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),
@@ -434,7 +539,7 @@ export class ParallAgentGateway {
             this.opts.log?.warn(`failed to create input step: ${String(err)}`);
         }
     }
-    async createRuntimeStep(sessionId, event, runtimeEvent, stepIdFilePath, contextFilePath) {
+    async createRuntimeStep(sessionId, event, runtimeEvent, stepIdFilePath, contextFilePath, laneContextFilePath) {
         const target = resolveStepTarget(event);
         try {
             switch (runtimeEvent.type) {
@@ -481,6 +586,9 @@ export class ParallAgentGateway {
                     else if (stepIdFilePath) {
                         this.writeStepIdFile(stepIdFilePath, step.id);
                     }
+                    if (laneContextFilePath) {
+                        this.updateContextFileStepId(laneContextFilePath, step.id);
+                    }
                     break;
                 }
                 case 'tool_result':
@@ -504,6 +612,9 @@ export class ParallAgentGateway {
                     else if (stepIdFilePath) {
                         this.clearStepIdFile(stepIdFilePath);
                     }
+                    if (laneContextFilePath) {
+                        this.updateContextFileStepId(laneContextFilePath, null);
+                    }
                     break;
                 case 'error':
                     await this.opts.client.createAgentStep(this.opts.config.org_id, this.opts.agentUserId, sessionId, {
@@ -577,7 +688,7 @@ export class ParallAgentGateway {
             await this.createInputStep(sessionId, event);
         }
     }
-    async bindRuntimeSession(sessionKey, runtimeEvent, contextFilePath) {
+    async bindRuntimeSession(sessionKey, runtimeEvent, contextFilePath, laneContextFilePath) {
         const runtimeLaneKey = runtimeEvent.runtimeLaneKey || sessionKey;
         const existing = this.sessionBindings.get(sessionKey);
         if (existing &&
@@ -626,6 +737,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;
     }
@@ -655,14 +769,32 @@ export class ParallAgentGateway {
             const dispatchContext = this.buildDispatchContext(event, sessionKey);
             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
             // — JS event loop is single-threaded, so shutdown() cannot interleave
@@ -694,7 +826,20 @@ 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
@@ -725,6 +870,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);
                     }
@@ -745,7 +896,7 @@ export class ParallAgentGateway {
                         pendingSendCallIds.delete(runtimeEvent.callId)) {
                         recordMessageSend(sessionKey, !runtimeEvent.error);
                     }
-                    await this.createRuntimeStep(binding.agentSessionId, event, runtimeEvent, stepIdFilePath, contextFilePath);
+                    await this.createRuntimeStep(binding.agentSessionId, event, runtimeEvent, stepIdFilePath, contextFilePath, laneContextFilePath);
                 }
                 if (!binding) {
                     binding = this.sessionBindings.get(sessionKey);
@@ -768,7 +919,7 @@ export class ParallAgentGateway {
                         await this.createRuntimeStep(binding.agentSessionId, event, {
                             type: 'error',
                             message: `Dispatch failed: ${String(err)}`,
-                        }, stepIdFilePath, contextFilePath);
+                        }, stepIdFilePath, contextFilePath, laneContextFilePath);
                     }
                     catch (stepErr) {
                         if (this.isSessionNotLiveError(stepErr))
@@ -824,6 +975,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);
@@ -889,13 +1043,44 @@ export class ParallAgentGateway {
                         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;
+                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 = [];
-                    const dispatched = await this.runDispatch(last, fork.fork.sessionKey, buildForkScopePrefix(last) + buildEventBody(last), earlier, batchText);
+                    let dispatched;
+                    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.
@@ -1011,9 +1196,10 @@ export class ParallAgentGateway {
                     this.opts.log?.info(`drainMainBuffer halted (shutting down) — ${this.dispatchState.mainBuffer.length} buffered, ${this.dispatchState.pendingForkResults.length} pending fork results left for catch-up`);
                     break;
                 }
-                const targetId = this.dispatchState.mainBuffer[0].targetId;
+                const groupKey = this.dispatchGroupKey(this.dispatchState.mainBuffer[0]);
                 const events = [];
-                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());
                 }
                 const event = events[events.length - 1];
@@ -1024,7 +1210,41 @@ 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;
+                    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);
                 }
@@ -1060,6 +1280,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
@@ -1088,10 +1309,40 @@ 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 = '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);
                 }
@@ -1099,6 +1350,7 @@ export class ParallAgentGateway {
                     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;
@@ -1125,7 +1377,20 @@ 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 (this.dispatchState.mainCurrentTargetId === event.targetId &&
+                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, buildEventBody(event)))) {
                     this.opts.log?.info(`steer injected for ${event.messageId} (will drain for bookkeeping)`);
                 }
@@ -1311,9 +1576,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);
@@ -1324,7 +1593,21 @@ export class ParallAgentGateway {
             this.dispatchedMessages.delete(data.id);
         }
     }
-    async handleTaskAssignment(task, ackSourceId) {
+    // Ledger re-drive consumption: dispatch.new message hints re-enter the
+    // shared WorkItem consumption path (same protocol as catch-up).
+    async handleMessageRedrive(item) {
+        if (!item.chat_id || !item.source_id)
+            return;
+        await this.consumeMessageWorkItem({
+            id: item.id,
+            source_id: item.source_id,
+            chat_id: item.chat_id,
+        });
+    }
+    consumeMessageWorkItem(item) {
+        return consumeMessageWorkItem(this.laneFlowHost(), item);
+    }
+    async handleTaskAssignment(task, ackSourceId, dispatchEventId) {
         if (this.shuttingDown)
             return false; // drain window — let server requeue via catch-up
         const dedupeKey = `${task.id}:${task.updated_at}`;
@@ -1354,6 +1637,7 @@ export class ParallAgentGateway {
             sentAt: task.updated_at ?? task.created_at,
             ackSourceType: 'task_activity',
             ackSourceId,
+            dispatchEventId,
         };
         const dispatched = await this.handleInboundEvent(event);
         if (!dispatched) {
@@ -1378,7 +1662,7 @@ export class ParallAgentGateway {
             this.opts.log?.info(`skipping stale task dispatch ${ackSourceId ?? taskId} — assigned to ${task.assignee_id}, creator ${task.creator_id}`);
             return true;
         }
-        return this.handleTaskAssignment(task, ackSourceId);
+        return this.handleTaskAssignment(task, ackSourceId, opts.dispatchEventId);
     }
     async handleTaskComment(commentId, taskId, actorId, deliveryReason) {
         if (this.shuttingDown)
@@ -1612,6 +1896,88 @@ export class ParallAgentGateway {
             return true;
         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.
+    async fetchAndHandleChannelMessage(messageId) {
+        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 = null;
+        let conv = 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) {
+            const status = err?.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 = {
+            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;
+        try {
+            dispatched = await this.handleInboundEvent(event);
+        }
+        catch (err) {
+            this.dispatchedMessages.delete(claimKey);
+            throw err;
+        }
+        if (!dispatched) {
+            this.dispatchedMessages.delete(claimKey);
+        }
+        return dispatched;
+    }
     async handleExternalTriggerRun(run) {
         if (this.shuttingDown)
             return false;
@@ -1749,10 +2115,14 @@ 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) {
                             this.opts.log?.warn(`catch-up task fetch failed for ${item.task_id}, leaving pending: ${String(err)}`);
@@ -1761,7 +2131,10 @@ 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) {
                             this.opts.log?.warn(`catch-up task fetch failed for ${item.task_id}, leaving pending: ${String(err)}`);
@@ -1769,61 +2142,29 @@ export class ParallAgentGateway {
                         }
                     }
                     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 = null;
-                        let msgFetchFailed = false;
-                        try {
-                            msg = await this.opts.client.getMessage(item.source_id);
-                        }
-                        catch (err) {
-                            const status = err?.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) {
@@ -1892,6 +2233,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);
@@ -1971,6 +2326,13 @@ 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();
         this.opts.log?.info(`disconnected`);