@parall/parall 1.43.0 → 1.44.0

package/dist/gateway.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"gateway.d.ts","sourceRoot":"","sources":["../src/gateway.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAE9D,uGAAuG;AACvG,KAAK,qBAAqB,CAAC,CAAC,GAAG,OAAO,IAAI,WAAW,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC;AACnF,OAAO,EAQL,KAAK,eAAe,EAGrB,MAAM,oBAAoB,CAAC;AAqB5B,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAiKxD,wBAAgB,6BAA6B,CAAC,IAAI,EAAE;IAClD,IAAI,EAAE,aAAa,CAAC;IACpB,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;CACtB,GAAG,eAAe,CA0KlB;AAED,eAAO,MAAM,aAAa,EAAE,qBAAqB,CAAC,qBAAqB,CAiKtE,CAAC"}
+{"version":3,"file":"gateway.d.ts","sourceRoot":"","sources":["../src/gateway.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAE9D,uGAAuG;AACvG,KAAK,qBAAqB,CAAC,CAAC,GAAG,OAAO,IAAI,WAAW,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC;AACnF,OAAO,EASL,KAAK,eAAe,EAGrB,MAAM,oBAAoB,CAAC;AAqB5B,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AA2KxD,wBAAgB,6BAA6B,CAAC,IAAI,EAAE;IAClD,IAAI,EAAE,aAAa,CAAC;IACpB,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;CACtB,GAAG,eAAe,CA0KlB;AAED,eAAO,MAAM,aAAa,EAAE,qBAAqB,CAAC,qBAAqB,CAqLtE,CAAC"}

package/dist/gateway.js

@@ -1,4 +1,4 @@
-import { ParallAgentGateway, capabilityBinDir, parseShutdownDeadlineMs, parseForkDeadlineMs, parseDispatchDeadlineMs, initAgentTelemetry, createOtelLogger, } from '@parall/agent-core';
+import { ParallAgentGateway, capabilityBinDir, dispatchLaneContextDir, parseShutdownDeadlineMs, parseForkDeadlineMs, parseDispatchDeadlineMs, initAgentTelemetry, createOtelLogger, } from '@parall/agent-core';
 import { appendPreparedLocalAttachmentRefs, ensureLocalAttachmentGitExclude, pinLocalAttachmentPaths, } from '@parall/agent-core/internal/attachment-input';
 import { ApiError, ParallClient, ParallWs } from '@parall/sdk';
 import * as crypto from 'node:crypto';
@@ -11,6 +11,15 @@ import { fetchAndApplyPlatformConfig, getChannelCapabilityKeys } from './config-
 import { startWikiHelper } from './wiki-helper.js';
 import { SessionManager } from './oc-session.js';
 import { cleanupForkSession, clearSessionState, forkOrchestratorSession, resolveSessionId, resolveTranscriptFile, } from './fork.js';
+/**
+ * Per-session dispatch context file (PRLL_CONTEXT_FILE contract) — same
+ * encoding as the claude/codex bridges: base64url(sessionKey) under the
+ * state dir's dispatch-context/.
+ */
+function sessionContextFilePath(stateDir, sessionKey) {
+    const fileName = Buffer.from(sessionKey).toString('base64url');
+    return path.join(stateDir, 'dispatch-context', `${fileName}.json`);
+}
 function resolveWsUrl(account) {
     if (account.config.ws_url)
         return account.config.ws_url;
@@ -404,6 +413,18 @@ export const parallGateway = {
                 runtimeKey: orchestratorKey,
                 runtimeRef: { hostname: os.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.
@@ -428,6 +449,12 @@ export const parallGateway = {
                         wikiMountRoot,
                         ws,
                         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 }) => {

package/dist/hooks.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"hooks.d.ts","sourceRoot":"","sources":["../src/hooks.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAgH7D,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,iBAAiB,QAmLzD"}
+{"version":3,"file":"hooks.d.ts","sourceRoot":"","sources":["../src/hooks.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAgH7D,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,iBAAiB,QA+OzD"}

package/dist/hooks.js

@@ -118,6 +118,45 @@ export function registerParallHooks(api) {
         };
     });
     const pendingSendCalls = new Map();
+    // Lane lease keepalive across the tool-call lifecycle. OpenClaw tool calls
+    // bypass the RuntimeEvent stream, so lane renewal must ride these hooks —
+    // and a ONE-SHOT touch at tool start is not enough: a single exec running
+    // past the lane TTL (10min server-side) would still be dethroned mid-call
+    // and the eventual CLI reply would die with STALE_LANE. While any tool call
+    // is in flight for a session, an unref'd interval keeps touching; the
+    // half-TTL throttle in the ledger decides when a real heartbeat is sent.
+    const laneRenewals = new Map();
+    const LANE_RENEW_INTERVAL_MS = 180_000;
+    const beginToolRenewal = (sessionKey) => {
+        const accountId = extractAccountIdFromSessionKey(sessionKey);
+        const state = accountId ? getParallAccountState(accountId) : undefined;
+        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) : undefined;
+        // Final touch on completion — covers the reply window right after a
+        // long tool call ends.
+        state?.touchRuntimeActivity?.(sessionKey);
+    };
     // before_tool_call -> (1) update dispatch metrics, (2) await step creation, (3) ENV injection
     // OpenClaw tool calls bypass the RuntimeEvent stream (they go through hooks, not the
     // gateway-base for-await loop), so dispatch metrics must be updated here as well.
@@ -125,6 +164,9 @@ export function registerParallHooks(api) {
         const sessionKey = ctx.sessionKey;
         if (sessionKey) {
             recordToolCall(sessionKey);
+            // Every tool (not just exec) keeps the ledger lane alive for its
+            // whole lifetime — see laneRenewals above.
+            beginToolRenewal(sessionKey);
             if (event.toolName === 'exec' && event.toolCallId) {
                 const command = event.params?.command;
                 if (isParallSendCommand(command)) {
@@ -209,6 +251,20 @@ export function registerParallHooks(api) {
             injectedEnv.PRLL_TRIGGER_MESSAGE_ID = triggerMsgId;
         if (state.wikiMountRoot)
             injectedEnv.PRLL_WIKI_MOUNT_ROOT = state.wikiMountRoot;
+        // Dispatch-ledger contract: the CLI keys into this directory by send
+        // target to bind dispatch_lane + the reply:<dsp> effect key (idempotent
+        // replies). Set only when the gateway runs the ledger.
+        if (state.dispatchContextDir)
+            injectedEnv.PRLL_CONTEXT_DIR = state.dispatchContextDir;
+        // Per-session context file — the CLI's TYPED binding (parall tasks
+        // update → task_update:<dsp> effect) reads lane/event/task from here.
+        if (state.contextFilePathForSession) {
+            injectedEnv.PRLL_CONTEXT_FILE = state.contextFilePathForSession(sessionKey);
+        }
+        // Long tool calls bypass the RuntimeEvent stream — forward activity so
+        // the ledger lane lease renews (a >TTL exec would otherwise be dethroned
+        // mid-turn and the eventual CLI reply would die with STALE_LANE).
+        state.touchRuntimeActivity?.(sessionKey);
         // OpenClaw context (upstream doesn't inject these into exec env yet)
         injectedEnv.OPENCLAW_SESSION_KEY = sessionKey;
         if (event.toolCallId)
@@ -223,6 +279,8 @@ export function registerParallHooks(api) {
     });
     // after_tool_call -> track CLI outcomes + send tool_result step to AgentSession
     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);
         }

package/dist/index.bundle.mjs

@@ -26479,6 +26479,9 @@ 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`);
 }
@@ -27940,7 +27943,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 +27950,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);
@@ -29153,7 +29159,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 +29240,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 +29262,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 +29278,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
@@ -29394,17 +29430,34 @@ 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";
@@ -30728,6 +30781,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;
@@ -31077,6 +31168,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 +31276,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,13 +31426,23 @@ 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);
@@ -31371,6 +31476,7 @@ var ParallAgentGateway = class {
         remaining.resolve(false);
       }
     } finally {
+      this.turnErrorSessions.delete(fork.fork.sessionKey);
       if (fork.deadlineTimer) {
         clearTimeout(fork.deadlineTimer);
         fork.deadlineTimer = null;
@@ -31483,6 +31589,10 @@ var ParallAgentGateway = class {
             this.dispatchState.pendingForkResults.unshift(...pendingFork);
             continue;
           }
+          if (outcome === "failed") {
+            this.dispatchState.pendingForkResults.unshift(...pendingFork);
+            continue;
+          }
           continue;
         }
         try {
@@ -31586,7 +31696,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 +31723,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)) {
+          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,
@@ -33873,6 +33985,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 +34358,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 +34393,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 +34584,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 +34687,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 +34704,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);
     }

package/dist/runtime.d.ts

@@ -16,6 +16,23 @@ export type ParallAccountState = {
     wikiMountRoot?: string;
     ws?: ParallWs;
     orchestratorSessionKey?: string;
+    /**
+     * Per-lane dispatch context dir (PRLL_CONTEXT_DIR contract) — set when the
+     * gateway runs the dispatch ledger; hooks inject it into exec env so the
+     * CLI binds replies to their dispatch lane.
+     */
+    dispatchContextDir?: string;
+    /**
+     * Per-session dispatch context file resolver (PRLL_CONTEXT_FILE contract)
+     * — the CLI's typed dispatch binding (task_update effects) reads from it.
+     */
+    contextFilePathForSession?: (sessionKey: string) => string;
+    /**
+     * Lease-renewal bridge into the gateway: openclaw tool activity flows
+     * through hooks (not the RuntimeEvent stream), so hooks must forward it or
+     * a long exec outlives the lane lease.
+     */
+    touchRuntimeActivity?: (sessionKey: string) => void;
     [key: string]: unknown;
 };
 export declare function setParallRuntime(next: PluginRuntime): void;

package/dist/runtime.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../src/runtime.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,KAAK,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAC1D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACxD,YAAY,EAAE,UAAU,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjF,OAAO,EACL,gBAAgB,EAChB,gBAAgB,EAChB,mBAAmB,EACnB,mBAAmB,EACnB,qBAAqB,EACrB,oBAAoB,EACpB,oBAAoB,EACpB,sBAAsB,EACtB,mBAAmB,EACnB,mBAAmB,EACnB,qBAAqB,EACrB,kBAAkB,EAClB,kBAAkB,EAClB,oBAAoB,GACrB,MAAM,oBAAoB,CAAC;AAE5B,MAAM,MAAM,kBAAkB,GAAG;IAC/B,MAAM,EAAE,YAAY,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,eAAe,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACtC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,EAAE,CAAC,EAAE,QAAQ,CAAC;IACd,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB,CAAC;AAIF,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,aAAa,QAEnD;AAED,wBAAgB,gBAAgB,IAAI,aAAa,CAKhD;AAKD,wBAAgB,qBAAqB,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,kBAAkB,QAEjF;AAED,wBAAgB,wBAAwB,CAAC,SAAS,EAAE,MAAM,QAEzD;AAED,wBAAgB,qBAAqB,CAAC,SAAS,EAAE,MAAM,GAAG,kBAAkB,GAAG,SAAS,CAEvF;AAED,wBAAgB,sBAAsB,CACpC,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAClB,cAAc,EAAE,MAAM,QAOvB;AAED,wBAAgB,sBAAsB,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAEhG;AAED,wBAAgB,yBAAyB,IAAI,WAAW,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAEnF;AAID,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,aAAa,QAEvD;AAED,wBAAgB,gBAAgB,IAAI,aAAa,GAAG,SAAS,CAE5D"}
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../src/runtime.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,KAAK,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAC1D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACxD,YAAY,EAAE,UAAU,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjF,OAAO,EACL,gBAAgB,EAChB,gBAAgB,EAChB,mBAAmB,EACnB,mBAAmB,EACnB,qBAAqB,EACrB,oBAAoB,EACpB,oBAAoB,EACpB,sBAAsB,EACtB,mBAAmB,EACnB,mBAAmB,EACnB,qBAAqB,EACrB,kBAAkB,EAClB,kBAAkB,EAClB,oBAAoB,GACrB,MAAM,oBAAoB,CAAC;AAE5B,MAAM,MAAM,kBAAkB,GAAG;IAC/B,MAAM,EAAE,YAAY,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,eAAe,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACtC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,EAAE,CAAC,EAAE,QAAQ,CAAC;IACd,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC;;;;OAIG;IACH,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B;;;OAGG;IACH,yBAAyB,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,MAAM,CAAC;IAC3D;;;;OAIG;IACH,oBAAoB,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,IAAI,CAAC;IACpD,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB,CAAC;AAIF,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,aAAa,QAEnD;AAED,wBAAgB,gBAAgB,IAAI,aAAa,CAKhD;AAKD,wBAAgB,qBAAqB,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,kBAAkB,QAEjF;AAED,wBAAgB,wBAAwB,CAAC,SAAS,EAAE,MAAM,QAEzD;AAED,wBAAgB,qBAAqB,CAAC,SAAS,EAAE,MAAM,GAAG,kBAAkB,GAAG,SAAS,CAEvF;AAED,wBAAgB,sBAAsB,CACpC,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAClB,cAAc,EAAE,MAAM,QAOvB;AAED,wBAAgB,sBAAsB,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAEhG;AAED,wBAAgB,yBAAyB,IAAI,WAAW,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAEnF;AAID,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,aAAa,QAEvD;AAED,wBAAgB,gBAAgB,IAAI,aAAa,GAAG,SAAS,CAE5D"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@parall/parall",
-  "version": "1.43.0",
+  "version": "1.44.0",
   "description": "OpenClaw channel plugin for Parall IM",
   "license": "MIT",
   "repository": {
@@ -16,8 +16,8 @@
     "openclaw.plugin.json"
   ],
   "dependencies": {
-    "@parall/agent-core": "1.43.0",
-    "@parall/sdk": "1.43.0"
+    "@parall/agent-core": "1.44.0",
+    "@parall/sdk": "1.44.0"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",

package/src/gateway.ts

@@ -6,6 +6,7 @@ type ChannelGatewayAdapter<T = unknown> = NonNullable<ChannelPlugin<T>['gateway'
 import {
   ParallAgentGateway,
   capabilityBinDir,
+  dispatchLaneContextDir,
   parseShutdownDeadlineMs,
   parseForkDeadlineMs,
   parseDispatchDeadlineMs,
@@ -47,6 +48,16 @@ import {
   resolveTranscriptFile,
 } from './fork.js';
 
+/**
+ * Per-session dispatch context file (PRLL_CONTEXT_FILE contract) — same
+ * encoding as the claude/codex bridges: base64url(sessionKey) under the
+ * state dir's dispatch-context/.
+ */
+function sessionContextFilePath(stateDir: string, sessionKey: string): string {
+  const fileName = Buffer.from(sessionKey).toString('base64url');
+  return path.join(stateDir, 'dispatch-context', `${fileName}.json`);
+}
+
 function resolveWsUrl(account: ResolvedParallAccount): string {
   if (account.config.ws_url) return account.config.ws_url;
   const base = account.config.parall_url.replace(/\/$/, '');
@@ -482,6 +493,19 @@ export const parallGateway: ChannelGatewayAdapter<ResolvedParallAccount> = {
         runtimeKey: orchestratorKey,
         runtimeRef: { hostname: os.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: string) =>
+          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.
@@ -506,6 +530,13 @@ export const parallGateway: ChannelGatewayAdapter<ResolvedParallAccount> = {
             wikiMountRoot,
             ws,
             orchestratorSessionKey: orchestratorKey,
+            dispatchContextDir: dispatchLaneContextDir(stateDir),
+            contextFilePathForSession: (sessionKey: string) =>
+              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: string) => gateway.touchRuntimeActivity(sessionKey),
           });
         },
         onSessionBinding: async ({ sessionKey, agentSessionId }) => {

package/src/hooks.ts

@@ -140,6 +140,49 @@ export function registerParallHooks(api: OpenClawPluginApi) {
 
   const pendingSendCalls = new Map<string, boolean>();
 
+  // Lane lease keepalive across the tool-call lifecycle. OpenClaw tool calls
+  // bypass the RuntimeEvent stream, so lane renewal must ride these hooks —
+  // and a ONE-SHOT touch at tool start is not enough: a single exec running
+  // past the lane TTL (10min server-side) would still be dethroned mid-call
+  // and the eventual CLI reply would die with STALE_LANE. While any tool call
+  // is in flight for a session, an unref'd interval keeps touching; the
+  // half-TTL throttle in the ledger decides when a real heartbeat is sent.
+  const laneRenewals = new Map<string, { count: number; timer?: ReturnType<typeof setInterval> }>();
+  const LANE_RENEW_INTERVAL_MS = 180_000;
+
+  const beginToolRenewal = (sessionKey: string) => {
+    const accountId = extractAccountIdFromSessionKey(sessionKey);
+    const state = accountId ? getParallAccountState(accountId) : undefined;
+    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: string) => {
+    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) : undefined;
+    // Final touch on completion — covers the reply window right after a
+    // long tool call ends.
+    state?.touchRuntimeActivity?.(sessionKey);
+  };
+
   // before_tool_call -> (1) update dispatch metrics, (2) await step creation, (3) ENV injection
   // OpenClaw tool calls bypass the RuntimeEvent stream (they go through hooks, not the
   // gateway-base for-await loop), so dispatch metrics must be updated here as well.
@@ -147,6 +190,9 @@ export function registerParallHooks(api: OpenClawPluginApi) {
     const sessionKey = ctx.sessionKey;
     if (sessionKey) {
       recordToolCall(sessionKey);
+      // Every tool (not just exec) keeps the ledger lane alive for its
+      // whole lifetime — see laneRenewals above.
+      beginToolRenewal(sessionKey);
       if (event.toolName === 'exec' && event.toolCallId) {
         const command = (event.params as Record<string, unknown>)?.command as string | undefined;
         if (isParallSendCommand(command)) {
@@ -228,6 +274,19 @@ export function registerParallHooks(api: OpenClawPluginApi) {
     }
     if (triggerMsgId) injectedEnv.PRLL_TRIGGER_MESSAGE_ID = triggerMsgId;
     if (state.wikiMountRoot) injectedEnv.PRLL_WIKI_MOUNT_ROOT = state.wikiMountRoot;
+    // Dispatch-ledger contract: the CLI keys into this directory by send
+    // target to bind dispatch_lane + the reply:<dsp> effect key (idempotent
+    // replies). Set only when the gateway runs the ledger.
+    if (state.dispatchContextDir) injectedEnv.PRLL_CONTEXT_DIR = state.dispatchContextDir;
+    // Per-session context file — the CLI's TYPED binding (parall tasks
+    // update → task_update:<dsp> effect) reads lane/event/task from here.
+    if (state.contextFilePathForSession) {
+      injectedEnv.PRLL_CONTEXT_FILE = state.contextFilePathForSession(sessionKey);
+    }
+    // Long tool calls bypass the RuntimeEvent stream — forward activity so
+    // the ledger lane lease renews (a >TTL exec would otherwise be dethroned
+    // mid-turn and the eventual CLI reply would die with STALE_LANE).
+    state.touchRuntimeActivity?.(sessionKey);
 
     // OpenClaw context (upstream doesn't inject these into exec env yet)
     injectedEnv.OPENCLAW_SESSION_KEY = sessionKey;
@@ -247,6 +306,7 @@ export function registerParallHooks(api: OpenClawPluginApi) {
 
   // after_tool_call -> track CLI outcomes + send tool_result step to AgentSession
   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);
     }

package/src/runtime.ts

@@ -32,6 +32,23 @@ export type ParallAccountState = {
   wikiMountRoot?: string;
   ws?: ParallWs;
   orchestratorSessionKey?: string;
+  /**
+   * Per-lane dispatch context dir (PRLL_CONTEXT_DIR contract) — set when the
+   * gateway runs the dispatch ledger; hooks inject it into exec env so the
+   * CLI binds replies to their dispatch lane.
+   */
+  dispatchContextDir?: string;
+  /**
+   * Per-session dispatch context file resolver (PRLL_CONTEXT_FILE contract)
+   * — the CLI's typed dispatch binding (task_update effects) reads from it.
+   */
+  contextFilePathForSession?: (sessionKey: string) => string;
+  /**
+   * Lease-renewal bridge into the gateway: openclaw tool activity flows
+   * through hooks (not the RuntimeEvent stream), so hooks must forward it or
+   * a long exec outlives the lane lease.
+   */
+  touchRuntimeActivity?: (sessionKey: string) => void;
   [key: string]: unknown;
 };