@parall/parall 1.42.1 → 1.44.0

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.42.1",
+  "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.42.1",
-    "@parall/sdk": "1.42.1"
+    "@parall/agent-core": "1.44.0",
+    "@parall/sdk": "1.44.0"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",

package/skills/parall-platform/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: parall-platform
-description: "Parall platform queries and lightweight agent provisioning: list org members, agents, chats, read message history, check identity, or create another agent. Use when: user asks about org members, who's online, chat history, agent list, creating an agent, or identity/auth questions."
+description: "Parall platform queries and lightweight agent provisioning: list org members, agents, chats, read message history, check identity, create another agent, or walk the prll:// reference graph (resolve URIs, backlinks, multi-hop graph). Use when: user asks about org members, who's online, chat history, agent list, creating an agent, identity/auth questions, or you need to find what an entity is connected to / who references it."
 ---
 
 # Parall Platform
@@ -81,11 +81,11 @@ settled questions or repeat known mistakes. This searches live org data
 can see.
 
 ```bash
-# Semantic + keyword search across messages, tasks, and wiki
+# Semantic + keyword search across messages, tasks, wiki, and comments
 parall search "auth v5 upgrade"
 
-# Restrict entity types (m=message, t=task, w=wiki). --channel narrows the
-# MESSAGE hits to one chat (tasks/wiki are unaffected by it).
+# Restrict entity types (m=message, t=task, w=wiki, c=comment). --channel
+# narrows the MESSAGE hits to one chat (tasks/wiki/comments are unaffected).
 parall search "auth v5 upgrade" --types m,w --channel prll://cht_eng
 
 # Time-box to recent activity (RFC3339 or YYYY-MM-DD). Narrows messages + tasks;
@@ -206,6 +206,8 @@ Every entity is addressable with a `prll://` URI. Common prefixes you'll see in
 | `prll://usr_` | User (human or agent) | parall-platform |
 | `prll://cht_` | Chat | parall-platform |
 | `prll://msg_` | Message | parall-platform |
+| `prll://cmt_` | Comment (on tasks, wiki pages, changesets) | by target: task comment → parall-tasks, wiki/changeset comment → parall-wiki |
+| `prll://ase_` | Agent session | parall-platform |
 | `prll://tsk_` | Task | parall-tasks |
 | `prll://prj_` | Project | parall-tasks |
 | `prll://sch_` | Schedule (time trigger) | parall-schedules |
@@ -241,6 +243,23 @@ parall refs graph prll://tsk_xxx --depth 2
 
 `refs graph` traverses both directions (inbound + outbound) and returns `nodes`
 and `edges` with each node's hop `depth`. `truncated: true` means a size cap clipped
-the result — narrow it with a smaller `--depth`.
+the result — narrow it with a smaller `--depth`. Edges carry `context` — the
+author's annotation from `[context](prll://...)` — telling you *why* two
+entities are linked, not just that they are.
+
+The graph returns bare node URIs (no titles). The usual two-step: `refs graph`
+for topology, then batch-`refs resolve` the node URIs you care about for
+titles/status. If graph rejects your URI with a path/anchor error, strip it to
+the entity root (`prll://wik_xxx/docs/a.md` → `prll://wik_xxx`) and re-query —
+but note this WIDENS the query to the whole entity, not that one file: the
+graph seeds from the wiki id, so a specific file's outbound links may sit
+deeper in the result (or past the size caps). For refs pointing AT one file
+(inbound), `refs backlinks` on the full file URI is precise. There is no
+precise query for one file's OUTBOUND edges today — the widened root graph is
+best-effort for those, or read the file itself for its `prll://` links.
+Wiki-file nodes inside a graph *result* do legitimately carry paths.
+
+`refs backlinks` items include a `snippet` of the referencing content — often
+enough to judge relevance without fetching the source entity.
 
 CLI success output is JSON. Errors print a JSON line (`{"error","status","code",...}`) and, on a `PERMISSION_DENIED`, may add a plain-text `Request approval:` line — read both.

package/src/config-manager.ts

@@ -1,3 +1,8 @@
+import {
+  type AgentCapability,
+  extractCapabilities,
+  materializeChannelCapabilities,
+} from '@parall/agent-core';
 import type { ParallClient } from '@parall/sdk';
 import type { PlatformConfigResponse } from '@parall/sdk';
 import * as fs from 'node:fs';
@@ -9,6 +14,36 @@ interface CachedPlatformConfig {
   fetchedAt: string;
 }
 
+// Channel-capability snapshot for the OTHER consumers of capability state:
+// the before_prompt_build hook (fragments into the system prompt — evaluated
+// every prompt build, so a refresh reaches the very next turn without any
+// restart) and the gateway's getCapabilityKeys (hint routing). Updated by
+// applyChannelCapabilitySnapshot alongside every config apply, so the shim
+// materialization and the declaration can never diverge within a refresh.
+// Process-global BY THE SAME assumption as runtime.ts's agentIdentity:
+// hosted agents run one-agent-per-pod, so a single snapshot is correct. A
+// future multi-account host would need this keyed per account together with
+// that identity global — do not fix one without the other.
+let currentCapabilities: AgentCapability[] = [];
+
+export function getChannelCapabilityFragments(): string[] {
+  return currentCapabilities.map((c) => c.fragment);
+}
+
+export function getChannelCapabilityKeys(): string[] {
+  return currentCapabilities.map((c) => c.key);
+}
+
+function applyChannelCapabilitySnapshot(
+  stateDir: string,
+  config: Record<string, unknown>,
+  log?: { info: (msg: string) => void; warn: (msg: string) => void; error: (msg: string) => void },
+): void {
+  const caps = extractCapabilities(config);
+  materializeChannelCapabilities(stateDir, caps, log);
+  currentCapabilities = caps;
+}
+
 interface ConfigManagerOpts {
   client: ParallClient;
   stateDir: string;
@@ -204,6 +239,7 @@ export async function fetchAndApplyPlatformConfig(opts: ConfigManagerOpts): Prom
         `platform config fetch failed, using cached version ${cached.version}: ${String(err)}`,
       );
       applyToOpenClawConfig(configPath, cached.config, credentials);
