@parall/daemon 1.44.0 → 1.45.0

package/bundle/parall-claude-agent.js

@@ -26487,9 +26487,6 @@ function laneContextFilePath(contextDir, targetUri, threadRootId) {
   return path.join(contextDir, `${laneKeyForTarget(targetUri, threadRootId)}.json`);
 }
 
-// ts/agent-core/dist/lane-ledger.js
-import * as fs from "node:fs";
-
 // ts/sdk/dist/types.js
 var MENTION_ALL_USER_ID = "all";
 
@@ -29101,6 +29098,7 @@ var ParallWs = class {
 };
 
 // ts/agent-core/dist/lane-ledger.js
+import * as fs from "node:fs";
 var LedgerUnsupportedError = class extends Error {
 };
 function isStaleLane(err) {
@@ -29384,6 +29382,20 @@ var LaneLedger = class {
     this.lanes.set(lane.laneKey, lane);
     return lane;
   }
+  /**
+   * Drop a lane's local record without any server call — for a typed lane
+   * whose member the by-id complete just resolved (the server dropped the
+   * vacated lane row in the same transaction). Calling completeIfIdle
+   * instead would fire a lane-form Complete at a lane that no longer exists
+   * and burn an RPC on the guaranteed STALE_LANE answer.
+   */
+  dropLocal(laneKey) {
+    const lane = this.lanes.get(laneKey);
+    if (!lane)
+      return;
+    this.lanes.delete(laneKey);
+    this.removeLaneContext(lane);
+  }
   /**
    * Remove the per-lane context file (and its CLI sidecar) when the lane
    * ends. A leftover file would make a later cross-context send to the same
@@ -29463,10 +29475,104 @@ async function dispatchLaneGroup(host, opts) {
   await ledger.completeIfIdle(lane.laneKey, pendingInjections || opts.hasMoreLocal());
   return "dispatched";
 }
+function typedLedgerEventIds(host, events) {
+  if (!host.laneLedger || host.ledgerDisabled)
+    return null;
+  const ids = [];
+  for (const ev of events) {
+    if (!ev.dispatchEventId || host.usesLaneLedger(ev))
+      return null;
+    ids.push(ev.dispatchEventId);
+  }
+  return ids.length > 0 ? ids : null;
+}
+function isByIDCompleteUnsupported(err) {
+  return err instanceof ApiError && err.status === 400;
+}
+async function resolveDispatchByID(host, dispatchEventId, lane) {
+  try {
+    await host.opts.client.completeDispatch(host.opts.config.org_id, {
+      dispatch_event_id: dispatchEventId,
+      ...lane ? { lane } : {},
+      turn_outcome: "ok"
+    });
+    return "ok";
+  } catch (err) {
+    if (err instanceof ApiError && err.status === 409)
+      return "stale";
+    if (isByIDCompleteUnsupported(err))
+      return "unsupported";
+    host.opts.log?.warn(`by-id complete failed for ${dispatchEventId} \u2014 leaving for re-drive: ${String(err)}`);
+    return "failed";
+  }
+}
+function clearTypedDedupeForEvent(host, event) {
+  const sourceId = event.ackSourceId;
+  if (!sourceId)
+    return;
+  switch (event.ackSourceType) {
+    case "task_activity": {
+      const prefix = `${event.targetId}:`;
+      for (const key of host.dispatchedTasks) {
+        if (key.startsWith(prefix))
+          host.dispatchedTasks.delete(key);
+      }
+      break;
+    }
+    case "comment":
+      host.dispatchedTasks.delete(`comment:${sourceId}`);
+      break;
+    case "schedule_run":
+      host.dispatchedTasks.delete(`schedule_run:${sourceId}`);
+      break;
+    case "external_trigger_run":
+      host.dispatchedTasks.delete(`external_trigger_run:${sourceId}`);
+      break;
+    case "channel_message":
+      host.dispatchedMessages.delete(`channel_message:${sourceId}`);
+      break;
+    case "approval":
+      host.dispatchedTasks.delete(`approval:${sourceId}`);
+      break;
+  }
+}
+async function settleDrainedTypedGroup(host, events, ids, turnErrored) {
+  if (turnErrored) {
+    host.opts.log?.info(`buffered typed turn for ${events[events.length - 1]?.messageId} surfaced a runtime error \u2014 leaving for re-drive`);
+    for (const event of events)
+      clearTypedDedupeForEvent(host, event);
+    return;
+  }
+  const legacyAckFrom = async (start) => {
+    for (const [j, id] of ids.slice(start).entries()) {
+      try {
+        await host.opts.client.ackDispatchByID(host.opts.config.org_id, id);
+      } catch {
+        clearTypedDedupeForEvent(host, events[start + j]);
+      }
+    }
+  };
+  if (host.typedByIdCompleteUnsupported) {
+    await legacyAckFrom(0);
+    return;
+  }
+  for (const [i, id] of ids.entries()) {
+    const outcome = await resolveDispatchByID(host, id);
+    if (outcome === "unsupported") {
+      host.typedByIdCompleteUnsupported = true;
+      host.opts.log?.warn("server predates the by-id dispatch complete \u2014 falling back to legacy typed acks");
+      await legacyAckFrom(i);
+      return;
+    }
+    if (outcome !== "ok") {
+      clearTypedDedupeForEvent(host, events[i]);
+    }
+  }
+}
 var TYPED_BACKOFF_BASE_MS = 2e3;
 var TYPED_BACKOFF_CAP_MS = 5 * 6e4;
 var TYPED_BACKOFF_MAP_CAP = 512;
-async function consumeTypedDispatch(host, ref, run, ack) {
+async function consumeTypedDispatch(host, ref, run, hooks) {
   const backoffKey = ref.dispatchEventId ?? `${ref.sourceType}:${ref.sourceId}`;
   const armed = host.typedRedriveBackoff.get(backoffKey);
   if (armed) {
@@ -29482,8 +29588,8 @@ async function consumeTypedDispatch(host, ref, run, ack) {
       return;
   }
   const settleAck = (ackResult) => ackResult !== false;
-  const settle = (acked2) => {
-    if (acked2) {
+  const settle = (resolved2) => {
+    if (resolved2) {
       host.typedRedriveBackoff.delete(backoffKey);
       return;
     }
@@ -29497,13 +29603,13 @@ async function consumeTypedDispatch(host, ref, run, ack) {
     host.typedRedriveBackoff.set(backoffKey, { failures, until: Date.now() + backoffMs });
   };
   const runLegacy = async () => {
-    let acked2 = false;
+    let acked = false;
     try {
       if (await run(ref.dispatchEventId)) {
-        acked2 = settleAck(await ack(ref.dispatchEventId));
+        acked = settleAck(await hooks.legacyAck(ref.dispatchEventId));
       }
     } finally {
-      settle(acked2);
+      settle(acked);
     }
   };
   if (!host.laneLedger || host.ledgerDisabled) {
@@ -29525,15 +29631,39 @@ async function consumeTypedDispatch(host, ref, run, ack) {
     host.opts.log?.info(`typed dispatch ${ref.dispatchEventId ?? `${ref.sourceType}:${ref.sourceId}`} not claimable (held elsewhere or already resolved) \u2014 skipping`);
     return;
   }
-  let acked = false;
+  let resolved = false;
+  let viaLegacyAck = false;
   try {
     if (await run(lane.typedDispatchEventId)) {
-      acked = settleAck(await ack(lane.typedDispatchEventId));
+      if (host.typedByIdCompleteUnsupported || !lane.typedDispatchEventId) {
+        viaLegacyAck = true;
+        resolved = settleAck(await hooks.legacyAck(lane.typedDispatchEventId));
+      } else {
+        const outcome = await resolveDispatchByID(host, lane.typedDispatchEventId, lane.lane);
+        if (outcome === "unsupported") {
+          host.typedByIdCompleteUnsupported = true;
+          host.opts.log?.warn("server predates the by-id dispatch complete \u2014 falling back to the legacy typed ack");
+          viaLegacyAck = true;
+          resolved = settleAck(await hooks.legacyAck(lane.typedDispatchEventId));
+        } else if (outcome === "stale") {
+          hooks.clearDedupe?.();
+          resolved = true;
+        } else {
+          resolved = outcome === "ok";
+          if (!resolved) {
+            hooks.clearDedupe?.();
+          }
+        }
+      }
     }
   } finally {
-    settle(acked);
-    await host.laneLedger.completeIfIdle(lane.laneKey, false).catch(() => {
-    });
+    settle(resolved);
+    if (resolved && !viaLegacyAck) {
+      host.laneLedger.dropLocal(lane.laneKey);
+    } else {
+      await host.laneLedger.completeIfIdle(lane.laneKey, false).catch(() => {
+      });
+    }
   }
 }
 async function consumeMessageWorkItem(host, item) {
@@ -29542,6 +29672,16 @@ async function consumeMessageWorkItem(host, item) {
   if (!host.tryClaimMessage(item.source_id))
     return;
   const ackItem = () => {
+    if (host.laneLedger && !host.ledgerDisabled && !host.typedByIdCompleteUnsupported) {
+      void resolveDispatchByID(host, item.id).then((outcome) => {
+        if (outcome === "unsupported") {
+          host.typedByIdCompleteUnsupported = true;
+          host.opts.client.ackDispatchByID(host.opts.config.org_id, item.id).catch(() => {
+          });
+        }
+      });
+      return;
+    }
     host.opts.client.ackDispatchByID(host.opts.config.org_id, item.id).catch(() => {
     });
   };
@@ -30721,20 +30861,23 @@ var ParallAgentGateway = class {
       if (data.status !== "todo" && data.status !== "in_progress")
         return;
       try {
-        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) {
-            return this.ackDispatchEvent(dispatchEventId, () => {
+        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), {
+          legacyAck: (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) => {
               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) => {
-            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) {
         this.opts.log?.error(`task dispatch failed for ${data.id}: ${String(err)}`);
@@ -30753,7 +30896,10 @@ var ParallAgentGateway = class {
         if (!data.source_id || !data.task_id)
           return;
         try {
-          await this.consumeTypedDispatch({ dispatchEventId: data.id }, () => this.handleTaskComment(data.source_id, data.task_id ?? "", data.actor_id, data.delivery_reason), () => this.ackDispatchEvent(data.id, () => this.clearTypedDispatchDedupe(data)));
+          await this.consumeTypedDispatch({ dispatchEventId: data.id }, (dispatchEventId) => this.handleTaskComment(data.source_id, data.task_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(`task comment dispatch failed for ${data.source_id}: ${String(err)}`);
         }
@@ -30761,7 +30907,10 @@ var ParallAgentGateway = class {
         if (!data.source_id)
           return;
         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)));
+          await this.consumeTypedDispatch({ dispatchEventId: data.id }, (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(`wiki comment dispatch failed for ${data.source_id}: ${String(err)}`);
         }
@@ -30772,7 +30921,10 @@ var ParallAgentGateway = class {
           await this.consumeTypedDispatch({ dispatchEventId: data.id }, (dispatchEventId) => this.handleTaskDispatch(data.task_id ?? "", data.source_id ?? data.task_id ?? "", {
             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)}`);
         }
@@ -30780,7 +30932,10 @@ var ParallAgentGateway = class {
         if (!data.source_id)
           return;
         try {
-          await this.consumeTypedDispatch({ dispatchEventId: data.id }, () => this.fetchAndHandleScheduleFire(data.source_id, data.actor_id), () => this.ackDispatchEvent(data.id, () => this.clearTypedDispatchDedupe(data)));
+          await this.consumeTypedDispatch({ dispatchEventId: data.id }, (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(`schedule fire dispatch failed for ${data.source_id}: ${String(err)}`);
         }
@@ -30788,7 +30943,10 @@ var ParallAgentGateway = class {
         if (!data.source_id)
           return;
         try {
-          await this.consumeTypedDispatch({ dispatchEventId: data.id }, () => this.fetchAndHandleExternalTriggerRun(data.source_id), () => this.ackDispatchEvent(data.id, () => this.clearTypedDispatchDedupe(data)));
+          await this.consumeTypedDispatch({ dispatchEventId: data.id }, (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(`external trigger dispatch failed for ${data.source_id}: ${String(err)}`);
         }
@@ -30796,7 +30954,10 @@ var ParallAgentGateway = class {
         if (!data.source_id)
           return;
         try {
-          await this.consumeTypedDispatch({ dispatchEventId: data.id }, () => this.fetchAndHandleChannelMessage(data.source_id), () => this.ackDispatchEvent(data.id, () => this.clearTypedDispatchDedupe(data)));
+          await this.consumeTypedDispatch({ dispatchEventId: data.id }, (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(`channel message dispatch failed for ${data.source_id}: ${String(err)}`);
         }
@@ -30804,7 +30965,10 @@ var ParallAgentGateway = class {
         if (!data.source_id)
           return;
         try {
-          await this.consumeTypedDispatch({ dispatchEventId: data.id }, () => this.fetchAndHandleApprovalDecided(data.source_id, data.actor_id, data.chat_id ?? null), () => this.ackDispatchEvent(data.id, () => this.clearTypedDispatchDedupe(data)));
+          await this.consumeTypedDispatch({ dispatchEventId: data.id }, (dispatchEventId) => this.fetchAndHandleApprovalDecided(data.source_id, data.actor_id, data.chat_id ?? null, dispatchEventId), {
+            legacyAck: () => this.ackDispatchEvent(data.id, () => this.clearTypedDispatchDedupe(data)),
+            clearDedupe: () => this.clearTypedDispatchDedupe(data)
+          });
         } catch (err) {
           this.opts.log?.error(`approval decided dispatch failed for ${data.source_id}: ${String(err)}`);
         }
@@ -30887,6 +31051,20 @@ var ParallAgentGateway = class {
       source_id: sourceId
     });
   }
+  /**
+   * 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.
+  typedLedgerEventIds(events) {
+    return typedLedgerEventIds(this.laneFlowHost(), events);
+  }
+  resolveDispatchByID(dispatchEventId, lane) {
+    return resolveDispatchByID(this.laneFlowHost(), dispatchEventId, lane);
+  }
   /** 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);
@@ -30917,15 +31095,16 @@ var ParallAgentGateway = class {
   dispatchLaneGroup(opts) {
     return dispatchLaneGroup(this.laneFlowHost(), opts);
   }
-  consumeTypedDispatch(ref, run, ack) {
-    return consumeTypedDispatch(this.laneFlowHost(), ref, run, ack);
+  consumeTypedDispatch(ref, run, hooks) {
+    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.
   ackDispatchEvent(dispatchEventId, onFailure) {
     return this.opts.client.ackDispatchByID(this.opts.config.org_id, dispatchEventId).then(() => true, (err) => {
       onFailure?.();
@@ -30933,6 +31112,9 @@ var ParallAgentGateway = class {
       return false;
     });
   }
+  // 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).
   clearTypedDispatchDedupe(item) {
     switch (item.event_type) {
       case "task_assign":
@@ -31506,6 +31688,12 @@ var ParallAgentGateway = class {
             dispatched = outcome === "dispatched";
           } else {
             dispatched = await this.runDispatch(last, fork.fork.sessionKey, buildForkScopePrefix(last) + buildEventBody(last), earlier, batchText);
+            if (dispatched && this.typedLedgerEventIds(events) && this.consumeTurnError(fork.fork.sessionKey)) {
+              this.opts.log?.info(`typed fork turn for ${last.messageId} surfaced a runtime error \u2014 releasing for retry`);
+              for (const item of items)
+                item.resolve(false);
+              continue;
+            }
           }
           if (!dispatched) {
             for (const item of items) {
@@ -31655,13 +31843,16 @@ var ParallAgentGateway = class {
           }
           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;
+        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, this.opts.runtimeKey, forkPrefix + buildEventBody(event), earlier);
         if (!dispatched) {
@@ -31669,6 +31860,10 @@ var ParallAgentGateway = class {
           this.dispatchState.pendingForkResults.unshift(...pendingFork);
           break;
         }
+        if (typedRefs) {
+          await settleDrainedTypedGroup(this.laneFlowHost(), events, typedRefs, this.consumeTurnError(this.opts.runtimeKey));
+          continue;
+        }
         for (const bufferedEvent of events) {
           const sourceType = bufferedEvent.ackSourceType ?? (bufferedEvent.type === "task" ? "task_activity" : "message");
           const sourceId = bufferedEvent.ackSourceId ?? bufferedEvent.messageId;
@@ -31728,20 +31923,27 @@ var ParallAgentGateway = class {
           }
           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 = void 0;
-          this.mainCurrentGroupKey = void 0;
-          this.dispatchState.mainPreDispatchBranchPoint = void 0;
-          this.dispatchState.pendingForkResults.unshift(...pendingFork);
-          return false;
+        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 = void 0;
+            this.mainCurrentGroupKey = void 0;
+            this.dispatchState.mainPreDispatchBranchPoint = void 0;
+            this.dispatchState.pendingForkResults.unshift(...pendingFork);
+            return false;
+          }
         }
         let dispatched = false;
         try {
           dispatched = await this.runDispatch(event, this.opts.runtimeKey, forkPrefix + buildEventBody(event));
+          if (dispatched && typedRefs && this.consumeTurnError(this.opts.runtimeKey)) {
+            this.opts.log?.info(`typed dispatch turn for ${event.messageId} surfaced a runtime error \u2014 releasing for retry`);
+            dispatched = false;
+          }
           if (!dispatched) {
             this.dispatchState.pendingForkResults.unshift(...pendingFork);
           }
@@ -31783,7 +31985,7 @@ var ParallAgentGateway = class {
           this.dispatchState.mainBuffer.push(event);
           return false;
         }
-        if (!this.usesLaneLedger(event)) {
+        if (!this.usesLaneLedger(event) && !this.typedLedgerEventIds([event])) {
           try {
             await this.emitDispatchReceived(event);
           } catch (err) {
@@ -31964,7 +32166,10 @@ var ParallAgentGateway = class {
       return;
     await this.consumeTypedDispatch({ dispatchEventId: item.id }, (dispatchEventId) => 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)
+    });
   }
   consumeMessageWorkItem(item) {
     return consumeMessageWorkItem(this.laneFlowHost(), item);
@@ -32025,7 +32230,7 @@ var ParallAgentGateway = class {
     }
     return this.handleTaskAssignment(task, ackSourceId, opts.dispatchEventId);
   }
-  async handleTaskComment(commentId, taskId, actorId, deliveryReason) {
+  async handleTaskComment(commentId, taskId, actorId, deliveryReason, dispatchEventId) {
     if (this.shuttingDown)
       return false;
     const dedupeKey = `comment:${commentId}`;
@@ -32081,7 +32286,8 @@ var ParallAgentGateway = class {
       body: parts.join("\n"),
       deliveryReason: deliveryReason ?? void 0,
       ackSourceType: "comment",
-      ackSourceId: commentId
+      ackSourceId: commentId,
+      dispatchEventId
     };
     let dispatched;
     try {
@@ -32095,7 +32301,7 @@ var ParallAgentGateway = class {
     }
     return dispatched;
   }
-  async handleWikiComment(commentId, actorId, deliveryReason) {
+  async handleWikiComment(commentId, actorId, deliveryReason, dispatchEventId) {
     if (this.shuttingDown)
       return false;
     const dedupeKey = `comment:${commentId}`;
@@ -32141,7 +32347,8 @@ var ParallAgentGateway = class {
       deliveryReason: deliveryReason ?? void 0,
       replyTargetUri: comment.target_uri,
       ackSourceType: "comment",
-      ackSourceId: commentId
+      ackSourceId: commentId,
+      dispatchEventId
     };
     let dispatched;
     try {
@@ -32163,7 +32370,7 @@ var ParallAgentGateway = class {
    * access to already-delivered run snapshots, and the runtime must not crash
    * or retry forever in that case.
    */
-  async fetchAndHandleScheduleFire(runId, actorId) {
+  async fetchAndHandleScheduleFire(runId, actorId, dispatchEventId) {
     let run = null;
     try {
       run = await this.opts.client.getScheduleRun(this.opts.config.org_id, runId);
@@ -32178,9 +32385,9 @@ var ParallAgentGateway = class {
     }
     if (!run)
       return true;
-    return this.handleScheduleFire(run, actorId);
+    return this.handleScheduleFire(run, actorId, dispatchEventId);
   }
-  async handleScheduleFire(run, actorId) {
+  async handleScheduleFire(run, actorId, dispatchEventId) {
     if (this.shuttingDown)
       return false;
     const dedupeKey = `schedule_run:${run.id}`;
@@ -32203,7 +32410,8 @@ var ParallAgentGateway = class {
       scheduledFireAt: run.scheduled_fire_at,
       attachedUri: run.fired_attached_uri ?? void 0,
       ackSourceType: "schedule_run",
-      ackSourceId: run.id
+      ackSourceId: run.id,
+      dispatchEventId
     };
     let dispatched;
     try {
@@ -32217,7 +32425,7 @@ var ParallAgentGateway = class {
     }
     return dispatched;
   }
-  async fetchAndHandleExternalTriggerRun(runId) {
+  async fetchAndHandleExternalTriggerRun(runId, dispatchEventId) {
     let run = null;
     try {
       run = await this.opts.client.getExternalTriggerRun(this.opts.config.org_id, runId);
@@ -32232,14 +32440,14 @@ var ParallAgentGateway = class {
     }
     if (!run)
       return true;
-    return this.handleExternalTriggerRun(run);
+    return this.handleExternalTriggerRun(run, dispatchEventId);
   }
   // 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) {
+  async fetchAndHandleChannelMessage(messageId, dispatchEventId) {
     if (this.shuttingDown)
       return false;
     const claimKey = `channel_message:${messageId}`;
@@ -32292,7 +32500,8 @@ var ParallAgentGateway = class {
       channelExternalMessageId: msg.external_message_id,
       channelCliCapable: cliCapable,
       ackSourceType: "channel_message",
-      ackSourceId: msg.id
+      ackSourceId: msg.id,
+      dispatchEventId
     };
     let dispatched;
     try {
@@ -32306,7 +32515,7 @@ var ParallAgentGateway = class {
     }
     return dispatched;
   }
-  async handleExternalTriggerRun(run) {
+  async handleExternalTriggerRun(run, dispatchEventId) {
     if (this.shuttingDown)
       return false;
     const dedupeKey = `external_trigger_run:${run.id}`;
@@ -32331,7 +32540,8 @@ var ParallAgentGateway = class {
       externalIngressEventType: run.ingress_event_type || void 0,
       attachedUri,
       ackSourceType: "external_trigger_run",
-      ackSourceId: run.id
+      ackSourceId: run.id,
+      dispatchEventId
     };
     let dispatched;
     try {
@@ -32345,7 +32555,7 @@ var ParallAgentGateway = class {
     }
     return dispatched;
   }
-  async fetchAndHandleApprovalDecided(approvalId, actorId, chatId) {
+  async fetchAndHandleApprovalDecided(approvalId, actorId, chatId, dispatchEventId) {
     let approval = null;
     try {
       approval = await this.opts.client.getApproval(approvalId);
@@ -32376,7 +32586,12 @@ var ParallAgentGateway = class {
       senderId: actorId ?? approval.decided_by ?? "system",
       senderName: "approver",
       messageId: approval.id,
-      body
+      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;
     try {
@@ -32423,7 +32638,17 @@ var ParallAgentGateway = class {
           break;
         if (overflowMode && processed >= CATCHUP_MAX) {
           try {
-            await this.opts.client.ackDispatchByID(this.opts.config.org_id, item.id);
+            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");
+              }
+            } 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);
@@ -32434,12 +32659,15 @@ var ParallAgentGateway = class {
         }
         processed++;
         try {
-          const ackItem = () => this.ackDispatchEvent(item.id, () => this.clearTypedDispatchDedupe(item));
+          const typedHooks = {
+            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({ dispatchEventId: item.id }, (dispatchEventId) => this.handleTaskDispatch(item.task_id ?? "", item.source_id ?? item.task_id ?? "", {
                 dispatchEventId
-              }), ackItem);
+              }), typedHooks);
             } catch (err) {
               this.opts.log?.warn(`catch-up task fetch failed for ${item.task_id}, leaving pending: ${String(err)}`);
               continue;
@@ -32449,23 +32677,23 @@ var ParallAgentGateway = class {
               await this.consumeTypedDispatch({ dispatchEventId: item.id }, (dispatchEventId) => this.handleTaskDispatch(item.task_id ?? "", item.source_id ?? item.task_id ?? "", {
                 allowCreator: true,
                 dispatchEventId
-              }), ackItem);
+              }), typedHooks);
             } catch (err) {
               this.opts.log?.warn(`catch-up task fetch failed for ${item.task_id}, leaving pending: ${String(err)}`);
               continue;
             }
           } else if (item.event_type === "task_comment" && item.source_id && item.task_id) {
-            await this.consumeTypedDispatch({ dispatchEventId: item.id }, () => this.handleTaskComment(item.source_id, item.task_id ?? "", item.actor_id, item.delivery_reason), ackItem);
+            await this.consumeTypedDispatch({ dispatchEventId: item.id }, (dispatchEventId) => this.handleTaskComment(item.source_id, item.task_id ?? "", item.actor_id, item.delivery_reason, dispatchEventId), 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);
+            await this.consumeTypedDispatch({ dispatchEventId: item.id }, (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);
+            await this.consumeTypedDispatch({ dispatchEventId: item.id }, (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);
+            await this.consumeTypedDispatch({ dispatchEventId: item.id }, (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);
+            await this.consumeTypedDispatch({ dispatchEventId: item.id }, (dispatchEventId) => this.fetchAndHandleChannelMessage(item.source_id, dispatchEventId), typedHooks);
           } else if (item.event_type === "approval_decided" && item.source_id) {
-            await this.consumeTypedDispatch({ dispatchEventId: item.id }, () => this.fetchAndHandleApprovalDecided(item.source_id, item.actor_id, item.chat_id ?? null), ackItem);
+            await this.consumeTypedDispatch({ dispatchEventId: item.id }, (dispatchEventId) => this.fetchAndHandleApprovalDecided(item.source_id, item.actor_id, item.chat_id ?? null, dispatchEventId), typedHooks);
           } else if (item.event_type === "message" && item.source_id && item.chat_id) {
             await this.consumeMessageWorkItem({
               id: item.id,
@@ -33163,16 +33391,32 @@ parall tasks list --assignee-id prll://usr_xxx   # first page only (default 20)
 parall tasks subtasks prll://tsk_xxx             # children of a single parent task
 
 # Create a task (add --parent-id to make it a SUBTASK of another task)
-parall tasks create --title "Task title" [--assignee-id prll://usr_xxx] [--parent-id prll://tsk_xxx] [--project-id prll://prj_xxx]
+parall tasks create --title "Task title" [--assignee-id prll://usr_xxx] [--parent-id prll://tsk_xxx] [--project-id prll://prj_xxx] [--due-date 2026-08-01]
 
-# Update task status
-parall tasks update prll://tsk_xxx --status in_progress
-parall tasks update prll://tsk_xxx --status done
+# Update task status \u2014 add --placement end so the task lands at the end of
+# its NEW status column (a bare --status keeps the old column's sort_order)
+parall tasks update prll://tsk_xxx --status in_progress --placement end
+parall tasks update prll://tsk_xxx --status done --placement end
+
+# Due date \u2014 a plain YYYY-MM-DD date (no timestamps); "none" clears it
+parall tasks update prll://tsk_xxx --due-date 2026-08-01
+parall tasks update prll://tsk_xxx --due-date none
+
+# Move a task to the end of its status column
+parall tasks update prll://tsk_xxx --placement end
 
 # Add a comment
 parall tasks comments add prll://tsk_xxx --body "Progress update..."
 \`\`\`
 
+Ordering: to append a task to the end of a status column, always use
+\`--placement end\` \u2014 the server resolves the position atomically. This
+includes status changes: a bare \`--status\` keeps the task's old
+\`sort_order\`, which may collide inside the new column. Do NOT compute a
+\`sort_order\` value yourself from listed tasks (your view may be stale or
+partial). \`--sort-order\` is only for pinpoint insertion between two cards
+you just listed, and it cannot be combined with \`--placement\`.
+
 Subtasks are just tasks with a parent: create one with \`tasks create --parent-id\`,
 re-parent with \`tasks update --parent-id\`, list a parent's children with
 \`tasks subtasks\`. \`tasks list\` without \`--parent-id\` already returns both
@@ -33207,7 +33451,7 @@ watcher.
 When you receive \`[Event: task.assigned]\`:
 
 1. Acknowledge with a comment: \`tasks comments add prll://tsk_xxx --body "On it"\`
-2. Update status: \`tasks update prll://tsk_xxx --status in_progress\`
+2. Update status: \`tasks update prll://tsk_xxx --status in_progress --placement end\`
 3. Do the work
 4. Report results in a comment. If a gate remains \u2014 review, merge, deploy,
    requester acceptance \u2014 set \`in_review\` and name the gate; set \`done\`
@@ -33453,7 +33697,7 @@ parall schedules create \\
   --run-at <FUTURE_RFC3339_TIME>
 \`\`\`
 
-\`--target-ids\` is who receives the fire (usually yourself when you're self-scheduling; another agent or human when delegating). \`--attached-to-uri\` optionally anchors the schedule to a task / chat / project / wiki page \u2014 when that resource is archived or deleted, the schedule auto-cancels (\`cancel_reason=attached_gone\`).
+\`--target-ids\` is who receives the fire (usually yourself when you're self-scheduling; another agent or human when delegating). \`--attached-to-uri\` optionally anchors the schedule to a task / chat / project / wiki page \u2014 when that resource is archived or deleted, the schedule auto-cancels (\`status_reason=attached_gone\`). A schedule whose agent targets all sit on a terminated machine is auto-paused by the platform (\`status_reason=attendee_unreachable\`) instead of firing into a void; resuming a recurring schedule while the machine is still terminated just pauses it again on the next slot (a one-shot resumed past its catch-up window instead follows the normal missed semantics and completes).
 
 ### Reminders for someone else