@parall/agent-core 1.42.1 → 1.44.0

package/src/gateway-base.ts

@@ -148,6 +148,14 @@ export type ParallGatewayOptions = {
    * this directory. Absent → legacy received/ack flow (openclaw / hermes).
    */
   dispatchContextDir?: string;
+  /**
+   * Live view of the agent's platform-granted capability keys (bridges wire
+   * PlatformConfigManager.capabilities().map(c => c.key)). Read at
+   * channel-event build time so the reply hint routes to the capability
+   * affordance (e.g. feishu-cli → lark-cli) — the single outbound path.
+   * Absent/empty → the hint states outbound is disabled.
+   */
+  getCapabilityKeys?: () => string[];
   onConfigUpdate?: (data: AgentConfigUpdateData) => Promise<void> | void;
   onSessionReady?: (state: {
     activeSessionId?: string;
@@ -293,6 +301,9 @@ export class ParallAgentGateway {
   // (stable mapping; avoids one connection fetch per inbound message).
   private readonly channelConnectionProviders = new Map<string, string>();
   private readonly dispatchedMessages = new Set<string>();
+  // Per-WorkItem failure backoff for typed dispatch consumption — see
+  // LaneFlowHost.typedRedriveBackoff in gateway-lane-flow.ts.
+  readonly typedRedriveBackoff = new Map<string, { failures: number; until: number }>();
   private readonly forkStates = new Map<string, ActiveForkState>();
   private readonly dispatchState: DispatchState = {
     mainDispatching: false,
@@ -448,8 +459,17 @@ export class ParallAgentGateway {
                 source_id: data.id,
               })
               .then(
-                () => undefined,
-                () => undefined,
+                () => true,
+                (err) => {
+                  // Same contract as ackDispatchEvent: a failed ack is a
+                  // failed consume (arms backoff) and must free the hot-path
+                  // dedupe so the re-drive isn't rejected by this pod forever.
+                  this.dispatchedTasks.delete(`${data.id}:${data.updated_at}`);
+                  this.opts.log?.warn(
+                    `dispatch ack failed for task ${data.id}, releasing for re-drive: ${String(err)}`,
+                  );
+                  return false;
+                },
               );
           },
         );
@@ -621,6 +641,45 @@ export class ParallAgentGateway {
     return true;
   }
 
+  /**
+   * Lane currently being dispatched per session — lets external activity
+   * signals renew exactly the caller's lane (renewing all lanes would keep
+   * an unrelated stalled fork's lane leased forever).
+   */
+  private sessionActiveLanes = new Map<string, string>();
+
+  noteSessionLane(sessionKey: string, laneKey: string | null): void {
+    if (laneKey == null) this.sessionActiveLanes.delete(sessionKey);
+    else this.sessionActiveLanes.set(sessionKey, laneKey);
+  }
+
+  /**
+   * External runtime-activity signal for adapters whose tool activity does
+   * not flow through the RuntimeEvent stream (openclaw hooks call this from
+   * the tool-call lifecycle): renews the session's OWN active ledger lane so
+   * a long tool call cannot outlive the lease and get dethroned mid-turn.
+   * No-op without an active ledger lane for the session.
+   */
+  touchRuntimeActivity(sessionKey: string): void {
+    if (this.ledgerDisabled) return;
+    const laneKey = this.sessionActiveLanes.get(sessionKey);
+    if (laneKey) this.laneLedger?.renewByKey(laneKey);
+  }
+
+  /** Sessions whose in-flight turn surfaced a runtime error event. */
+  private turnErrorSessions = new Set<string>();
+
+  /**
+   * Consume (read-and-clear) the error marker for sessionKey's last turn.
+   * Feeds complete's turn_outcome so an error turn's lane members are
+   * released for retry instead of no_action-swept (design §3). Consuming
+   * (rather than peeking) keeps one-shot fork session keys from accumulating
+   * in the set forever.
+   */
+  consumeTurnError(sessionKey: string): boolean {
+    return this.turnErrorSessions.delete(sessionKey);
+  }
+
   private async emitDispatchReceived(event: ParallEvent): Promise<void> {
     const sourceType = event.ackSourceType ?? (event.type === 'task' ? 'task_activity' : 'message');
     const sourceId = event.ackSourceId ?? event.messageId;
@@ -673,24 +732,27 @@ export class ParallAgentGateway {
     earlier: ParallEvent[];
     captureText?: string[];
     hasMoreLocal: () => boolean;
-  }): Promise<'dispatched' | 'foreign' | 'shutdown'> {
+  }): Promise<'dispatched' | 'foreign' | 'shutdown' | 'failed'> {
     return dispatchLaneGroup(this.laneFlowHost(), opts);
   }
 
   private consumeTypedDispatch(
     ref: { dispatchEventId?: string; sourceType?: string; sourceId?: string },
     run: (dispatchEventId?: string) => Promise<boolean>,
-    ack: (dispatchEventId?: string) => void | Promise<void>,
+    ack: (dispatchEventId?: string) => boolean | void | Promise<boolean | void>,
   ): Promise<void> {
     return consumeTypedDispatch(this.laneFlowHost(), ref, run, ack);
   }
 
   // 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.
-  private ackDispatchEvent(dispatchEventId: string, onFailure?: () => void): Promise<void> {
+  // received, so Complete releases and re-drives it safely. The boolean
+  // outcome feeds the typed-consume backoff — an ack that failed must count
+  // as a failed consume, or an ack outage would clear the backoff entry and
+  // let the release re-drive spin at wire speed.
+  private ackDispatchEvent(dispatchEventId: string, onFailure?: () => void): Promise<boolean> {
     return this.opts.client.ackDispatchByID(this.opts.config.org_id, dispatchEventId).then(
-      () => undefined,
+      () => true,
       (err) => {
         // Complete will return the still-received item to pending and publish
         // an immediate hint. Free its hot-path claim first, otherwise that
@@ -699,6 +761,7 @@ export class ParallAgentGateway {
         this.opts.log?.warn(
           `dispatch ack failed for ${dispatchEventId}, releasing for re-drive: ${String(err)}`,
         );
+        return false;
       },
     );
   }
@@ -1113,6 +1176,7 @@ export class ParallAgentGateway {
     }
 
     resetDispatchMetrics(sessionKey);
+    this.turnErrorSessions.delete(sessionKey);
     return runWithSessionKey(sessionKey, async () => {
       let dispatchSpan: ReturnType<typeof startDispatchSpan> = null;
 
@@ -1275,6 +1339,9 @@ export class ParallAgentGateway {
           ) {
             recordMessageSend(sessionKey, !runtimeEvent.error);
           }
+          if (runtimeEvent.type === 'error') {
+            this.turnErrorSessions.add(sessionKey);
+          }
           await this.createRuntimeStep(
             binding.agentSessionId,
             event,
@@ -1471,13 +1538,29 @@ export class ParallAgentGateway {
               body: buildForkScopePrefix(last) + buildEventBody(last),
               earlier,
               captureText: batchText,
-              hasMoreLocal: () => fork.queue.length > 0,
+              // Per-LANE residue check (parity with the main-buffer path):
+              // the fork queue can hold several lanes (channel + thread of
+              // the same chat). A whole-queue check would defer THIS lane's
+              // complete behind another lane's items and never revisit it —
+              // its members would sit received until lease expiry.
+              hasMoreLocal: () =>
+                fork.queue.some(
+                  (it) => this.dispatchGroupKey(it.event) === this.dispatchGroupKey(last),
+                ),
             });
             if (outcome === 'foreign') {
               // Another pod owns the lane — the events stay pending server-side.
               for (const item of items) item.resolve(false);
               break;
             }
+            if (outcome === 'failed') {
+              // Error turn: complete(error) already released the members for
+              // redelivery. Do NOT push them to processedEvents — the redrive
+              // must not arrive wearing an "already handled" prefix. Keep
+              // draining; the released work rejoins the next claim.
+              for (const item of items) item.resolve(false);
+              continue;
+            }
             dispatched = outcome === 'dispatched';
           } else {
             dispatched = await this.runDispatch(
@@ -1518,6 +1601,10 @@ export class ParallAgentGateway {
         remaining.resolve(false);
       }
     } finally {
+      // One-shot fork keys are never dispatched again — drop any error marker
+      // the legacy (non-ledger) path left unconsumed, or the set grows with
+      // every failed ephemeral fork.
+      this.turnErrorSessions.delete(fork.fork.sessionKey);
       if (fork.deadlineTimer) {
         clearTimeout(fork.deadlineTimer);
         fork.deadlineTimer = null;
@@ -1630,7 +1717,7 @@ export class ParallAgentGateway {
           this.opts.runtimeKey,
         );
         if (this.usesLaneLedger(event)) {
-          let outcome: 'dispatched' | 'foreign' | 'shutdown';
+          let outcome: 'dispatched' | 'foreign' | 'shutdown' | 'failed';
           try {
             outcome = await this.dispatchLaneGroup({
               events,
@@ -1657,6 +1744,13 @@ export class ParallAgentGateway {
             this.dispatchState.pendingForkResults.unshift(...pendingFork);
             continue;
           }
+          if (outcome === 'failed') {
+            // Error turn settled with complete(error) — members released for
+            // redelivery. The fork results were not consumed by the failed
+            // turn; keep them for the next real dispatch.
+            this.dispatchState.pendingForkResults.unshift(...pendingFork);
+            continue;
+          }
           // Dispatched — resolution happened server-side (reply cover or
           // no_action sweep); no legacy acks.
           continue;
@@ -1745,7 +1839,7 @@ export class ParallAgentGateway {
         if (this.usesLaneLedger(event)) {
           // Ledger flow: claim replaces mark-received; complete/reply replace
           // acks. A foreign incumbent leaves the event pending for re-drive.
-          let outcome: 'dispatched' | 'foreign' | 'shutdown' = 'shutdown';
+          let outcome: 'dispatched' | 'foreign' | 'shutdown' | 'failed' = 'shutdown';
           try {
             try {
               outcome = await this.dispatchLaneGroup({
@@ -1816,10 +1910,17 @@ export class ParallAgentGateway {
           // fold leaves the event buffered — the drain claims it as its own
           // turn. Injection requires an exact lane match (same chat AND same
           // thread) — a thread message never rides a channel turn.
+          // The adapter-capability check comes BEFORE the fold: on a
+          // buffer-only adapter (openclaw — no enqueueDuringDispatch) a
+          // folded-but-never-injected member would be broad-covered by the
+          // current turn's reply without the model ever seeing it. Leaving
+          // the event un-folded keeps it buffered; the drain claims it as
+          // its own turn and folds it there.
           if (
             this.mainCurrentGroupKey === this.dispatchGroupKey(event) &&
+            this.opts.dispatchAdapter.enqueueDuringDispatch != null &&
             (await this.laneLedger?.steerLive(event)) &&
-            (await this.opts.dispatchAdapter.enqueueDuringDispatch?.(
+            (await this.opts.dispatchAdapter.enqueueDuringDispatch(
               this.opts.runtimeKey,
               buildEventBody(event),
             ))
@@ -1868,14 +1969,21 @@ export class ParallAgentGateway {
           return false;
         }
 
-        try {
-          await this.emitDispatchReceived(event);
-        } catch (err) {
-          this.opts.log?.warn?.(
-            `mark-received failed for fork dispatch, leaving unacked for retry: ${String(err)}`,
-          );
-          this.dispatchState.mainBuffer.push(event);
-          return false;
+        // Ledger-managed events must never touch the legacy received surface
+        // — the fork's lane claim marks them received. A mark-received here
+        // outruns the claim, strands the row ownerless, and the chat goes
+        // silent (the 0713 black hole; dispatch-convergence-design.md §6).
+        // This was the only unguarded call site of the three.
+        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,
@@ -2471,6 +2579,19 @@ export class ParallAgentGateway {
       }
     }
 
+    // The reply hint routes on the live capability grant: `<provider>-cli`
+    // present → the vendor CLI is on PATH (broker shim) and is THE reply
+    // path; absent → outbound is disabled for this org (flag/connection off)
+    // and the hint must say so instead of pointing at a retired clip. The
+    // provider label lookup above is best-effort/cosmetic — when it fails,
+    // ANY granted `*-cli` capability keeps the hint on the CLI path: a
+    // transient metadata miss must not flip an actively granted agent's
+    // hint to "outbound disabled" and strand a valid external message.
+    const keys = this.opts.getCapabilityKeys?.() ?? [];
+    const cliCapable = provider
+      ? keys.includes(`${provider}-cli`)
+      : keys.some((k) => k.endsWith('-cli'));
+
     const event: ParallEvent = {
       type: 'channel_message',
       targetId: conv.id,
@@ -2485,6 +2606,7 @@ export class ParallAgentGateway {
       channelConversationType: conv.conversation_type || undefined,
       channelExternalConversationId: conv.external_conversation_id,
       channelExternalMessageId: msg.external_message_id,
+      channelCliCapable: cliCapable,
       ackSourceType: 'channel_message',
       ackSourceId: msg.id,
     };

package/src/gateway-lane-flow.ts

@@ -18,6 +18,15 @@ export interface LaneFlowHost {
   ledgerDisabled: boolean;
   shuttingDown: boolean;
   dispatchedMessages: Set<string>;
+  /**
+   * Per-WorkItem failure backoff for typed dispatch consumption. A consume
+   * that ends without an ack re-arms the entry; the next attempt for the
+   * same WorkItem is delayed (not skipped — a skipped attempt would strand
+   * the pending row until reconnect catch-up) so a claim→fail→complete
+   * tight loop is throttled to exponential intervals instead of spinning at
+   * wire speed against the server's immediate re-drive (2026-07-11 OOM).
+   */
+  typedRedriveBackoff: Map<string, { failures: number; until: number }>;
   opts: {
     client: ParallClient;
     log?: GatewayLogger;
@@ -28,6 +37,8 @@ export interface LaneFlowHost {
   disableLedger(reason: string): void;
   usesLaneLedger(event: ParallEvent): boolean;
   emitDispatchReceived(event: ParallEvent): Promise<void>;
+  consumeTurnError(sessionKey: string): boolean;
+  noteSessionLane(sessionKey: string, laneKey: string | null): void;
   runDispatch(
     event: ParallEvent,
     sessionKey: string,
@@ -59,7 +70,7 @@ export async function dispatchLaneGroup(
     captureText?: string[];
     hasMoreLocal: () => boolean;
   },
-): Promise<'dispatched' | 'foreign' | 'shutdown'> {
+): Promise<'dispatched' | 'foreign' | 'shutdown' | 'failed'> {
   const ledger = host.laneLedger!;
   const event = opts.events[opts.events.length - 1];
   let lane: Awaited<ReturnType<LaneLedger['ensureLane']>>;
@@ -97,6 +108,9 @@ export async function dispatchLaneGroup(
     }
     return 'foreign';
   }
+  // Register the session's active lane so external activity signals
+  // (touchRuntimeActivity from adapter hooks) renew exactly this lane.
+  host.noteSessionLane(opts.sessionKey, lane.laneKey);
   let dispatched = false;
   try {
     dispatched = await host.runDispatch(
@@ -109,34 +123,141 @@ export async function dispatchLaneGroup(
   } catch (err) {
     // Failed turn: hand the members back so the retry (this pod or the
     // next) re-claims immediately instead of waiting out the lease.
+    host.noteSessionLane(opts.sessionKey, null);
     await ledger.release(lane.laneKey).catch(() => {});
     throw err;
+  } finally {
+    if (dispatched) host.noteSessionLane(opts.sessionKey, null);
   }
   if (!dispatched) {
     // Shutdown short-circuit — shutdown() releases all active lanes.
     return 'shutdown';
   }
+  if (host.consumeTurnError(opts.sessionKey)) {
+    // An error turn must not no_action-sweep its members — settle the lane
+    // NOW with an error complete so they release for retry on the redrive
+    // budget (dispatch-convergence-design.md §3). Settling immediately (even
+    // with same-lane work still buffered) is deliberate: carrying the error
+    // across buffered turns would let a later reply broad-cover the failed
+    // member, or requeue the later turn's successful work. Released members
+    // rejoin the next claim, merged with whatever was buffered. Dropping the
+    // local dedupe claims lets the server's re-drive hint retrigger the
+    // messages immediately instead of waiting out the renotify pacing.
+    ledger.markTurnError(lane.laneKey);
+    // Clear dedupe for EVERY lane member, not just this batch: an earlier
+    // successful batch may have deferred its complete via hasMoreLocal, so
+    // the error complete below releases those members too — their redrive
+    // would be permanently blocked by a stale local claim.
+    for (const msgId of lane.folded.keys()) {
+      host.dispatchedMessages.delete(msgId);
+    }
+    // Invalidate any armed steer state before settling: a pending injection
+    // left over from the failed turn would make the retry claim enter the
+    // "already injected" path, produce an empty turn, and no_action-sweep the
+    // released members without ever retrying them. abortDispatch is the
+    // adapter contract's idempotent "clear pending steer state" hook.
+    try {
+      host.opts.dispatchAdapter.abortDispatch?.(opts.sessionKey);
+    } catch {
+      // best-effort — a throwing abort must not block the error settlement
+    }
+    await ledger.completeIfIdle(lane.laneKey, false);
+    // 'failed' — callers must NOT record these events as handled: the server
+    // just released them for redelivery, and an "already handled" fork prefix
+    // (or a consumed fork summary) on the redrive would be a lie.
+    return 'failed';
+  }
   const pendingInjections =
     host.opts.dispatchAdapter.hasPendingInjections?.(opts.sessionKey) ?? false;
   await ledger.completeIfIdle(lane.laneKey, pendingInjections || opts.hasMoreLocal());
   return 'dispatched';
 }
 
+/** Failure backoff pacing for typed dispatch retries (base 2s, cap 5min). */
+const TYPED_BACKOFF_BASE_MS = 2_000;
+const TYPED_BACKOFF_CAP_MS = 5 * 60_000;
+const TYPED_BACKOFF_MAP_CAP = 512;
+
 /**
  * Consume one typed dispatch (task/comment/schedule/trigger/approval) under
  * its typed-lane occupancy guard: claim the dsp:<id> lane (skip when another
  * pod holds it or the WorkItem is already resolved), run the handler, ack on
  * success (the doc's option (b): notification delivered, tracked elsewhere),
  * then release the lane. Legacy run+ack flow when the ledger is unavailable.
+ *
+ * Repeated failures back off: a consume that ends un-acked re-arms the
+ * WorkItem's backoff entry, and the next attempt sleeps out the remaining
+ * window before claiming. Without this, complete's release re-drives the
+ * item instantly and a persistently-failing consume (e.g. buffered behind a
+ * saturated fork pool) spins at wire speed — the client half of the
+ * 2026-07-11 poison loop (the server half is the redrive budget).
  */
 export async function consumeTypedDispatch(
   host: LaneFlowHost,
   ref: { dispatchEventId?: string; sourceType?: string; sourceId?: string },
   run: (dispatchEventId?: string) => Promise<boolean>,
-  ack: (dispatchEventId?: string) => void | Promise<void>,
+  ack: (dispatchEventId?: string) => boolean | void | Promise<boolean | void>,
 ): Promise<void> {
+  const backoffKey = ref.dispatchEventId ?? `${ref.sourceType}:${ref.sourceId}`;
+  const armed = host.typedRedriveBackoff.get(backoffKey);
+  if (armed) {
+    const waitMs = armed.until - Date.now();
+    if (waitMs > 0) {
+      host.opts.log?.info(
+        `typed dispatch ${backoffKey} backing off ${Math.ceil(waitMs / 1000)}s after ${armed.failures} failed consume(s)`,
+      );
+      // unref: the wait must never be what keeps the process alive — on
+      // SIGTERM the gateway drains and exits while this timer is pending
+      // (the re-drive/renotify path re-delivers on the next pod).
+      await new Promise<void>((resolve) => {
+        const timer = setTimeout(resolve, waitMs);
+        timer.unref?.();
+      });
+    }
+    if (host.shuttingDown) return;
+  }
+  // An ack callback that returns void (legacy custom acks) counts as success;
+  // an explicit false (ackDispatchEvent's failed HTTP ack) is a failed
+  // consume — clearing backoff there would let an ack outage re-create the
+  // wire-speed release/re-drive loop against a pre-budget server.
+  const settleAck = (ackResult: boolean | void) => ackResult !== false;
+  const settle = (acked: boolean) => {
+    if (acked) {
+      host.typedRedriveBackoff.delete(backoffKey);
+      return;
+    }
+    const failures = (host.typedRedriveBackoff.get(backoffKey)?.failures ?? 0) + 1;
+    const backoffMs = Math.min(TYPED_BACKOFF_CAP_MS, TYPED_BACKOFF_BASE_MS * 2 ** (failures - 1));
+    // True LRU: delete-then-set moves an updated key to the tail of the
+    // Map's insertion order, so capacity eviction always removes the
+    // least-recently-FAILING key — an actively-failing old key must not be
+    // evicted ahead of a quieter newer one. Evict only when inserting a new
+    // key at capacity (an in-place update never shrinks the map).
+    if (
+      host.typedRedriveBackoff.delete(backoffKey) === false &&
+      host.typedRedriveBackoff.size >= TYPED_BACKOFF_MAP_CAP
+    ) {
+      const oldest = host.typedRedriveBackoff.keys().next().value;
+      if (oldest !== undefined) host.typedRedriveBackoff.delete(oldest);
+    }
+    host.typedRedriveBackoff.set(backoffKey, { failures, until: Date.now() + backoffMs });
+  };
+
+  // Legacy run+ack (no ledger): same settle-in-finally contract as the lane
+  // path — a thrown run/ack must arm backoff, not skip it.
+  const runLegacy = async () => {
+    let acked = false;
+    try {
+      if (await run(ref.dispatchEventId)) {
+        acked = settleAck(await ack(ref.dispatchEventId));
+      }
+    } finally {
+      settle(acked);
+    }
+  };
+
   if (!host.laneLedger || host.ledgerDisabled) {
-    if (await run(ref.dispatchEventId)) await ack(ref.dispatchEventId);
+    await runLegacy();
     return;
   }
   let lane: Awaited<ReturnType<LaneLedger['claimTyped']>>;
@@ -145,23 +266,29 @@ export async function consumeTypedDispatch(
   } catch (err) {
     if (err instanceof LedgerUnsupportedError) {
       host.disableLedger('claim endpoint missing');
-      if (await run(ref.dispatchEventId)) await ack(ref.dispatchEventId);
+      await runLegacy();
       return;
     }
     throw err;
   }
   if (!lane) {
+    // Held elsewhere or already resolved — not a local failure; leave the
+    // backoff state as-is (a stale entry is cleared by the next local ack).
     host.opts.log?.info(
       `typed dispatch ${ref.dispatchEventId ?? `${ref.sourceType}:${ref.sourceId}`} not claimable (held elsewhere or already resolved) — skipping`,
     );
     return;
   }
+  let acked = false;
   try {
     // Ack must settle before Complete. A fire-and-forget ack races the lane
     // release: Complete can return the still-received typed item to pending
     // and publish a re-drive while its successful ack is still in flight.
-    if (await run(lane.typedDispatchEventId)) await ack(lane.typedDispatchEventId);
+    if (await run(lane.typedDispatchEventId)) {
+      acked = settleAck(await ack(lane.typedDispatchEventId));
+    }
   } finally {
+    settle(acked);
     // Release the occupancy row. A buffered dispatch may outlive this guard
     // (lane TTL) — acceptable at-least-once; the ledger's resolution paths
     // still dedupe the persistent side effects.

package/src/index.ts

@@ -2,6 +2,7 @@ export * from './provider-config.js';
 export * from './types.js';
 export * from './lane-key.js';
 export type { LaneFlowHost } from './gateway-lane-flow.js';
+export { consumeTypedDispatch } from './gateway-lane-flow.js';
 export * from './session-state.js';
 export * from './routing.js';
 export * from './event-format.js';
@@ -11,6 +12,8 @@ export * from './dispatch-adapter.js';
 export { createLogger, childLogger } from './logger.js';
 export * from './gateway-base.js';
 export * from './platform-config.js';
+export * from './channel-capability.js';
+export * from './channel-token.js';
 export { writeSkillFiles, buildSkillReferences, SKILLS } from './skills/index.js';
 export type { SkillMeta } from './skills/index.js';
 export {

package/src/lane-ledger.ts

@@ -19,6 +19,13 @@ export type ActiveLane = {
   /** Lease expiry (ms epoch) and TTL from the claim — renewal pacing state. */
   leaseUntilMs?: number;
   leaseTtlMs?: number;
+  /**
+   * Sticky error bit: some turn on this lane surfaced a runtime error. Read
+   * (and only cleared) by the lane's final complete, so an error outcome
+   * survives buffered same-lane turns in between — a later successful turn
+   * must not no_action-sweep the failed turn's members.
+   */
+  turnError?: boolean;
 };
 
 /**
@@ -122,9 +129,19 @@ export class LaneLedger {
         throw err;
       }
       if (!res.claimed || !res.lane) {
-        this.opts.log?.info(
-          `lane for ${targetUri} held by a healthy incumbent — leaving events pending for re-drive`,
-        );
+        if (res.reason === 'empty') {
+          // Nothing foldable: resolved elsewhere, or stranded outside the
+          // ledger (the reconciler reclaims strays past the received TTL).
+          // Post-convergence this should not happen on a message lane — warn
+          // so a regression surfaces (design §3).
+          this.opts.log?.warn(
+            `claim for ${targetUri} came back empty — nothing foldable; leaving to the reconciler`,
+          );
+        } else {
+          this.opts.log?.info(
+            `lane for ${targetUri} held by a healthy incumbent — leaving events pending for re-drive`,
+          );
+        }
         return null;
       }
       const leaseUntilMs = Date.parse(res.lease_until ?? '');
@@ -218,6 +235,18 @@ export class LaneLedger {
    * 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: string): void {
+    const lane = this.lanes.get(laneKey);
+    if (lane) lane.turnError = true;
+  }
+
   async completeIfIdle(laneKey: string, hasMoreLocal: boolean): Promise<void> {
     const lane = this.lanes.get(laneKey);
     if (!lane || hasMoreLocal) return;
@@ -228,6 +257,9 @@ export class LaneLedger {
         lane: lane.lane,
         target_uri: lane.targetUri,
         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(
@@ -244,6 +276,17 @@ export class LaneLedger {
     }
   }
 
+  /**
+   * 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: string): void {
+    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

package/src/platform-config.ts

@@ -17,6 +17,46 @@ export interface PlatformConfigManager {
   fetch(): Promise<PlatformDefaults>;
   current(): PlatformDefaults;
   rawConfig(): Record<string, unknown> | null;
+  /**
+   * Channel capabilities delivered in `agents.capabilities[]` — the
+   * declaration plane of the channel-capability broker. Reads the current
+   * (possibly LKG-cached) config with NO freshness gate: the credential is
+   * pull-at-use (the mint endpoint re-evaluates the grant on every call), so
+   * a stale declaration fail-closes there with a self-explanatory 403 — like
+   * a stale model, it is suboptimal, never dangerous.
+   */
+  capabilities(): AgentCapability[];
+}
+
+// One platform-granted capability (agents.capabilities[] in platform-config).
+// `fragment` is the complete system-prompt declaration text; the server is
+// the SSOT for channel knowledge, runtimes just splice it in.
+export interface AgentCapability {
+  key: string;
+  source: string;
+  fragment: string;
+}
+
+// Defensive extraction: entries missing a non-empty string key/fragment are
+// skipped so a malformed or future-shaped payload can never inject a blank
+// declaration into a system prompt.
+export function extractCapabilities(config: Record<string, unknown>): AgentCapability[] {
+  const agents = (config.agents ?? {}) as Record<string, unknown>;
+  const raw = agents.capabilities;
+  if (!Array.isArray(raw)) return [];
+  const out: AgentCapability[] = [];
+  for (const entry of raw) {
+    if (typeof entry !== 'object' || entry === null) continue;
+    const e = entry as Record<string, unknown>;
+    if (typeof e.key !== 'string' || !e.key) continue;
+    if (typeof e.fragment !== 'string' || !e.fragment) continue;
+    out.push({
+      key: e.key,
+      source: typeof e.source === 'string' ? e.source : '',
+      fragment: e.fragment,
+    });
+  }
+  return out;
 }
 
 export interface PlatformManagementProfile {
@@ -276,5 +316,9 @@ export function createPlatformConfigManager(opts: {
     rawConfig(): Record<string, unknown> | null {
       return currentRawConfig;
     },
+
+    capabilities(): AgentCapability[] {
+      return currentRawConfig ? extractCapabilities(currentRawConfig) : [];
+    },
   };
 }