@parall/agent-core 1.42.0 → 1.43.0

package/src/channel-capability.ts

@@ -0,0 +1,187 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import type { GatewayLogger } from './dispatch-adapter.js';
+import type { AgentCapability } from './platform-config.js';
+
+// Runtime-side materializer for channel capabilities — a pure PLACEMENT
+// layer. The server declares WHAT the agent has (agents.capabilities[]);
+// the credential logic lives in this package's channel-exec entry
+// (bin/channel-exec.ts, reusing channel-token.ts); this module only drops
+// constant POINTER shims onto the capability PATH so the vendor command name
+// (e.g. `lark-cli`, which the official skills invoke directly) routes into
+// that entry. Pointers reference channel-exec by IN-PACKAGE ABSOLUTE PATH —
+// no PATH lookup, no dependence on agent-writable install state; the engine
+// ships atomically with the bridge.
+//
+// Revocation keeps the pointer in place (nothing to remove): the pointer's
+// content is independent of grant state, and revocation semantics are
+// enforced by the platform mint endpoint (403 with an agent-readable
+// message). Deleting would let PATH fall through to a directly-installed
+// real CLI past the mint gate — the failure mode the old deny-stub existed
+// to prevent; a constant pointer prevents it structurally.
+// Design: docs/engineering-design/agent-capability-fragments-design.md §5.1.
+
+export const CAPABILITY_FEISHU_CLI = 'feishu-cli';
+
+// Marker embedded in every generated pointer. channel-exec skips any PATH
+// candidate whose head carries it, so a pointer (or a stray copy of one) can
+// never be mistaken for the real vendor binary — self-recursion is
+// structurally impossible even if the skip-dir hint is wrong.
+export const CHANNEL_POINTER_MAGIC = 'parall channel capability pointer';
+
+// SSOT for the shim directory: bridges prepend this to the child PATH once,
+// unconditionally — the directory is constant, its content tracks grants, so
+// a grant reaches even long-lived subprocesses (the shell re-resolves PATH
+// per command) without any respawn.
+export function capabilityBinDir(stateDir: string): string {
+  return path.join(stateDir, 'bin');
+}
+
+// Absolute path of the channel-exec entry, resolved across BOTH distribution
+// layouts — mirroring the daemon's resolveBbBrowserDaemonPath:
+//   - npm / hosted image: agent-core's dist tree exists on disk →
+//     ./bin/channel-exec.js sits under this module's dir.
+//   - standalone bundle (@parall/daemon / CDN self-update / desktop): esbuild
+//     flattens this module INTO bundle/parall-claude-agent.js, so ./bin/…
+//     doesn't exist; the bundle ships parall-channel-exec.js as a sibling flat
+//     artifact (scripts/bundle-daemon.mjs), resolved next to this file.
+// Prefer the sibling (bundle) and fall through to the in-package path (dev /
+// npm), like the bb-browser resolver — the two candidates are mutually
+// exclusive so order only affects which stat wins in the impossible case that
+// both exist.
+export function channelExecEntryPath(): string {
+  const selfDir = path.dirname(fileURLToPath(import.meta.url));
+  const sibling = path.join(selfDir, 'parall-channel-exec.js');
+  if (fs.existsSync(sibling)) return sibling;
+  return fileURLToPath(new URL('./bin/channel-exec.js', import.meta.url));
+}
+
+/**
+ * Idempotently reconcile local capability pointers with the delivered
+ * capability list. Call at boot (after the first config fetch) and on every
+ * config refresh. Never throws — a pointer write failure must not take down
+ * a config refresh (the capability simply stays unusable until the next pass).
+ */
+export function materializeChannelCapabilities(
+  stateDir: string,
+  capabilities: AgentCapability[],
+  log?: GatewayLogger,
+): void {
+  try {
+    reconcileFeishuCli(stateDir, capabilities, log);
+  } catch (err) {
+    log?.warn(`channel capability materialization failed: ${String(err)}`);
+  }
+}
+
+function reconcileFeishuCli(
+  stateDir: string,
+  capabilities: AgentCapability[],
+  log?: GatewayLogger,
+): void {
+  const binDir = capabilityBinDir(stateDir);
+  const posixPath = path.join(binDir, 'lark-cli');
+  const granted = capabilities.some((c) => c.key === CAPABILITY_FEISHU_CLI);
+  const hadPointer = fs.existsSync(posixPath);
+
+  // Write/refresh pointers when GRANTED, or when a pointer already exists (a
+  // previously-granted, now-revoked agent). The refresh-on-revoke case is
+  // load-bearing for bundle self-update: the pointer embeds channel-exec's
+  // ABSOLUTE path, which resolves through the daemon's `current` symlink into
+  // a versioned dir; after an upgrade prunes the old version, a stale retained
+  // pointer would fail MODULE_NOT_FOUND instead of reaching the mint 403.
+  // Re-rendering every pass keeps the pointer aimed at the LIVE channel-exec,
+  // so a revoked agent still gets the self-explanatory 403. A NEVER-granted
+  // agent (no pointer) is left untouched — the operator's own lark-cli install
+  // stays clean.
+  if (!granted && !hadPointer) return;
+
+  fs.mkdirSync(binDir, { recursive: true });
+  const entry = channelExecEntryPath();
+  // The node binary is referenced by ABSOLUTE path (process.execPath), not the
+  // bare name `node`: packaged installs (desktop / daemon bundle) embed the
+  // runtime as `parall-node` with no plain `node` on PATH, so a bare `node`
+  // would die before channel-exec ever runs and break bundle parity at the
+  // last hop. process.execPath is the very node currently running the bridge —
+  // the parall-node in a bundle, the system node under npm.
+  const nodeExec = process.execPath;
+  writePointerIfChanged(posixPath, renderPosixPointer(nodeExec, entry, binDir, 'feishu'), log);
+  // Windows companion: cmd/PowerShell resolve executables via PATHEXT and
+  // ignore extensionless shebang files. (The agent's own Bash tool on Windows
+  // is git-bash, which uses the sh pointer above — the .cmd is the cmd/
+  // PowerShell fallback; its %* follows standard batch semantics, same as any
+  // npm-installed .cmd bin.)
+  writePointerIfChanged(
+    path.join(binDir, 'lark-cli.cmd'),
+    renderCmdPointer(nodeExec, entry, binDir, 'feishu'),
+    log,
+  );
+}
+
+function writePointerIfChanged(filePath: string, content: string, log?: GatewayLogger): void {
+  let existing: string | null = null;
+  try {
+    existing = fs.readFileSync(filePath, 'utf8');
+  } catch {
+    existing = null;
+  }
+  if (existing !== content) {
+    fs.writeFileSync(filePath, content, { mode: 0o755 });
+    log?.info(`channel capability: pointer materialized (${path.basename(filePath)})`);
+  }
+  // Mode is enforced even when content is unchanged (a prior partial write
+  // or umask drift must not leave the pointer non-executable).
+  fs.chmodSync(filePath, 0o755);
+}
+
+// Pointer content is versioned HERE (never delivered by the server — config
+// carries declarations, not code). It embeds the entry's AND the bin dir's
+// absolute paths at write time — no $(dirname)/external commands (a minimal
+// PATH must not break the pointer), and the skip hint cannot drift. A
+// package upgrade that moves paths changes the rendered content, and the
+// boot-time materialize pass rewrites it (self-healing).
+// The target binary is NOT passed on the command line — channel-exec derives
+// it from the channel (feishu → lark-cli), so a caller cannot redirect the
+// minted token to a different program. binDir is still passed as the skip hint.
+export function renderPosixPointer(
+  nodeExecPath: string,
+  entryJsPath: string,
+  binDir: string,
+  channel: string,
+): string {
+  return [
+    '#!/bin/sh',
+    `# Generated by @parall/agent-core — ${CHANNEL_POINTER_MAGIC} (do not edit).`,
+    '# Credential + exec logic lives in the agent-core package; revocation is',
+    '# enforced by the platform mint endpoint, so this pointer stays constant.',
+    // Strip Node preload-hijack vars BEFORE launching node: NODE_OPTIONS
+    // (e.g. --require=/evil.js) and NODE_PATH would execute caller-supplied code
+    // at interpreter startup — BEFORE channel-exec's own env scrub, i.e. before
+    // the mint. The pointer is a platform-authored trust-boundary artifact whose
+    // whole job is a CONTROLLED launch of the broker (absolute node, magic
+    // guard, skip-dir); this closes the same env-hijack class for node startup
+    // that the absolute node path closes for PATH, keeping the launch deterministic.
+    'unset NODE_OPTIONS NODE_PATH',
+    // "$@" preserves argv exactly (this is the agent's main path via git-bash).
+    `exec "${nodeExecPath}" "${entryJsPath}" --channel ${channel} --skip-dir "${binDir}" -- "$@"`,
+    '',
+  ].join('\n');
+}
+
+export function renderCmdPointer(
+  nodeExecPath: string,
+  entryJsPath: string,
+  binDir: string,
+  channel: string,
+): string {
+  return [
+    '@echo off',
+    `rem Generated by @parall/agent-core - ${CHANNEL_POINTER_MAGIC} (do not edit).`,
+    // Clear Node preload-hijack vars before launching node (see the sh pointer).
+    'set "NODE_OPTIONS="',
+    'set "NODE_PATH="',
+    `"${nodeExecPath}" "${entryJsPath}" --channel ${channel} --skip-dir "${binDir}" -- %*`,
+    '',
+  ].join('\r\n');
+}