+      applyChannelCapabilitySnapshot(stateDir, cached.config, log);
       return;
     }
     // No cache and fetch fails — degrade gracefully
@@ -216,6 +252,7 @@ export async function fetchAndApplyPlatformConfig(opts: ConfigManagerOpts): Prom
     log?.info('platform config unchanged (304)');
     if (cached) {
       applyToOpenClawConfig(configPath, cached.config, credentials);
+      applyChannelCapabilitySnapshot(stateDir, cached.config, log);
     }
     return;
   }
@@ -228,6 +265,7 @@ export async function fetchAndApplyPlatformConfig(opts: ConfigManagerOpts): Prom
     );
     if (cached) {
       applyToOpenClawConfig(configPath, cached.config, credentials);
+      applyChannelCapabilitySnapshot(stateDir, cached.config, log);
     }
     return;
   }
@@ -235,5 +273,6 @@ export async function fetchAndApplyPlatformConfig(opts: ConfigManagerOpts): Prom
   // 5. Newer config received — save cache and apply
   log?.info(`platform config updated to version ${fresh.version}`);
   saveCachedConfig(stateDir, fresh);
+  applyChannelCapabilitySnapshot(stateDir, fresh.config, log);
   applyToOpenClawConfig(configPath, fresh.config, credentials);
 }

package/src/gateway.ts

@@ -5,6 +5,8 @@ import type { ChannelPlugin } from 'openclaw/plugin-sdk/core';
 type ChannelGatewayAdapter<T = unknown> = NonNullable<ChannelPlugin<T>['gateway']>;
 import {
   ParallAgentGateway,
+  capabilityBinDir,
+  dispatchLaneContextDir,
   parseShutdownDeadlineMs,
   parseForkDeadlineMs,
   parseDispatchDeadlineMs,
@@ -35,7 +37,7 @@ import {
 } from './runtime.js';
 import { buildOrchestratorSessionKey } from './session.js';
 import type { ResolvedParallAccount } from './types.js';
-import { fetchAndApplyPlatformConfig } from './config-manager.js';
+import { fetchAndApplyPlatformConfig, getChannelCapabilityKeys } from './config-manager.js';
 import { startWikiHelper } from './wiki-helper.js';
 import { SessionManager } from './oc-session.js';
 import {
@@ -46,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(/\/$/, '');
@@ -406,6 +418,17 @@ export const parallGateway: ChannelGatewayAdapter<ResolvedParallAccount> = {
         process.env.OPENCLAW_STATE_DIR || path.join(process.env.HOME || '/data', '.openclaw');
       const openclawConfigPath = path.join(stateDir, 'openclaw.json');
 
+      // Channel-capability shims resolve ahead of any globally-installed CLI
+      // of the same name. The plugin runs INSIDE the openclaw process, whose
+      // env every exec-tool child inherits — one idempotent prepend here
+      // covers the agent's shell commands for the process lifetime (the
+      // DIRECTORY is constant; its content tracks capability grants).
+      const shimDir = capabilityBinDir(stateDir);
+      const currentPath = process.env.PATH ?? '';
+      if (!currentPath.split(path.delimiter).includes(shimDir)) {
+        process.env.PATH = currentPath ? `${shimDir}${path.delimiter}${currentPath}` : shimDir;
+      }
+
       const configManagerOpts = {
         client,
         stateDir,
@@ -470,7 +493,23 @@ 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.
+        getCapabilityKeys: getChannelCapabilityKeys,
         shutdownDeadlineMs: parseShutdownDeadlineMs(process.env.PRLL_SHUTDOWN_DEADLINE_MS),
         forkDeadlineMs: parseForkDeadlineMs(process.env.PRLL_FORK_DEADLINE_MS),
         dispatchDeadlineMs: parseDispatchDeadlineMs(process.env.PRLL_DISPATCH_DEADLINE_MS),
@@ -491,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

@@ -9,6 +9,7 @@ import {
   recordMessageSend,
   recordNoReply,
 } from '@parall/agent-core';
+import { getChannelCapabilityFragments } from './config-manager.js';
 import { extractAccountIdFromSessionKey } from './session.js';
 import {
   clearDispatchGroupKey,
@@ -127,12 +128,61 @@ export function registerParallHooks(api: OpenClawPluginApi) {
         PRLL_CHANNEL_CONTEXT,
         PRLL_BEHAVIOR,
         PRLL_REFERENCE_GUIDE,
+        // Channel-capability declarations (platform-config
+        // agents.capabilities[]). Evaluated on EVERY prompt build, so a
+        // capability grant/revocation reaches the next turn without any
+        // restart — the openclaw analogue of the CLI bridges' prompt-file
+        // rewrite + respawn.
+        ...getChannelCapabilityFragments(),
       ].join('\n\n'),
     };
   });
 
   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.
@@ -140,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)) {
@@ -221,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;
@@ -240,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;
 };