@parall/parall 1.43.0 → 1.45.0

package/dist/index.bundle.mjs

@@ -26479,13 +26479,13 @@ function laneKeyForTarget(targetUri, threadRootId) {
   return Buffer.from(`${targetUri}
 ${threadRootId ?? ""}`, "utf8").toString("base64url");
 }
+function dispatchLaneContextDir(stateDir) {
+  return path.join(stateDir, "dispatch-lane-context");
+}
 function laneContextFilePath(contextDir, targetUri, threadRootId) {
   return path.join(contextDir, `${laneKeyForTarget(targetUri, threadRootId)}.json`);
 }
 
-// ../agent-core/dist/lane-ledger.js
-import * as fs from "node:fs";
-
 // ../sdk/dist/types.js
 var MENTION_ALL_USER_ID = "all";
 
@@ -27940,7 +27940,6 @@ var ParallClient = class _ParallClient {
   async steerDispatch(orgId, req) {
     return this.request("POST", ENDPOINTS.DISPATCH_STEER(orgId), req);
   }
-  /** End a turn: no_action sweep of the lane's members + lane release + re-drive check. */
   async completeDispatch(orgId, req) {
     return this.request("POST", ENDPOINTS.DISPATCH_COMPLETE(orgId), req);
   }
@@ -27948,6 +27947,10 @@ var ParallClient = class _ParallClient {
    * End a turn for a lane-less runtime: resolve the turn's folded WorkItems
    * by source — broad-cover to the turn's reply Effect when one exists,
    * no_action sweep otherwise. Idempotent.
+   *
+   * @deprecated Legacy ok-only alias — use {@link completeDispatch} with the
+   * `sources` form, which also carries `turn_outcome`. The endpoint retires
+   * at S3b (dispatch-convergence-design.md §3).
    */
   async completeDispatchSources(orgId, req) {
     return this.request("POST", ENDPOINTS.DISPATCH_COMPLETE_SOURCES(orgId), req);
@@ -29094,6 +29097,7 @@ var ParallWs = class {
 };
 
 // ../agent-core/dist/lane-ledger.js
+import * as fs from "node:fs";
 var LedgerUnsupportedError = class extends Error {
 };
 function isStaleLane(err) {
@@ -29153,7 +29157,11 @@ var LaneLedger = class {
         throw err;
       }
       if (!res.claimed || !res.lane) {
-        this.opts.log?.info(`lane for ${targetUri} held by a healthy incumbent \u2014 leaving events pending for re-drive`);
+        if (res.reason === "empty") {
+          this.opts.log?.warn(`claim for ${targetUri} came back empty \u2014 nothing foldable; leaving to the reconciler`);
+        } else {
+          this.opts.log?.info(`lane for ${targetUri} held by a healthy incumbent \u2014 leaving events pending for re-drive`);
+        }
         return null;
       }
       const leaseUntilMs = Date.parse(res.lease_until ?? "");
@@ -29230,6 +29238,18 @@ var LaneLedger = class {
    * re-drives any same-target pending work. A STALE_LANE answer means a
    * takeover already owns the resource — local state is dropped either way.
    */
+  /**
+   * Record that the turn on this lane surfaced a runtime error. The flow
+   * settles an errored lane immediately (dispatchLaneGroup returns 'failed'
+   * after a forced complete), so the bit normally lives for one turn only —
+   * it is the transport between the gateway's per-session error signal and
+   * this lane's complete request.
+   */
+  markTurnError(laneKey) {
+    const lane = this.lanes.get(laneKey);
+    if (lane)
+      lane.turnError = true;
+  }
   async completeIfIdle(laneKey, hasMoreLocal) {
     const lane = this.lanes.get(laneKey);
     if (!lane || hasMoreLocal)
@@ -29240,7 +29260,10 @@ var LaneLedger = class {
       const res = await this.opts.client.completeDispatch(this.opts.orgId, {
         lane: lane.lane,
         target_uri: lane.targetUri,
-        thread_root_id: lane.threadRootId
+        thread_root_id: lane.threadRootId,
+        // An error turn releases its members for retry instead of sweeping
+        // them as handled (ignored by older servers).
+        turn_outcome: lane.turnError ? "error" : "ok"
       });
       if (res.swept_no_action > 0 || res.redriven) {
         this.opts.log?.info(`lane complete for ${lane.targetUri}: swept ${res.swept_no_action} no_action, redriven=${res.redriven}`);
@@ -29253,6 +29276,17 @@ var LaneLedger = class {
       this.opts.log?.warn(`lane complete failed for ${lane.targetUri}: ${String(err)}`);
     }
   }
+  /**
+   * Renew one lane by its key — the external runtime-activity hook for
+   * adapters whose tool traffic bypasses the RuntimeEvent stream (openclaw
+   * hooks). Scoped to the session's own lane: renewing every lane would let
+   * one busy fork keep an unrelated stalled fork's lane leased forever.
+   */
+  renewByKey(laneKey) {
+    const lane = this.lanes.get(laneKey);
+    if (lane)
+      this.maybeRenew(lane);
+  }
   /**
    * Long-turn keepalive: renew the lane's lease on runtime activity, throttled
    * so a chatty turn doesn't spam the server. Without this, a legitimately
@@ -29347,6 +29381,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
@@ -29394,25 +29442,136 @@ async function dispatchLaneGroup(host, opts) {
     }
     return "foreign";
   }
+  host.noteSessionLane(opts.sessionKey, lane.laneKey);
   let dispatched = false;
   try {
     dispatched = await host.runDispatch(event, opts.sessionKey, opts.body, opts.earlier, opts.captureText);
   } catch (err) {
+    host.noteSessionLane(opts.sessionKey, null);
     await ledger.release(lane.laneKey).catch(() => {
     });
     throw err;
+  } finally {
+    if (dispatched)
+      host.noteSessionLane(opts.sessionKey, null);
   }
   if (!dispatched) {
     return "shutdown";
   }
+  if (host.consumeTurnError(opts.sessionKey)) {
+    ledger.markTurnError(lane.laneKey);
+    for (const msgId of lane.folded.keys()) {
+      host.dispatchedMessages.delete(msgId);
+    }
+    try {
+      host.opts.dispatchAdapter.abortDispatch?.(opts.sessionKey);
+    } catch {
+    }
+    await ledger.completeIfIdle(lane.laneKey, false);
+    return "failed";
+  }
   const pendingInjections = host.opts.dispatchAdapter.hasPendingInjections?.(opts.sessionKey) ?? false;
   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) {
@@ -29428,8 +29587,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;
     }
@@ -29443,13 +29602,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) {
@@ -29471,15 +29630,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) {
@@ -29488,6 +29671,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(() => {
     });
   };
@@ -30608,20 +30801,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)}`);
@@ -30640,7 +30836,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)}`);
         }
@@ -30648,7 +30847,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)}`);
         }
@@ -30659,7 +30861,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)}`);
         }
@@ -30667,7 +30872,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)}`);
         }
@@ -30675,7 +30883,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)}`);
         }
@@ -30683,7 +30894,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)}`);
         }
@@ -30691,7 +30905,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)}`);
         }
@@ -30728,6 +30945,44 @@ var ParallAgentGateway = class {
     this.dispatchedMessages.add(id);
     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).
+   */
+  sessionActiveLanes = /* @__PURE__ */ new Map();
+  noteSessionLane(sessionKey, laneKey) {
+    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) {
+    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. */
+  turnErrorSessions = /* @__PURE__ */ new Set();
+  /**
+   * 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) {
+    return this.turnErrorSessions.delete(sessionKey);
+  }
   async emitDispatchReceived(event) {
     const sourceType = event.ackSourceType ?? (event.type === "task" ? "task_activity" : "message");
     const sourceId = event.ackSourceId ?? event.messageId;
@@ -30736,6 +30991,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);
@@ -30766,15 +31035,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?.();
@@ -30782,6 +31052,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":
@@ -31077,6 +31350,7 @@ var ParallAgentGateway = class {
       this.pendingRestartNotification = null;
     }
     resetDispatchMetrics(sessionKey);
+    this.turnErrorSessions.delete(sessionKey);
     return runWithSessionKey(sessionKey, async () => {
       let dispatchSpan = null;
       setSessionChatId(sessionKey, event.targetId);
@@ -31184,6 +31458,9 @@ var ParallAgentGateway = class {
           } else if (runtimeEvent.type === "tool_result" && pendingSendCallIds.delete(runtimeEvent.callId)) {
             recordMessageSend(sessionKey, !runtimeEvent.error);
           }
+          if (runtimeEvent.type === "error") {
+            this.turnErrorSessions.add(sessionKey);
+          }
           await this.createRuntimeStep(binding.agentSessionId, event, runtimeEvent, stepIdFilePath, contextFilePath, laneContextFilePath2);
         }
         if (!binding) {
@@ -31331,16 +31608,32 @@ var ParallAgentGateway = class {
               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") {
               for (const item of items)
                 item.resolve(false);
               break;
             }
+            if (outcome === "failed") {
+              for (const item of items)
+                item.resolve(false);
+              continue;
+            }
             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) {
@@ -31371,6 +31664,7 @@ var ParallAgentGateway = class {
         remaining.resolve(false);
       }
     } finally {
+      this.turnErrorSessions.delete(fork.fork.sessionKey);
       if (fork.deadlineTimer) {
         clearTimeout(fork.deadlineTimer);
         fork.deadlineTimer = null;
@@ -31483,15 +31777,22 @@ var ParallAgentGateway = class {
             this.dispatchState.pendingForkResults.unshift(...pendingFork);
             continue;
           }
+          if (outcome === "failed") {
+            this.dispatchState.pendingForkResults.unshift(...pendingFork);
+            continue;
+          }
           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) {
@@ -31499,6 +31800,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;
@@ -31558,20 +31863,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);
           }
@@ -31586,7 +31898,7 @@ var ParallAgentGateway = class {
         }
         this.dispatchState.mainBuffer.push(event);
         if (this.usesLaneLedger(event)) {
-          if (this.mainCurrentGroupKey === this.dispatchGroupKey(event) && await this.laneLedger?.steerLive(event) && await this.opts.dispatchAdapter.enqueueDuringDispatch?.(this.opts.runtimeKey, buildEventBody(event))) {
+          if (this.mainCurrentGroupKey === this.dispatchGroupKey(event) && this.opts.dispatchAdapter.enqueueDuringDispatch != null && await this.laneLedger?.steerLive(event) && await this.opts.dispatchAdapter.enqueueDuringDispatch(this.opts.runtimeKey, buildEventBody(event))) {
             this.opts.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))) {
@@ -31613,12 +31925,14 @@ var ParallAgentGateway = class {
           this.dispatchState.mainBuffer.push(event);
           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;
+        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,
@@ -31792,7 +32106,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);
@@ -31853,7 +32170,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}`;
@@ -31909,7 +32226,8 @@ var ParallAgentGateway = class {
       body: parts.join("\n"),
       deliveryReason: deliveryReason ?? void 0,
       ackSourceType: "comment",
-      ackSourceId: commentId
+      ackSourceId: commentId,
+      dispatchEventId
     };
     let dispatched;
     try {
@@ -31923,7 +32241,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}`;
@@ -31969,7 +32287,8 @@ var ParallAgentGateway = class {
       deliveryReason: deliveryReason ?? void 0,
       replyTargetUri: comment.target_uri,
       ackSourceType: "comment",
-      ackSourceId: commentId
+      ackSourceId: commentId,
+      dispatchEventId
     };
     let dispatched;
     try {
@@ -31991,7 +32310,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);
@@ -32006,9 +32325,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}`;
@@ -32031,7 +32350,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 {
@@ -32045,7 +32365,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);
@@ -32060,14 +32380,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}`;
@@ -32120,7 +32440,8 @@ var ParallAgentGateway = class {
       channelExternalMessageId: msg.external_message_id,
       channelCliCapable: cliCapable,
       ackSourceType: "channel_message",
-      ackSourceId: msg.id
+      ackSourceId: msg.id,
+      dispatchEventId
     };
     let dispatched;
     try {
@@ -32134,7 +32455,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}`;
@@ -32159,7 +32480,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 {
@@ -32173,7 +32495,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);
@@ -32204,7 +32526,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 {
@@ -32251,7 +32578,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);
@@ -32262,12 +32599,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;
@@ -32277,23 +32617,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,
@@ -33873,6 +34213,10 @@ function cleanupForkSession(opts) {
 }
 
 // dist/gateway.js
+function sessionContextFilePath(stateDir, sessionKey) {
+  const fileName = Buffer.from(sessionKey).toString("base64url");
+  return path8.join(stateDir, "dispatch-context", `${fileName}.json`);
+}
 function resolveWsUrl(account) {
   if (account.config.ws_url)
     return account.config.ws_url;
@@ -34242,6 +34586,18 @@ var parallGateway = {
         runtimeKey: orchestratorKey,
         runtimeRef: { hostname: os2.hostname(), pid: process.pid },
         dispatchAdapter,
+        // Opts openclaw into the dispatch ledger (claim/fold/complete +
+        // idempotent reply effects) — the same shared-gateway machinery
+        // claude/codex ride; openclaw stays buffer-only (no mid-turn steer),
+        // which the ledger does not require. Replies already flow through
+        // @parall/cli, which reads PRLL_CONTEXT_DIR (injected in hooks.ts)
+        // to bind dispatch_lane + reply effect keys.
+        // Design: docs/engineering-design/dispatch-convergence-design.md §7 (S2).
+        dispatchContextDir: dispatchLaneContextDir(stateDir),
+        // Per-session context file (PRLL_CONTEXT_FILE contract) — the CLI's
+        // TYPED dispatch binding (parall tasks update → task_update effect)
+        // reads lane/event/task fields from this file, not the lane dir.
+        contextFilePathForSession: (sessionKey) => sessionContextFilePath(stateDir, sessionKey),
         log: otelLog,
         // Live capability view for hint routing: the channel reply hint
         // points at the vendor CLI only while the grant is active.
@@ -34265,7 +34621,13 @@ var parallGateway = {
             runtimeRef: { hostname: os2.hostname(), pid: process.pid },
             wikiMountRoot,
             ws,
-            orchestratorSessionKey: orchestratorKey
+            orchestratorSessionKey: orchestratorKey,
+            dispatchContextDir: dispatchLaneContextDir(stateDir),
+            contextFilePathForSession: (sessionKey) => sessionContextFilePath(stateDir, sessionKey),
+            // Lease-renewal bridge: openclaw tool calls flow through hooks,
+            // not the RuntimeEvent stream, so hook activity must renew the
+            // ledger lanes or a long exec outlives the lease (STALE_LANE).
+            touchRuntimeActivity: (sessionKey) => gateway.touchRuntimeActivity(sessionKey)
           });
         },
         onSessionBinding: async ({ sessionKey, agentSessionId }) => {
@@ -34450,10 +34812,41 @@ function registerParallHooks(api) {
     };
   });
   const pendingSendCalls = /* @__PURE__ */ new Map();
+  const laneRenewals = /* @__PURE__ */ new Map();
+  const LANE_RENEW_INTERVAL_MS = 18e4;
+  const beginToolRenewal = (sessionKey) => {
+    const accountId = extractAccountIdFromSessionKey(sessionKey);
+    const state = accountId ? getParallAccountState(accountId) : void 0;
+    if (!state?.touchRuntimeActivity)
+      return;
+    state.touchRuntimeActivity(sessionKey);
+    const entry = laneRenewals.get(sessionKey) ?? { count: 0 };
+    entry.count++;
+    if (!entry.timer) {
+      entry.timer = setInterval(() => state.touchRuntimeActivity?.(sessionKey), LANE_RENEW_INTERVAL_MS);
+      entry.timer.unref?.();
+    }
+    laneRenewals.set(sessionKey, entry);
+  };
+  const endToolRenewal = (sessionKey) => {
+    const entry = laneRenewals.get(sessionKey);
+    if (entry) {
+      entry.count--;
+      if (entry.count <= 0) {
+        if (entry.timer)
+          clearInterval(entry.timer);
+        laneRenewals.delete(sessionKey);
+      }
+    }
+    const accountId = extractAccountIdFromSessionKey(sessionKey);
+    const state = accountId ? getParallAccountState(accountId) : void 0;
+    state?.touchRuntimeActivity?.(sessionKey);
+  };
   api.on("before_tool_call", async (event, ctx) => {
     const sessionKey = ctx.sessionKey;
     if (sessionKey) {
       recordToolCall(sessionKey);
+      beginToolRenewal(sessionKey);
       if (event.toolName === "exec" && event.toolCallId) {
         const command = event.params?.command;
         if (isParallSendCommand(command)) {
@@ -34522,6 +34915,12 @@ function registerParallHooks(api) {
       injectedEnv.PRLL_TRIGGER_MESSAGE_ID = triggerMsgId;
     if (state.wikiMountRoot)
       injectedEnv.PRLL_WIKI_MOUNT_ROOT = state.wikiMountRoot;
+    if (state.dispatchContextDir)
+      injectedEnv.PRLL_CONTEXT_DIR = state.dispatchContextDir;
+    if (state.contextFilePathForSession) {
+      injectedEnv.PRLL_CONTEXT_FILE = state.contextFilePathForSession(sessionKey);
+    }
+    state.touchRuntimeActivity?.(sessionKey);
     injectedEnv.OPENCLAW_SESSION_KEY = sessionKey;
     if (event.toolCallId)
       injectedEnv.OPENCLAW_TOOL_CALL_ID = event.toolCallId;
@@ -34533,6 +34932,8 @@ function registerParallHooks(api) {
     };
   });
   api.on("after_tool_call", async (event, ctx) => {
+    if (ctx.sessionKey)
+      endToolRenewal(ctx.sessionKey);
     if (ctx.sessionKey && event.toolCallId && pendingSendCalls.delete(event.toolCallId)) {
       recordMessageSend(ctx.sessionKey, !event.error);
     }