package/src/channel-token.ts

@@ -0,0 +1,92 @@
+// Channel-capability credential client — the ONE place that talks to the
+// platform mint endpoint. Consumed today by the short-lived exec form
+// (bin/channel-exec.ts); the future resident forms (proxy / mcp, hosted by
+// the bridge process) reuse this module so swimlane routing, error
+// presentation, and any future retry/telemetry policy stay single-sourced.
+// Design: docs/engineering-design/agent-capability-fragments-design.md §5.
+
+export interface MintedChannelToken {
+  channel_type: string;
+  token_type: string;
+  app_id: string;
+  brand: string;
+  token: string;
+  expires_at: string;
+}
+
+// Thrown for every mint failure; `message` is written for the AGENT to read
+// (and relay to the user when the platform says the capability is revoked).
+export class ChannelTokenError extends Error {}
+
+const MINT_TIMEOUT_MS = 10_000;
+
+/**
+ * Exchange the agent's channel grant for a short-lived provider token.
+ * Deliberately NO local caching at any layer here: the parall round trip is
+ * tens of ms (the expensive vendor exchange is absorbed by the server-side
+ * Redis cache), and every call re-passing the server gate is what makes
+ * revocation and re-credentialing bite on the very next invocation.
+ */
+export async function mintChannelToken(
+  channelType: string,
+  env: NodeJS.ProcessEnv,
+): Promise<MintedChannelToken> {
+  const apiUrl = (env.PRLL_API_URL || '').replace(/\/+$/, '');
+  const apiKey = env.PRLL_API_KEY || '';
+  const orgId = env.PRLL_ORG_ID || '';
+  if (!apiUrl || !apiKey || !orgId) {
+    throw new ChannelTokenError(
+      'PRLL_API_URL/PRLL_API_KEY/PRLL_ORG_ID missing from the environment',
+    );
+  }
+  const headers: Record<string, string> = {
+    'Content-Type': 'application/json',
+    Authorization: `Bearer ${apiKey}`,
+  };
+  // Swimlane routing must ride the mint request exactly like every SDK call —
+  // a bridge deployed in a PR swimlane mints against its own API/DB.
+  const swimlane = (env.PRLL_SWIMLANE_NAME || '').trim();
+  if (swimlane) headers['X-Prll-Swimlane'] = swimlane;
+
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), MINT_TIMEOUT_MS);
+  let resp: Response;
+  try {
+    resp = await fetch(
+      `${apiUrl}/api/v1/orgs/${encodeURIComponent(orgId)}/agents/me/channel-token`,
+      {
+        method: 'POST',
+        headers,
+        body: JSON.stringify({ channel_type: channelType }),
+        signal: controller.signal,
+      },
+    );
+  } catch (err) {
+    throw new ChannelTokenError(
+      `could not reach the Parall platform to authenticate (${String(err)}); channel actions are unavailable right now`,
+    );
+  } finally {
+    clearTimeout(timer);
+  }
+
+  if (!resp.ok) {
+    let msg = `platform returned HTTP ${resp.status}`;
+    try {
+      const body = (await resp.json()) as { error?: { message?: string } };
+      if (body?.error?.message) msg = body.error.message;
+    } catch {
+      // non-JSON error body: keep the status-line message
+    }
+    throw new ChannelTokenError(msg);
+  }
+
+  // Validate every field the caller actually injects into the vendor CLI, not
+  // just `token`: a 2xx missing app_id/brand would otherwise launch the real
+  // CLI with an incomplete credential env and fail opaquely downstream.
+  const minted = (await resp.json()) as Partial<MintedChannelToken>;
+  const nonEmpty = (v: unknown): v is string => typeof v === 'string' && v.length > 0;
+  if (!minted || !nonEmpty(minted.token) || !nonEmpty(minted.app_id) || !nonEmpty(minted.brand)) {
+    throw new ChannelTokenError('platform returned an unusable token payload');
+  }
+  return minted as MintedChannelToken;
+}

