@parall/agent-core 1.43.0 → 1.45.0

package/src/gateway-base.ts

@@ -41,8 +41,11 @@ import {
   consumeMessageWorkItem,
   consumeTypedDispatch,
   dispatchLaneGroup,
+  resolveDispatchByID,
+  settleDrainedTypedGroup,
+  typedLedgerEventIds,
 } from './gateway-lane-flow.js';
-import type { LaneFlowHost } from './gateway-lane-flow.js';
+import type { LaneFlowHost, TypedConsumeHooks } from './gateway-lane-flow.js';
 import { LaneLedger } from './lane-ledger.js';
 import { routeTrigger } from './routing.js';
 import {
@@ -447,30 +450,33 @@ export class ParallAgentGateway {
             ? { dispatchEventId: data.dispatch_event_id }
             : { sourceType: 'task_activity', sourceId: data.id },
           (dispatchEventId) => this.handleTaskAssignment(data, data.id, dispatchEventId),
-          (dispatchEventId) => {
-            if (dispatchEventId) {
-              return this.ackDispatchEvent(dispatchEventId, () => {
-                this.dispatchedTasks.delete(`${data.id}:${data.updated_at}`);
-              });
-            }
-            return this.opts.client
-              .ackDispatch(this.opts.config.org_id, {
-                source_type: 'task_activity',
-                source_id: data.id,
-              })
-              .then(
-                () => true,
-                (err) => {
-                  // Same contract as ackDispatchEvent: a failed ack is a
-                  // failed consume (arms backoff) and must free the hot-path
-                  // dedupe so the re-drive isn't rejected by this pod forever.
+          {
+            legacyAck: (dispatchEventId) => {
+              if (dispatchEventId) {
+                return this.ackDispatchEvent(dispatchEventId, () => {
                   this.dispatchedTasks.delete(`${data.id}:${data.updated_at}`);
-                  this.opts.log?.warn(
-                    `dispatch ack failed for task ${data.id}, releasing for re-drive: ${String(err)}`,
-                  );
-                  return false;
-                },
-              );
+                });
+              }
+              return this.opts.client
+                .ackDispatch(this.opts.config.org_id, {
+                  source_type: 'task_activity',
+                  source_id: data.id,
+                })
+                .then(
+                  () => true,
+                  (err) => {
+                    // Same contract as ackDispatchEvent: a failed ack is a
+                    // failed consume (arms backoff) and must free the hot-path
+                    // dedupe so the re-drive isn't rejected by this pod forever.
+                    this.dispatchedTasks.delete(`${data.id}:${data.updated_at}`);
+                    this.opts.log?.warn(
+                      `dispatch ack failed for task ${data.id}, releasing for re-drive: ${String(err)}`,
+                    );
+                    return false;
+                  },
+                );
+            },
+            clearDedupe: () => this.dispatchedTasks.delete(`${data.id}:${data.updated_at}`),
           },
         );
       } catch (err) {
@@ -493,14 +499,19 @@ export class ParallAgentGateway {
         try {
           await this.consumeTypedDispatch(
             { dispatchEventId: data.id },
-            () =>
+            (dispatchEventId) =>
               this.handleTaskComment(
                 data.source_id,
                 data.task_id ?? '',
                 data.actor_id,
                 data.delivery_reason,
+                dispatchEventId,
               ),
-            () => this.ackDispatchEvent(data.id, () => this.clearTypedDispatchDedupe(data)),
+            {
+              legacyAck: () =>
+                this.ackDispatchEvent(data.id, () => this.clearTypedDispatchDedupe(data)),
+              clearDedupe: () => this.clearTypedDispatchDedupe(data),
+            },
           );
         } catch (err) {
           this.opts.log?.error(
@@ -512,8 +523,18 @@ export class ParallAgentGateway {
         try {
           await this.consumeTypedDispatch(
             { dispatchEventId: data.id },
-            () => this.handleWikiComment(data.source_id, data.actor_id, data.delivery_reason),
-            () => this.ackDispatchEvent(data.id, () => this.clearTypedDispatchDedupe(data)),
+            (dispatchEventId) =>
+              this.handleWikiComment(
+                data.source_id,
+                data.actor_id,
+                data.delivery_reason,
+                dispatchEventId,
+              ),
+            {
+              legacyAck: () =>
+                this.ackDispatchEvent(data.id, () => this.clearTypedDispatchDedupe(data)),
+              clearDedupe: () => this.clearTypedDispatchDedupe(data),
+            },
           );
         } catch (err) {
           this.opts.log?.error(
@@ -530,7 +551,11 @@ export class ParallAgentGateway {
                 allowCreator: true,
                 dispatchEventId,
               }),
-            () => this.ackDispatchEvent(data.id, () => this.clearTypedDispatchDedupe(data)),
+            {
+              legacyAck: () =>
+                this.ackDispatchEvent(data.id, () => this.clearTypedDispatchDedupe(data)),
+              clearDedupe: () => this.clearTypedDispatchDedupe(data),
+            },
           );
         } catch (err) {
           this.opts.log?.error(`task update dispatch failed for ${data.task_id}: ${String(err)}`);
@@ -540,8 +565,13 @@ export class ParallAgentGateway {
         try {
           await this.consumeTypedDispatch(
             { dispatchEventId: data.id },
-            () => this.fetchAndHandleScheduleFire(data.source_id, data.actor_id),
-            () => this.ackDispatchEvent(data.id, () => this.clearTypedDispatchDedupe(data)),
+            (dispatchEventId) =>
+              this.fetchAndHandleScheduleFire(data.source_id, data.actor_id, dispatchEventId),
+            {
+              legacyAck: () =>
+                this.ackDispatchEvent(data.id, () => this.clearTypedDispatchDedupe(data)),
+              clearDedupe: () => this.clearTypedDispatchDedupe(data),
+            },
           );
         } catch (err) {
           this.opts.log?.error(
@@ -553,8 +583,13 @@ export class ParallAgentGateway {
         try {
           await this.consumeTypedDispatch(
             { dispatchEventId: data.id },
-            () => this.fetchAndHandleExternalTriggerRun(data.source_id),
-            () => this.ackDispatchEvent(data.id, () => this.clearTypedDispatchDedupe(data)),
+            (dispatchEventId) =>
+              this.fetchAndHandleExternalTriggerRun(data.source_id, dispatchEventId),
+            {
+              legacyAck: () =>
+                this.ackDispatchEvent(data.id, () => this.clearTypedDispatchDedupe(data)),
+              clearDedupe: () => this.clearTypedDispatchDedupe(data),
+            },
           );
         } catch (err) {
           this.opts.log?.error(
@@ -566,8 +601,12 @@ export class ParallAgentGateway {
         try {
           await this.consumeTypedDispatch(
             { dispatchEventId: data.id },
-            () => this.fetchAndHandleChannelMessage(data.source_id),
-            () => this.ackDispatchEvent(data.id, () => this.clearTypedDispatchDedupe(data)),
+            (dispatchEventId) => this.fetchAndHandleChannelMessage(data.source_id, dispatchEventId),
+            {
+              legacyAck: () =>
+                this.ackDispatchEvent(data.id, () => this.clearTypedDispatchDedupe(data)),
+              clearDedupe: () => this.clearTypedDispatchDedupe(data),
+            },
           );
         } catch (err) {
           this.opts.log?.error(
@@ -579,13 +618,18 @@ export class ParallAgentGateway {
         try {
           await this.consumeTypedDispatch(
             { dispatchEventId: data.id },
-            () =>
+            (dispatchEventId) =>
               this.fetchAndHandleApprovalDecided(
                 data.source_id,
                 data.actor_id,
                 data.chat_id ?? null,
+                dispatchEventId,
               ),
-            () => this.ackDispatchEvent(data.id, () => this.clearTypedDispatchDedupe(data)),
+            {
+              legacyAck: () =>
+                this.ackDispatchEvent(data.id, () => this.clearTypedDispatchDedupe(data)),
+              clearDedupe: () => this.clearTypedDispatchDedupe(data),
+            },
           );
         } catch (err) {
           this.opts.log?.error(
@@ -641,6 +685,45 @@ export class ParallAgentGateway {
     return true;
   }
 
+  /**
+   * Lane currently being dispatched per session — lets external activity
+   * signals renew exactly the caller's lane (renewing all lanes would keep
+   * an unrelated stalled fork's lane leased forever).
+   */
+  private sessionActiveLanes = new Map<string, string>();
+
+  noteSessionLane(sessionKey: string, laneKey: string | null): void {
+    if (laneKey == null) this.sessionActiveLanes.delete(sessionKey);
+    else this.sessionActiveLanes.set(sessionKey, laneKey);
+  }
+
+  /**
+   * External runtime-activity signal for adapters whose tool activity does
+   * not flow through the RuntimeEvent stream (openclaw hooks call this from
+   * the tool-call lifecycle): renews the session's OWN active ledger lane so
+   * a long tool call cannot outlive the lease and get dethroned mid-turn.
+   * No-op without an active ledger lane for the session.
+   */
+  touchRuntimeActivity(sessionKey: string): void {
+    if (this.ledgerDisabled) return;
+    const laneKey = this.sessionActiveLanes.get(sessionKey);
+    if (laneKey) this.laneLedger?.renewByKey(laneKey);
+  }
+
+  /** Sessions whose in-flight turn surfaced a runtime error event. */
+  private turnErrorSessions = new Set<string>();
+
+  /**
+   * Consume (read-and-clear) the error marker for sessionKey's last turn.
+   * Feeds complete's turn_outcome so an error turn's lane members are
+   * released for retry instead of no_action-swept (design §3). Consuming
+   * (rather than peeking) keeps one-shot fork session keys from accumulating
+   * in the set forever.
+   */
+  consumeTurnError(sessionKey: string): boolean {
+    return this.turnErrorSessions.delete(sessionKey);
+  }
+
   private async emitDispatchReceived(event: ParallEvent): Promise<void> {
     const sourceType = event.ackSourceType ?? (event.type === 'task' ? 'task_activity' : 'message');
     const sourceId = event.ackSourceId ?? event.messageId;
@@ -650,6 +733,26 @@ export class ParallAgentGateway {
     });
   }
 
+  /**
+   * Sticky: the server answered a by-id complete with 400 (predates the
+   * form). Typed resolution falls back to the legacy ack for the rest of
+   * the process lifetime.
+   */
+  typedByIdCompleteUnsupported = false;
+
+  // Typed-face ledger helpers live in gateway-lane-flow.ts; thin delegates
+  // keep the site code and tests on the class surface.
+  private typedLedgerEventIds(events: ParallEvent[]): string[] | null {
+    return typedLedgerEventIds(this.laneFlowHost(), events);
+  }
+
+  private resolveDispatchByID(
+    dispatchEventId: string,
+    lane?: string,
+  ): ReturnType<typeof resolveDispatchByID> {
+    return resolveDispatchByID(this.laneFlowHost(), dispatchEventId, lane);
+  }
+
   /** 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);
@@ -693,24 +796,25 @@ export class ParallAgentGateway {
     earlier: ParallEvent[];
     captureText?: string[];
     hasMoreLocal: () => boolean;
-  }): Promise<'dispatched' | 'foreign' | 'shutdown'> {
+  }): Promise<'dispatched' | 'foreign' | 'shutdown' | 'failed'> {
     return dispatchLaneGroup(this.laneFlowHost(), opts);
   }
 
   private consumeTypedDispatch(
     ref: { dispatchEventId?: string; sourceType?: string; sourceId?: string },
     run: (dispatchEventId?: string) => Promise<boolean>,
-    ack: (dispatchEventId?: string) => boolean | void | Promise<boolean | void>,
+    hooks: TypedConsumeHooks,
   ): Promise<void> {
-    return consumeTypedDispatch(this.laneFlowHost(), ref, run, ack);
+    return consumeTypedDispatch(this.laneFlowHost(), ref, run, hooks);
   }
 
-  // Typed completion must wait until the administrative ack has either
-  // committed or failed. Errors stay best-effort: a failed ack leaves the row
-  // received, so Complete releases and re-drives it safely. The boolean
-  // outcome feeds the typed-consume backoff — an ack that failed must count
-  // as a failed consume, or an ack outage would clear the backoff entry and
-  // let the release re-drive spin at wire speed.
+  // Legacy administrative ack (ledger-disabled fallback only). Typed
+  // completion must wait until the ack has either committed or failed.
+  // Errors stay best-effort: a failed ack leaves the row received, so
+  // Complete releases and re-drives it safely. The boolean outcome feeds the
+  // typed-consume backoff — an ack that failed must count as a failed
+  // consume, or an ack outage would clear the backoff entry and let the
+  // release re-drive spin at wire speed.
   private ackDispatchEvent(dispatchEventId: string, onFailure?: () => void): Promise<boolean> {
     return this.opts.client.ackDispatchByID(this.opts.config.org_id, dispatchEventId).then(
       () => true,
@@ -727,6 +831,9 @@ export class ParallAgentGateway {
     );
   }
 
+  // PARITY: this switch and gateway-lane-flow's clearTypedDedupeForEvent must
+  // handle the same typed source families — extend BOTH when adding a typed
+  // event type (same dedupe entries, keyed from different event shapes).
   private clearTypedDispatchDedupe(item: DispatchNewData): void {
     switch (item.event_type) {
       case 'task_assign':
@@ -1137,6 +1244,7 @@ export class ParallAgentGateway {
     }
 
     resetDispatchMetrics(sessionKey);
+    this.turnErrorSessions.delete(sessionKey);
     return runWithSessionKey(sessionKey, async () => {
       let dispatchSpan: ReturnType<typeof startDispatchSpan> = null;
 
@@ -1299,6 +1407,9 @@ export class ParallAgentGateway {
           ) {
             recordMessageSend(sessionKey, !runtimeEvent.error);
           }
+          if (runtimeEvent.type === 'error') {
+            this.turnErrorSessions.add(sessionKey);
+          }
           await this.createRuntimeStep(
             binding.agentSessionId,
             event,
@@ -1495,13 +1606,29 @@ export class ParallAgentGateway {
               body: buildForkScopePrefix(last) + buildEventBody(last),
               earlier,
               captureText: batchText,
-              hasMoreLocal: () => fork.queue.length > 0,
+              // Per-LANE residue check (parity with the main-buffer path):
+              // the fork queue can hold several lanes (channel + thread of
+              // the same chat). A whole-queue check would defer THIS lane's
+              // complete behind another lane's items and never revisit it —
+              // its members would sit received until lease expiry.
+              hasMoreLocal: () =>
+                fork.queue.some(
+                  (it) => this.dispatchGroupKey(it.event) === this.dispatchGroupKey(last),
+                ),
             });
             if (outcome === 'foreign') {
               // Another pod owns the lane — the events stay pending server-side.
               for (const item of items) item.resolve(false);
               break;
             }
+            if (outcome === 'failed') {
+              // Error turn: complete(error) already released the members for
+              // redelivery. Do NOT push them to processedEvents — the redrive
+              // must not arrive wearing an "already handled" prefix. Keep
+              // draining; the released work rejoins the next claim.
+              for (const item of items) item.resolve(false);
+              continue;
+            }
             dispatched = outcome === 'dispatched';
           } else {
             dispatched = await this.runDispatch(
@@ -1511,6 +1638,22 @@ export class ParallAgentGateway {
               earlier,
               batchText,
             );
+            if (
+              dispatched &&
+              this.typedLedgerEventIds(events) &&
+              this.consumeTurnError(fork.fork.sessionKey)
+            ) {
+              // Typed error turn in a fork: report failure to the awaiting
+              // typed consumes so the members release for a budgeted retry,
+              // and do NOT record the events as handled — the redrive must
+              // not arrive wearing an "already handled" prefix. Keep draining
+              // (an error turn is not a shutdown).
+              this.opts.log?.info(
+                `typed fork turn for ${last.messageId} surfaced a runtime error — releasing for retry`,
+              );
+              for (const item of items) item.resolve(false);
+              continue;
+            }
           }
           if (!dispatched) {
             // Shutdown short-circuit — resolve un-acked so the server requeues
@@ -1542,6 +1685,10 @@ export class ParallAgentGateway {
         remaining.resolve(false);
       }
     } finally {
+      // One-shot fork keys are never dispatched again — drop any error marker
+      // the legacy (non-ledger) path left unconsumed, or the set grows with
+      // every failed ephemeral fork.
+      this.turnErrorSessions.delete(fork.fork.sessionKey);
       if (fork.deadlineTimer) {
         clearTimeout(fork.deadlineTimer);
         fork.deadlineTimer = null;
@@ -1654,7 +1801,7 @@ export class ParallAgentGateway {
           this.opts.runtimeKey,
         );
         if (this.usesLaneLedger(event)) {
-          let outcome: 'dispatched' | 'foreign' | 'shutdown';
+          let outcome: 'dispatched' | 'foreign' | 'shutdown' | 'failed';
           try {
             outcome = await this.dispatchLaneGroup({
               events,
@@ -1681,19 +1828,33 @@ export class ParallAgentGateway {
             this.dispatchState.pendingForkResults.unshift(...pendingFork);
             continue;
           }
+          if (outcome === 'failed') {
+            // Error turn settled with complete(error) — members released for
+            // redelivery. The fork results were not consumed by the failed
+            // turn; keep them for the next real dispatch.
+            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) {
-          this.opts.log?.warn?.(
-            `mark-received failed for buffered dispatch, leaving unacked for retry: ${String(err)}`,
-          );
-          this.dispatchState.mainBuffer.unshift(...events);
-          this.dispatchState.pendingForkResults.unshift(...pendingFork);
-          break;
+        // Buffered typed events are the one wrapper-less dispatch path: their
+        // consumeTypedDispatch guard returned long ago (buffer-main resolves
+        // false) and released the claims, so THIS site owns their resolution.
+        // Message groups here are the ledger-disabled legacy flow.
+        const typedRefs = this.typedLedgerEventIds(events);
+        if (!typedRefs) {
+          try {
+            await this.emitDispatchReceived(event);
+          } catch (err) {
+            this.opts.log?.warn?.(
+              `mark-received failed for buffered dispatch, leaving unacked for retry: ${String(err)}`,
+            );
+            this.dispatchState.mainBuffer.unshift(...events);
+            this.dispatchState.pendingForkResults.unshift(...pendingFork);
+            break;
+          }
         }
         const dispatched = await this.runDispatch(
           event,
@@ -1709,6 +1870,18 @@ export class ParallAgentGateway {
           this.dispatchState.pendingForkResults.unshift(...pendingFork);
           break;
         }
+        if (typedRefs) {
+          // Wrapper-less resolution of the buffered typed group — protocol
+          // lives in gateway-lane-flow.ts. The turn-error marker is consumed
+          // HERE, before this loop can start another turn on the session.
+          await settleDrainedTypedGroup(
+            this.laneFlowHost(),
+            events,
+            typedRefs,
+            this.consumeTurnError(this.opts.runtimeKey),
+          );
+          continue;
+        }
         for (const bufferedEvent of events) {
           const sourceType =
             bufferedEvent.ackSourceType ??
@@ -1769,7 +1942,7 @@ export class ParallAgentGateway {
         if (this.usesLaneLedger(event)) {
           // Ledger flow: claim replaces mark-received; complete/reply replace
           // acks. A foreign incumbent leaves the event pending for re-drive.
-          let outcome: 'dispatched' | 'foreign' | 'shutdown' = 'shutdown';
+          let outcome: 'dispatched' | 'foreign' | 'shutdown' | 'failed' = 'shutdown';
           try {
             try {
               outcome = await this.dispatchLaneGroup({
@@ -1796,16 +1969,24 @@ export class ParallAgentGateway {
           }
           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;
+        // Ledger-claimed typed events skip the legacy received write — the
+        // claim already marked the row received, and a second mark here would
+        // wipe its lease owner (the 0713 black-hole shape on the typed face).
+        const typedRefs = this.typedLedgerEventIds([event]);
+        if (!typedRefs) {
+          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;
+          }
         }
         let dispatched = false;
         try {
@@ -1814,6 +1995,17 @@ export class ParallAgentGateway {
             this.opts.runtimeKey,
             forkPrefix + buildEventBody(event),
           );
+          if (dispatched && typedRefs && this.consumeTurnError(this.opts.runtimeKey)) {
+            // Typed error turn: report failure to the enclosing typed consume
+            // so the member releases for a budgeted retry instead of being
+            // terminally resolved (tech-debt: typed-dispatch-error-outcome).
+            // Consumed HERE, before the finally's drain can start another
+            // turn on this session and clear the marker.
+            this.opts.log?.info(
+              `typed dispatch turn for ${event.messageId} surfaced a runtime error — releasing for retry`,
+            );
+            dispatched = false;
+          }
           if (!dispatched) {
             // Shutdown short-circuit — restore the fork results so a future
             // pod can replay them, and return false so handleMessage skips ack.
@@ -1840,10 +2032,17 @@ export class ParallAgentGateway {
           // 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.
+          // The adapter-capability check comes BEFORE the fold: on a
+          // buffer-only adapter (openclaw — no enqueueDuringDispatch) a
+          // folded-but-never-injected member would be broad-covered by the
+          // current turn's reply without the model ever seeing it. Leaving
+          // the event un-folded keeps it buffered; the drain claims it as
+          // its own turn and folds it there.
           if (
             this.mainCurrentGroupKey === this.dispatchGroupKey(event) &&
+            this.opts.dispatchAdapter.enqueueDuringDispatch != null &&
             (await this.laneLedger?.steerLive(event)) &&
-            (await this.opts.dispatchAdapter.enqueueDuringDispatch?.(
+            (await this.opts.dispatchAdapter.enqueueDuringDispatch(
               this.opts.runtimeKey,
               buildEventBody(event),
             ))
@@ -1892,14 +2091,22 @@ export class ParallAgentGateway {
           return false;
         }
 
-        try {
-          await this.emitDispatchReceived(event);
-        } catch (err) {
-          this.opts.log?.warn?.(
-            `mark-received failed for fork dispatch, leaving unacked for retry: ${String(err)}`,
-          );
-          this.dispatchState.mainBuffer.push(event);
-          return false;
+        // Ledger-managed events must never touch the legacy received surface
+        // — the fork's lane claim marks them received. A mark-received here
+        // outruns the claim, strands the row ownerless, and the chat goes
+        // silent (the 0713 black hole; dispatch-convergence-design.md §6).
+        // Same rule for ledger-claimed typed events: their dsp-lane claim
+        // owns received-ness, and a re-mark would wipe the lease owner.
+        if (!this.usesLaneLedger(event) && !this.typedLedgerEventIds([event])) {
+          try {
+            await this.emitDispatchReceived(event);
+          } catch (err) {
+            this.opts.log?.warn?.(
+              `mark-received failed for fork dispatch, leaving unacked for retry: ${String(err)}`,
+            );
+            this.dispatchState.mainBuffer.push(event);
+            return false;
+          }
         }
         const fork = await this.opts.dispatchAdapter.forkSession({
           sessionKey: this.opts.runtimeKey,
@@ -2101,10 +2308,13 @@ export class ParallAgentGateway {
         this.handleTaskDispatch(item.task_id ?? '', item.source_id ?? item.task_id ?? '', {
           dispatchEventId,
         }),
-      (dispatchEventId) =>
-        this.ackDispatchEvent(dispatchEventId ?? item.id, () =>
-          this.clearTypedDispatchDedupe(item),
-        ),
+      {
+        legacyAck: (dispatchEventId) =>
+          this.ackDispatchEvent(dispatchEventId ?? item.id, () =>
+            this.clearTypedDispatchDedupe(item),
+          ),
+        clearDedupe: () => this.clearTypedDispatchDedupe(item),
+      },
     );
   }
 
@@ -2187,6 +2397,7 @@ export class ParallAgentGateway {
     taskId: string,
     actorId: string | null,
     deliveryReason?: DispatchDeliveryReason | null,
+    dispatchEventId?: string,
   ): Promise<boolean> {
     if (this.shuttingDown) return false; // drain window — let server requeue via catch-up
     const dedupeKey = `comment:${commentId}`;
@@ -2251,6 +2462,7 @@ export class ParallAgentGateway {
       deliveryReason: deliveryReason ?? undefined,
       ackSourceType: 'comment',
       ackSourceId: commentId,
+      dispatchEventId,
     };
 
     let dispatched: boolean;
@@ -2271,6 +2483,7 @@ export class ParallAgentGateway {
     commentId: string,
     actorId: string | null,
     deliveryReason?: DispatchDeliveryReason | null,
+    dispatchEventId?: string,
   ): Promise<boolean> {
     if (this.shuttingDown) return false; // drain window — let server requeue via catch-up
     // Shares the comment dedupe namespace with handleTaskComment; comment IDs
@@ -2326,6 +2539,7 @@ export class ParallAgentGateway {
       replyTargetUri: comment.target_uri,
       ackSourceType: 'comment',
       ackSourceId: commentId,
+      dispatchEventId,
     };
 
     let dispatched: boolean;
@@ -2353,6 +2567,7 @@ export class ParallAgentGateway {
   private async fetchAndHandleScheduleFire(
     runId: string,
     actorId: string | null,
+    dispatchEventId?: string,
   ): Promise<boolean> {
     let run: ScheduleRun | null = null;
     try {
@@ -2374,10 +2589,14 @@ export class ParallAgentGateway {
       return false;
     }
     if (!run) return true;
-    return this.handleScheduleFire(run, actorId);
+    return this.handleScheduleFire(run, actorId, dispatchEventId);
   }
 
-  private async handleScheduleFire(run: ScheduleRun, actorId: string | null): Promise<boolean> {
+  private async handleScheduleFire(
+    run: ScheduleRun,
+    actorId: string | null,
+    dispatchEventId?: string,
+  ): Promise<boolean> {
     if (this.shuttingDown) return false; // drain window — let server requeue via catch-up
     const dedupeKey = `schedule_run:${run.id}`;
     if (this.dispatchedTasks.has(dedupeKey)) return false;
@@ -2400,6 +2619,7 @@ export class ParallAgentGateway {
       attachedUri: run.fired_attached_uri ?? undefined,
       ackSourceType: 'schedule_run',
       ackSourceId: run.id,
+      dispatchEventId,
     };
 
     let dispatched: boolean;
@@ -2415,7 +2635,10 @@ export class ParallAgentGateway {
     return dispatched;
   }
 
-  private async fetchAndHandleExternalTriggerRun(runId: string): Promise<boolean> {
+  private async fetchAndHandleExternalTriggerRun(
+    runId: string,
+    dispatchEventId?: string,
+  ): Promise<boolean> {
     let run: ExternalTriggerRun | null = null;
     try {
       run = await this.opts.client.getExternalTriggerRun(this.opts.config.org_id, runId);
@@ -2433,7 +2656,7 @@ export class ParallAgentGateway {
       return false;
     }
     if (!run) return true;
-    return this.handleExternalTriggerRun(run);
+    return this.handleExternalTriggerRun(run, dispatchEventId);
   }
 
   // fetchAndHandleChannelMessage resolves a channel_message dispatch to its
@@ -2441,7 +2664,10 @@ export class ParallAgentGateway {
   // 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> {
+  private async fetchAndHandleChannelMessage(
+    messageId: string,
+    dispatchEventId?: 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
@@ -2525,6 +2751,7 @@ export class ParallAgentGateway {
       channelCliCapable: cliCapable,
       ackSourceType: 'channel_message',
       ackSourceId: msg.id,
+      dispatchEventId,
     };
 
     // Release the claim if the event isn't actually dispatched (or throws) so
@@ -2542,7 +2769,10 @@ export class ParallAgentGateway {
     return dispatched;
   }
 
-  private async handleExternalTriggerRun(run: ExternalTriggerRun): Promise<boolean> {
+  private async handleExternalTriggerRun(
+    run: ExternalTriggerRun,
+    dispatchEventId?: string,
+  ): Promise<boolean> {
     if (this.shuttingDown) return false;
     const dedupeKey = `external_trigger_run:${run.id}`;
     if (this.dispatchedTasks.has(dedupeKey)) return false;
@@ -2570,6 +2800,7 @@ export class ParallAgentGateway {
       attachedUri,
       ackSourceType: 'external_trigger_run',
       ackSourceId: run.id,
+      dispatchEventId,
     };
 
     let dispatched: boolean;
@@ -2589,6 +2820,7 @@ export class ParallAgentGateway {
     approvalId: string,
     actorId: string | null,
     chatId: string | null,
+    dispatchEventId?: string,
   ): Promise<boolean> {
     let approval: Approval | null = null;
     try {
@@ -2625,6 +2857,11 @@ export class ParallAgentGateway {
       senderName: 'approver',
       messageId: approval.id,
       body,
+      // The WorkItem's real source pair. Without it the legacy fallback
+      // guessed ('message', approval_id) — a pair no row matches.
+      ackSourceType: 'approval',
+      ackSourceId: approval.id,
+      dispatchEventId,
     };
 
     let dispatched: boolean;
@@ -2683,7 +2920,24 @@ export class ParallAgentGateway {
 
         if (overflowMode && processed >= CATCHUP_MAX) {
           try {
-            await this.opts.client.ackDispatchByID(this.opts.config.org_id, item.id);
+            // Administrative drop of the overflow backlog (summarized to the
+            // agent instead of dispatched). Ledger path: by-id complete —
+            // closes the pending row and refuses (stale) one a live lane
+            // owns; the legacy ack stays as the ledger-disabled / pre-by-id
+            // fallback.
+            if (this.laneLedger && !this.ledgerDisabled && !this.typedByIdCompleteUnsupported) {
+              const outcome = await this.resolveDispatchByID(item.id);
+              if (outcome === 'unsupported') {
+                this.typedByIdCompleteUnsupported = true;
+                await this.opts.client.ackDispatchByID(this.opts.config.org_id, item.id);
+              } else if (outcome === 'failed') {
+                throw new Error('by-id complete failed');
+              }
+              // 'stale' counts as skipped: a live lane owns the row and its
+              // turn will resolve it — nothing left for catch-up to do.
+            } else {
+              await this.opts.client.ackDispatchByID(this.opts.config.org_id, item.id);
+            }
             skipped++;
             const key = item.event_type;
             skippedByType.set(key, (skippedByType.get(key) ?? 0) + 1);
@@ -2695,8 +2949,11 @@ export class ParallAgentGateway {
 
         processed++;
         try {
-          const ackItem = () =>
-            this.ackDispatchEvent(item.id, () => this.clearTypedDispatchDedupe(item));
+          const typedHooks: TypedConsumeHooks = {
+            legacyAck: () =>
+              this.ackDispatchEvent(item.id, () => this.clearTypedDispatchDedupe(item)),
+            clearDedupe: () => this.clearTypedDispatchDedupe(item),
+          };
           if (item.event_type === 'task_assign' && item.task_id) {
             try {
               await this.consumeTypedDispatch(
@@ -2709,7 +2966,7 @@ export class ParallAgentGateway {
                       dispatchEventId,
                     },
                   ),
-                ackItem,
+                typedHooks,
               );
             } catch (err: unknown) {
               this.opts.log?.warn(
@@ -2730,7 +2987,7 @@ export class ParallAgentGateway {
                       dispatchEventId,
                     },
                   ),
-                ackItem,
+                typedHooks,
               );
             } catch (err: unknown) {
               this.opts.log?.warn(
@@ -2741,49 +2998,60 @@ export class ParallAgentGateway {
           } else if (item.event_type === 'task_comment' && item.source_id && item.task_id) {
             await this.consumeTypedDispatch(
               { dispatchEventId: item.id },
-              () =>
+              (dispatchEventId) =>
                 this.handleTaskComment(
                   item.source_id,
                   item.task_id ?? '',
                   item.actor_id,
                   item.delivery_reason,
+                  dispatchEventId,
                 ),
-              ackItem,
+              typedHooks,
             );
           } else if (item.event_type === 'wiki_comment' && item.source_id) {
             await this.consumeTypedDispatch(
               { dispatchEventId: item.id },
-              () => this.handleWikiComment(item.source_id, item.actor_id, item.delivery_reason),
-              ackItem,
+              (dispatchEventId) =>
+                this.handleWikiComment(
+                  item.source_id,
+                  item.actor_id,
+                  item.delivery_reason,
+                  dispatchEventId,
+                ),
+              typedHooks,
             );
           } else if (item.event_type === 'schedule.fire' && item.source_id) {
             await this.consumeTypedDispatch(
               { dispatchEventId: item.id },
-              () => this.fetchAndHandleScheduleFire(item.source_id, item.actor_id),
-              ackItem,
+              (dispatchEventId) =>
+                this.fetchAndHandleScheduleFire(item.source_id, item.actor_id, dispatchEventId),
+              typedHooks,
             );
           } else if (item.event_type === 'external_trigger' && item.source_id) {
             await this.consumeTypedDispatch(
               { dispatchEventId: item.id },
-              () => this.fetchAndHandleExternalTriggerRun(item.source_id),
-              ackItem,
+              (dispatchEventId) =>
+                this.fetchAndHandleExternalTriggerRun(item.source_id, dispatchEventId),
+              typedHooks,
             );
           } else if (item.event_type === 'channel_message' && item.source_id) {
             await this.consumeTypedDispatch(
               { dispatchEventId: item.id },
-              () => this.fetchAndHandleChannelMessage(item.source_id),
-              ackItem,
+              (dispatchEventId) =>
+                this.fetchAndHandleChannelMessage(item.source_id, dispatchEventId),
+              typedHooks,
             );
           } else if (item.event_type === 'approval_decided' && item.source_id) {
             await this.consumeTypedDispatch(
               { dispatchEventId: item.id },
-              () =>
+              (dispatchEventId) =>
                 this.fetchAndHandleApprovalDecided(
                   item.source_id,
                   item.actor_id,
                   item.chat_id ?? null,
+                  dispatchEventId,
                 ),
-              ackItem,
+              typedHooks,
             );
           } else if (item.event_type === 'message' && item.source_id && item.chat_id) {
             await this.consumeMessageWorkItem({