package/src/event-format.ts

@@ -175,22 +175,27 @@ function buildSendMessageHint(event: ParallEvent): string {
   }
 
   if (event.type === 'channel_message') {
-    // Provider metadata is best-effort (the gateway's connection lookup can
-    // fail) — never instruct the agent to invoke a made-up clip alias.
-    const clipLabel = event.channelProvider
-      ? `the \`${event.channelProvider}\` clip's`
-      : "your channel provider clip's";
-    const apiLabel = event.channelProvider ?? 'external platform';
-    const target = event.channelExternalConversationId
-      ? `{"chat_id": "${event.channelExternalConversationId}", "text": "..."}`
-      : `{"chat_id": "<conversation id>", "text": "..."}`;
-    // Offer the in-thread alternative whenever the inbound message id is
-    // known — otherwise the hint nudges every threaded conversation toward a
-    // new top-level message.
-    const threadAlt = event.channelExternalMessageId
-      ? ` To reply in-thread to this specific message, use {"message_id": "${event.channelExternalMessageId}", "text": "..."} instead.`
-      : '';
-    return `\n<system-reminder>To reply, invoke ${clipLabel} \`send_message\` command with ${target} — your plain text output is NOT delivered to the external conversation.${threadAlt} The same clip's \`call\` command reaches the wider ${apiLabel} API when needed.</system-reminder>`;
+    // Single-path routing (multi-channel-architecture-design §6): with the
+    // `<provider>-cli` capability granted, the vendor CLI on PATH is THE
+    // reply path; without it there is no outbound path at all — say so
+    // instead of pointing at the retired provider clip.
+    // channelCliCapable alone decides: only feishu mints exist today, so a
+    // live grant implies Feishu even when the cosmetic provider-label lookup
+    // failed (event.channelProvider undefined).
+    if (event.channelCliCapable) {
+      const convRef = event.channelExternalConversationId
+        ? `chat_id "${event.channelExternalConversationId}"`
+        : 'the conversation id named in this event';
+      // Offer the in-thread alternative whenever the inbound message id is
+      // known — otherwise the hint nudges every threaded conversation toward
+      // a new top-level message.
+      const threadAlt = event.channelExternalMessageId
+        ? ` To reply threaded to this specific message, reference message_id "${event.channelExternalMessageId}".`
+        : '';
+      return `\n<system-reminder>To reply, use the official Feishu CLI on your PATH: send a message to ${convRef} with \`lark-cli im\` (see \`lark-cli im --help\` for send syntax; auth is provisioned automatically).${threadAlt} lark-cli is the ONLY outbound path — your plain text output is NOT delivered to the external conversation.</system-reminder>`;
+    }
+    const platform = event.channelProvider ?? 'the external platform';
+    return `\n<system-reminder>This message arrived from ${platform}, but outbound replies are currently disabled for this org (no channel capability granted). Do NOT attempt to reply on the external platform. If action is needed, surface it inside Parall (\`parall messages send\` / \`parall dm\`). Your plain text output is not delivered anywhere.</system-reminder>`;
   }
 
   if (event.type === 'external_trigger' || event.targetId.startsWith('xtr_')) {

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,
@@ -438,17 +449,28 @@ export class ParallAgentGateway {
           (dispatchEventId) => this.handleTaskAssignment(data, data.id, dispatchEventId),
           (dispatchEventId) => {
             if (dispatchEventId) {
-              this.opts.client
-                .ackDispatchByID(this.opts.config.org_id, dispatchEventId)
-                .catch(() => {});
-              return;
+              return this.ackDispatchEvent(dispatchEventId, () => {
+                this.dispatchedTasks.delete(`${data.id}:${data.updated_at}`);
+              });
             }
-            this.opts.client
+            return this.opts.client
               .ackDispatch(this.opts.config.org_id, {
                 source_type: 'task_activity',
                 source_id: data.id,
               })
-              .catch(() => {});
+              .then(
+                () => 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;
+                },
+              );
           },
         );
       } catch (err) {
@@ -457,7 +479,16 @@ export class ParallAgentGateway {
     });
 
     ws.on('dispatch.new', async (data: DispatchNewData) => {
-      if (data.event_type === 'task_comment') {
+      if (data.event_type === 'task_assign') {
+        if (!data.task_id) return;
+        try {
+          await this.handleTaskAssignmentRedrive(data);
+        } catch (err) {
+          this.opts.log?.error(
+            `task assignment re-drive failed for ${data.task_id}: ${String(err)}`,
+          );
+        }
+      } else if (data.event_type === 'task_comment') {
         if (!data.source_id || !data.task_id) return;
         try {
           await this.consumeTypedDispatch(
@@ -469,9 +500,7 @@ export class ParallAgentGateway {
                 data.actor_id,
                 data.delivery_reason,
               ),
-            () => {
-              this.opts.client.ackDispatchByID(this.opts.config.org_id, data.id).catch(() => {});
-            },
+            () => this.ackDispatchEvent(data.id, () => this.clearTypedDispatchDedupe(data)),
           );
         } catch (err) {
           this.opts.log?.error(
@@ -484,9 +513,7 @@ export class ParallAgentGateway {
           await this.consumeTypedDispatch(
             { dispatchEventId: data.id },
             () => this.handleWikiComment(data.source_id, data.actor_id, data.delivery_reason),
-            () => {
-              this.opts.client.ackDispatchByID(this.opts.config.org_id, data.id).catch(() => {});
-            },
+            () => this.ackDispatchEvent(data.id, () => this.clearTypedDispatchDedupe(data)),
           );
         } catch (err) {
           this.opts.log?.error(
@@ -503,9 +530,7 @@ export class ParallAgentGateway {
                 allowCreator: true,
                 dispatchEventId,
               }),
-            () => {
-              this.opts.client.ackDispatchByID(this.opts.config.org_id, data.id).catch(() => {});
-            },
+            () => this.ackDispatchEvent(data.id, () => this.clearTypedDispatchDedupe(data)),
           );
         } catch (err) {
           this.opts.log?.error(`task update dispatch failed for ${data.task_id}: ${String(err)}`);
@@ -516,9 +541,7 @@ export class ParallAgentGateway {
           await this.consumeTypedDispatch(
             { dispatchEventId: data.id },
             () => this.fetchAndHandleScheduleFire(data.source_id, data.actor_id),
-            () => {
-              this.opts.client.ackDispatchByID(this.opts.config.org_id, data.id).catch(() => {});
-            },
+            () => this.ackDispatchEvent(data.id, () => this.clearTypedDispatchDedupe(data)),
           );
         } catch (err) {
           this.opts.log?.error(
@@ -531,9 +554,7 @@ export class ParallAgentGateway {
           await this.consumeTypedDispatch(
             { dispatchEventId: data.id },
             () => this.fetchAndHandleExternalTriggerRun(data.source_id),
-            () => {
-              this.opts.client.ackDispatchByID(this.opts.config.org_id, data.id).catch(() => {});
-            },
+            () => this.ackDispatchEvent(data.id, () => this.clearTypedDispatchDedupe(data)),
           );
         } catch (err) {
           this.opts.log?.error(
@@ -546,9 +567,7 @@ export class ParallAgentGateway {
           await this.consumeTypedDispatch(
             { dispatchEventId: data.id },
             () => this.fetchAndHandleChannelMessage(data.source_id),
-            () => {
-              this.opts.client.ackDispatchByID(this.opts.config.org_id, data.id).catch(() => {});
-            },
+            () => this.ackDispatchEvent(data.id, () => this.clearTypedDispatchDedupe(data)),
           );
         } catch (err) {
           this.opts.log?.error(
@@ -566,9 +585,7 @@ export class ParallAgentGateway {
                 data.actor_id,
                 data.chat_id ?? null,
               ),
-            () => {
-              this.opts.client.ackDispatchByID(this.opts.config.org_id, data.id).catch(() => {});
-            },
+            () => this.ackDispatchEvent(data.id, () => this.clearTypedDispatchDedupe(data)),
           );
         } catch (err) {
           this.opts.log?.error(
@@ -589,14 +606,11 @@ export class ParallAgentGateway {
         } catch (err) {
           this.opts.log?.error(`message re-drive failed for ${data.source_id}: ${String(err)}`);
         }
-      } else if (data.event_type !== 'message' && data.event_type !== 'task_assign') {
+      } else if (data.event_type !== 'message') {
         // Truly unknown event_type — log so a newly-added dispatch type
-        // not yet wired here surfaces during runtime testing. "message"
-        // and "task_assign" are deliberately excluded: dispatch.new
-        // carries them too, but they are owned by dedicated WS handlers
-        // (message.new, task.assigned) above and would otherwise spam
-        // info-level logs for every inbound chat message / task
-        // assignment on a busy agent.
+        // not yet wired here surfaces during runtime testing. "message" is
+        // deliberately excluded because its first delivery is owned by the
+        // message.new handler; recovered task_assign rows are handled above.
         this.opts.log?.info(
           `dispatch.new with unhandled event_type=${String(data.event_type)} (id=${data.id}) — no-op`,
         );
@@ -686,11 +700,63 @@ export class ParallAgentGateway {
   private consumeTypedDispatch(
     ref: { dispatchEventId?: string; sourceType?: string; sourceId?: string },
     run: (dispatchEventId?: string) => Promise<boolean>,
-    ack: (dispatchEventId?: string) => 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. 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(
+      () => true,
+      (err) => {
+        // Complete will return the still-received item to pending and publish
+        // an immediate hint. Free its hot-path claim first, otherwise that
+        // same-process re-drive is rejected forever by the local dedupe set.
+        onFailure?.();
+        this.opts.log?.warn(
+          `dispatch ack failed for ${dispatchEventId}, releasing for re-drive: ${String(err)}`,
+        );
+        return false;
+      },
+    );
+  }
+
+  private clearTypedDispatchDedupe(item: DispatchNewData): void {
+    switch (item.event_type) {
+      case 'task_assign':
+      case 'task_update':
+        if (item.task_id) {
+          const prefix = `${item.task_id}:`;
+          for (const key of this.dispatchedTasks) {
+            if (key.startsWith(prefix)) this.dispatchedTasks.delete(key);
+          }
+        }
+        break;
+      case 'task_comment':
+      case 'wiki_comment':
+        if (item.source_id) this.dispatchedTasks.delete(`comment:${item.source_id}`);
+        break;
+      case 'schedule.fire':
+        if (item.source_id) this.dispatchedTasks.delete(`schedule_run:${item.source_id}`);
+        break;
+      case 'external_trigger':
+        if (item.source_id) this.dispatchedTasks.delete(`external_trigger_run:${item.source_id}`);
+        break;
+      case 'channel_message':
+        if (item.source_id) this.dispatchedMessages.delete(`channel_message:${item.source_id}`);
+        break;
+      case 'approval_decided':
+        if (item.source_id) this.dispatchedTasks.delete(`approval:${item.source_id}`);
+        break;
+    }
+  }
+
   private buildDispatchContext(event: ParallEvent, sessionKey: string): DispatchContext {
     const binding = this.sessionBindings.get(sessionKey);
     return {
@@ -2023,6 +2089,25 @@ export class ParallAgentGateway {
     });
   }
 
+  // A task assignment's first delivery rides task.assigned, but a typed lane
+  // released without an effect is re-driven as dispatch.new. Reuse the exact
+  // typed claim path used by catch-up so that recovery does not require a
+  // runtime reconnect.
+  private async handleTaskAssignmentRedrive(item: DispatchNewData): Promise<void> {
+    if (!item.task_id) return;
+    await this.consumeTypedDispatch(
+      { dispatchEventId: item.id },
+      (dispatchEventId) =>
+        this.handleTaskDispatch(item.task_id ?? '', item.source_id ?? item.task_id ?? '', {
+          dispatchEventId,
+        }),
+      (dispatchEventId) =>
+        this.ackDispatchEvent(dispatchEventId ?? item.id, () =>
+          this.clearTypedDispatchDedupe(item),
+        ),
+    );
+  }
+
   private consumeMessageWorkItem(item: {
     id: string;
     source_id: string;
@@ -2410,6 +2495,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,
@@ -2424,6 +2522,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,
     };
@@ -2596,9 +2695,8 @@ export class ParallAgentGateway {
 
         processed++;
         try {
-          const ackItem = () => {
-            this.opts.client.ackDispatchByID(this.opts.config.org_id, item.id).catch(() => {});
-          };
+          const ackItem = () =>
+            this.ackDispatchEvent(item.id, () => this.clearTypedDispatchDedupe(item));
           if (item.event_type === 'task_assign' && item.task_id) {
             try {
               await this.consumeTypedDispatch(