@pnds/pond 1.0.1 → 1.2.0

package/src/gateway.ts

@@ -1,14 +1,31 @@
-import type { ChannelGatewayAdapter, PluginRuntime } from "openclaw/plugin-sdk";
-import { PondClient, PondWs, MENTION_ALL_USER_ID, WS_EVENTS } from "@pnds/sdk";
-import type { Chat, MessageNewData, TextContent, MediaContent, HelloData, ChatUpdateData, AgentConfigUpdateData } from "@pnds/sdk";
+import type { PluginRuntime } from "openclaw/plugin-sdk";
+import type { ChannelPlugin } from "openclaw/plugin-sdk/core";
+
+/** Extract ChannelGatewayAdapter from ChannelPlugin (removed from public SDK exports in 2026.3.24). */
+type ChannelGatewayAdapter<T = unknown> = NonNullable<ChannelPlugin<T>["gateway"]>;
+import { PondClient, PondWs, MENTION_ALL_USER_ID } from "@pnds/sdk";
+import type { Chat, MessageNewData, TextContent, MediaContent, HelloData, ChatUpdateData, AgentConfigUpdateData, TaskAssignedData, Task } from "@pnds/sdk";
 import type { PondChannelConfig } from "./types.js";
 import * as os from "node:os";
 import * as path from "node:path";
 import { resolvePondAccount } from "./accounts.js";
-import { getPondRuntime, setPondAccountState, getPondAccountState, removePondAccountState, setSessionChatId } from "./runtime.js";
-import { buildSessionKey } from "./session.js";
+import {
+  getPondRuntime,
+  setPondAccountState,
+  getPondAccountState,
+  removePondAccountState,
+  setSessionChatId,
+  setSessionMessageId,
+  setDispatchMessageId,
+  setDispatchNoReply,
+} from "./runtime.js";
+import type { PondEvent, DispatchState, ForkResult } from "./runtime.js";
+import { buildOrchestratorSessionKey } from "./session.js";
 import type { ResolvedPondAccount } from "./types.js";
 import { fetchAndApplyPlatformConfig } from "./config-manager.js";
+import { startWikiHelper } from "./wiki-helper.js";
+import { routeTrigger, defaultRoutingStrategy } from "./routing.js";
+import { forkOrchestratorSession, cleanupForkSession, resolveTranscriptFile } from "./fork.js";
 
 function resolveWsUrl(account: ResolvedPondAccount): string {
   if (account.config.ws_url) return account.config.ws_url;
@@ -17,20 +34,22 @@ function resolveWsUrl(account: ResolvedPondAccount): string {
   return `${wsBase}/ws`;
 }
 
+type ChatInfo = { type: Chat["type"]; name: string | null };
+
 /**
- * Fetch all chats with pagination and populate the type map.
+ * Fetch all chats with pagination and populate the info map (type + name).
  */
 async function fetchAllChats(
   client: PondClient,
   orgId: string,
-  chatTypeMap: Map<string, Chat["type"]>,
+  chatInfoMap: Map<string, ChatInfo>,
 ): Promise<number> {
   let cursor: string | undefined;
   let total = 0;
   do {
     const res = await client.getChats(orgId, { limit: 100, cursor });
     for (const c of res.data) {
-      chatTypeMap.set(c.id, c.type);
+      chatInfoMap.set(c.id, { type: c.type, name: c.name ?? null });
     }
     total += res.data.length;
     cursor = res.has_more ? res.next_cursor : undefined;
@@ -38,10 +57,54 @@ async function fetchAllChats(
   return total;
 }
 
-/**
- * Dispatch an inbound message to the OpenClaw agent and handle the reply.
- * Shared by both text and file message handlers to avoid duplication.
- */
+// ---------------------------------------------------------------------------
+// Event body formatting
+// ---------------------------------------------------------------------------
+
+function buildEventBody(event: PondEvent): string {
+  const lines: string[] = [];
+  if (event.type === "message") {
+    lines.push(`[Event: message.new]`);
+    const chatLabel = event.targetName
+      ? `"${event.targetName}" (${event.targetId})`
+      : event.targetId;
+    lines.push(`[Chat: ${chatLabel} | type: ${event.targetType ?? "unknown"}]`);
+    lines.push(`[From: ${event.senderName} (${event.senderId})]`);
+    lines.push(`[Message ID: ${event.messageId}]`);
+    if (event.threadRootId) lines.push(`[Thread: ${event.threadRootId}]`);
+    if (event.noReply) lines.push(`[Hint: no_reply]`);
+    if (event.mediaFields?.MediaUrl) {
+      lines.push(`[Attachment: ${event.mediaFields.MediaType ?? "file"} ${event.mediaFields.MediaUrl}]`);
+    }
+    lines.push("", event.body);
+  } else {
+    lines.push(`[Event: task.assigned]`);
+    const taskLabel = event.targetName
+      ? `${event.targetName} (${event.targetId})`
+      : event.targetId;
+    lines.push(`[Task: ${taskLabel} | type: ${event.targetType ?? "task"}]`);
+    lines.push(`[Assigned by: ${event.senderName} (${event.senderId})]`);
+    lines.push("", event.body);
+  }
+  return lines.join("\n");
+}
+
+function buildForkResultPrefix(results: ForkResult[]): string {
+  if (!results.length) return "";
+  const blocks = results.map((r) => {
+    const lines = [`[Fork result]`];
+    lines.push(`[Handled: ${r.sourceEvent.type} — ${r.sourceEvent.summary}]`);
+    if (r.actions.length) lines.push(`[Actions: ${r.actions.join("; ")}]`);
+    if (r.agentRunId) lines.push(`[Agent run: ${r.agentRunId}]`);
+    return lines.join("\n");
+  });
+  return blocks.join("\n\n") + "\n\n---\n\n";
+}
+
+// ---------------------------------------------------------------------------
+// Dispatch to OpenClaw agent (orchestrator mode — all text suppressed)
+// ---------------------------------------------------------------------------
+
 async function dispatchToAgent(opts: {
   core: PluginRuntime;
   cfg: Record<string, unknown>;
@@ -50,12 +113,19 @@ async function dispatchToAgent(opts: {
   agentUserId: string;
   accountId: string;
   sessionKey: string;
-  chatId: string;
   messageId: string;
   inboundCtx: Record<string, unknown>;
+  triggerType?: string;
+  triggerRef?: Record<string, unknown>;
+  chatId?: string;
+  /** For task dispatches: bind the run to a task target for Redis presence + fallback comments. */
+  defaultTargetType?: string;
+  defaultTargetId?: string;
   log?: { info: (msg: string) => void; warn: (msg: string) => void; error: (msg: string) => void };
 }) {
-  const { core, cfg, client, config, agentUserId, accountId, sessionKey, chatId, messageId, inboundCtx, log } = opts;
+  const { core, cfg, client, config, agentUserId, accountId, sessionKey, messageId, inboundCtx, log } = opts;
+  const triggerType = opts.triggerType ?? "mention";
+  const triggerRef = opts.triggerRef ?? { message_id: messageId };
   const sessionKeyLower = sessionKey.toLowerCase();
   let thinkingSent = false;
   let runIdPromise: Promise<string | undefined> | undefined;
@@ -66,31 +136,22 @@ async function dispatchToAgent(opts: {
       cfg,
       dispatcherOptions: {
         deliver: async (payload: { text?: string }, info: { kind: string }) => {
+          // Orchestrator mode: ALL text output is suppressed — agent uses tools to interact.
+          // Record as internal step for observability.
           const replyText = payload.text?.trim();
           if (!replyText) return;
-          // Wait for run creation to complete before sending
           const runId = runIdPromise ? await runIdPromise : undefined;
-
-          if (info.kind === "final") {
-            // Final reply → chat message
-            await client.sendMessage(config.org_id, chatId, {
-              message_type: "text",
-              content: { text: replyText },
-              agent_run_id: runId,
-            });
-          } else if (info.kind === "block" && runId) {
-            // Intermediate text → step with chat_projection hint (server decides)
+          if (runId) {
             try {
               await client.createAgentStep(config.org_id, agentUserId, runId, {
                 step_type: "text",
-                content: { text: replyText },
-                chat_projection: true,
+                content: { text: replyText, suppressed: true },
+                ...(info.kind === "block" ? { chat_projection: false } : {}),
               });
             } catch (err) {
-              log?.warn(`pond[${accountId}]: failed to create text step: ${String(err)}`);
+              log?.warn(`pond[${accountId}]: failed to create suppressed text step: ${String(err)}`);
             }
           }
-          // kind === "tool" → ignore (handled by hooks)
         },
         onReplyStart: () => {
           if (thinkingSent) return;
@@ -98,9 +159,10 @@ async function dispatchToAgent(opts: {
           runIdPromise = (async () => {
             try {
               const run = await client.createAgentRun(config.org_id, agentUserId, {
-                trigger_type: "mention",
-                trigger_ref: { message_id: messageId },
-                chat_id: chatId,
+                trigger_type: triggerType,
+                trigger_ref: triggerRef,
+                ...(opts.chatId ? { chat_id: opts.chatId } : {}),
+                ...(opts.defaultTargetType ? { default_target_type: opts.defaultTargetType, default_target_id: opts.defaultTargetId } : {}),
               });
               return run.id;
             } catch (err) {
@@ -108,7 +170,6 @@ async function dispatchToAgent(opts: {
               return undefined;
             }
           })();
-          // Store promise immediately so hooks can await it before the run is created
           const state = getPondAccountState(accountId);
           if (state) state.activeRuns.set(sessionKeyLower, runIdPromise);
         },
@@ -133,11 +194,17 @@ async function dispatchToAgent(opts: {
         },
       },
     });
+    return true;
   } catch (err) {
     log?.error(`pond[${accountId}]: dispatch failed for ${messageId}: ${String(err)}`);
+    return false;
   }
 }
 
+// ---------------------------------------------------------------------------
+// Gateway
+// ---------------------------------------------------------------------------
+
 export const pondGateway: ChannelGatewayAdapter<ResolvedPondAccount> = {
   startAccount: async (ctx) => {
     const account = resolvePondAccount({ cfg: ctx.cfg, accountId: ctx.accountId });
@@ -158,16 +225,21 @@ export const pondGateway: ChannelGatewayAdapter<ResolvedPondAccount> = {
     const agentUserId = me.id;
     log?.info(`pond[${ctx.accountId}]: authenticated as ${me.display_name} (${agentUserId})`);
 
-    // Inject env vars so child processes (e.g. @pnds/cli) inherit Pond credentials
-    process.env.POND_API_URL = config.pond_url;
-    process.env.POND_API_KEY = config.api_key;
-    process.env.POND_ORG_ID = config.org_id;
-
     // Apply platform config (models, defaults)
-    // Use OPENCLAW_STATE_DIR if set, otherwise derive from HOME (systemd sets HOME=/data for hosted agents)
     const stateDir = process.env.OPENCLAW_STATE_DIR
       || path.join(process.env.HOME || "/data", ".openclaw");
     const openclawConfigPath = path.join(stateDir, "openclaw.json");
+    const previousEnv = {
+      POND_API_URL: process.env.POND_API_URL,
+      POND_API_KEY: process.env.POND_API_KEY,
+      POND_ORG_ID: process.env.POND_ORG_ID,
+      POND_AGENT_ID: process.env.POND_AGENT_ID,
+    };
+    process.env.POND_API_URL = config.pond_url;
+    process.env.POND_API_KEY = config.api_key;
+    process.env.POND_ORG_ID = config.org_id;
+    process.env.POND_AGENT_ID = agentUserId;
+
     const configManagerOpts = {
       client,
       stateDir,
@@ -182,6 +254,24 @@ export const pondGateway: ChannelGatewayAdapter<ResolvedPondAccount> = {
       log?.warn(`pond[${ctx.accountId}]: platform config fetch failed: ${String(err)}`);
     }
 
+    let stopWikiHelper: (() => void) | null = null;
+    let wikiMountRoot: string | undefined;
+    try {
+      const wikiHelper = await startWikiHelper({
+        accountId: ctx.accountId,
+        pondUrl: config.pond_url,
+        apiKey: config.api_key,
+        orgId: config.org_id,
+        agentId: agentUserId,
+        stateDir,
+        log,
+      });
+      wikiMountRoot = wikiHelper.mountRoot;
+      stopWikiHelper = wikiHelper.stop;
+    } catch (err) {
+      log?.warn(`pond[${ctx.accountId}]: wiki helper startup failed: ${String(err)}`);
+    }
+
     // Connect WebSocket via ticket auth (reconnection enabled by default in PondWs)
     const wsUrl = resolveWsUrl(account);
     const ws = new PondWs({
@@ -189,40 +279,390 @@ export const pondGateway: ChannelGatewayAdapter<ResolvedPondAccount> = {
       wsUrl,
     });
 
-    // Chat type lookup — populated on hello, used by message handler
-    const chatTypeMap = new Map<string, Chat["type"]>();
+    // Orchestrator session key — single session for all Pond events
+    const orchestratorKey = buildOrchestratorSessionKey(ctx.accountId);
+
+    // Chat info lookup — populated on hello, used for structured event bodies
+    const chatInfoMap = new Map<string, ChatInfo>();
 
     // Session ID from hello — used for heartbeat
     let sessionId = "";
-    // Heartbeat interval handle — created inside hello handler with server-provided interval
     let heartbeatTimer: ReturnType<typeof setInterval> | null = null;
-    // Track active dispatches per chat for typing indicator management
+    // Typing indicator management — reference-counted per chat
     const activeDispatches = new Map<string, { count: number; typingTimer: ReturnType<typeof setInterval> }>();
-    // Heartbeat watchdog: detect event loop blocking during long CC runs
+    // Dedupe task dispatches
+    const dispatchedTasks = new Set<string>();
+    // Dedupe message dispatches — shared by live handler and catch-up.
+    // Bounded: evict oldest entries when cap is reached.
+    const dispatchedMessages = new Set<string>();
+    const DISPATCHED_MESSAGES_CAP = 5000;
+    // Tracks whether the agent has had at least one successful hello in this process.
+    let hadSuccessfulHello = false;
+    const COLD_START_WINDOW_MS = 5 * 60_000;
+    // Heartbeat watchdog
     let lastHeartbeatAt = Date.now();
 
-    // Log connection state changes (covers reconnection)
+    /** Atomically claim a message ID for processing. Returns false if already claimed. */
+    function tryClaimMessage(id: string): boolean {
+      if (dispatchedMessages.has(id)) return false;
+      if (dispatchedMessages.size >= DISPATCHED_MESSAGES_CAP) {
+        let toEvict = Math.floor(DISPATCHED_MESSAGES_CAP / 4);
+        for (const old of dispatchedMessages) {
+          dispatchedMessages.delete(old);
+          if (--toEvict <= 0) break;
+        }
+      }
+      dispatchedMessages.add(id);
+      return true;
+    }
+
+    // Sessions dir for fork transcript resolution.
+    // Session key "agent:main:pond:..." → agentId is "main" → store at agents/main/sessions/
+    const sessionsDir = path.join(stateDir, "agents", "main", "sessions");
+
+    // ---------------------------------------------------------------------------
+    // Dispatch state for fork-on-busy routing
+    // ---------------------------------------------------------------------------
+    const dispatchState: DispatchState = {
+      mainDispatching: false,
+      activeForks: new Map(),
+      pendingForkResults: [],
+      mainBuffer: [],
+    };
+
+    // ---------------------------------------------------------------------------
+    // Per-fork queue state (internal to gateway, not exposed via DispatchState)
+    // ---------------------------------------------------------------------------
+    type ForkQueueItem = {
+      event: PondEvent;
+      resolve: (dispatched: boolean) => void;
+    };
+
+    type ActiveForkState = {
+      sessionKey: string;
+      sessionFile: string;
+      targetId: string;
+      queue: ForkQueueItem[];
+      processedEvents: PondEvent[];
+    };
+
+    const forkStates = new Map<string, ActiveForkState>();
+
+    // ---------------------------------------------------------------------------
+    // Typing indicator helpers
+    // ---------------------------------------------------------------------------
+    function startTyping(chatId: string) {
+      const existing = activeDispatches.get(chatId);
+      if (existing) {
+        existing.count++;
+      } else {
+        if (ws.state === "connected") ws.sendTyping(chatId, "start");
+        const typingRefresh = setInterval(() => {
+          if (ws.state === "connected") ws.sendTyping(chatId, "start");
+        }, 2000);
+        activeDispatches.set(chatId, { count: 1, typingTimer: typingRefresh });
+      }
+    }
+
+    function stopTyping(chatId: string) {
+      const dispatch = activeDispatches.get(chatId);
+      if (!dispatch) return;
+      dispatch.count--;
+      if (dispatch.count <= 0) {
+        clearInterval(dispatch.typingTimer);
+        activeDispatches.delete(chatId);
+        if (ws.state === "connected") ws.sendTyping(chatId, "stop");
+      }
+    }
+
+    // ---------------------------------------------------------------------------
+    // Fork drain loop — processes queued events on a forked session
+    // ---------------------------------------------------------------------------
+
+    /**
+     * Process all queued events on a fork session, then clean up.
+     * Fire-and-forget: callers await per-event promises, not this function.
+     *
+     * Invariant: between the while-loop empty check and cleanup, there is no
+     * await, so JS single-threaded execution guarantees no new events can be
+     * pushed to the queue between the check and the cleanup.
+     */
+    async function runForkDrainLoop(fork: ActiveForkState) {
+      try {
+        while (fork.queue.length > 0) {
+          const item = fork.queue.shift()!;
+          try {
+            await runDispatch(item.event, fork.sessionKey, buildEventBody(item.event));
+            fork.processedEvents.push(item.event);
+            item.resolve(true);
+          } catch (err) {
+            log?.error(`pond[${ctx.accountId}]: fork dispatch failed for ${item.event.messageId}: ${String(err)}`);
+            item.resolve(false);
+            break;
+          }
+        }
+        // Resolve remaining items as not-dispatched (fork stopped after error).
+        // These events are NOT acked — inbox retains them for catch-up replay.
+        for (const remaining of fork.queue.splice(0)) {
+          remaining.resolve(false);
+        }
+      } finally {
+        // Collect fork result for injection into main session's next turn
+        if (fork.processedEvents.length > 0) {
+          const first = fork.processedEvents[0];
+          dispatchState.pendingForkResults.push({
+            forkSessionKey: fork.sessionKey,
+            sourceEvent: {
+              type: first.type,
+              targetId: fork.targetId,
+              summary: fork.processedEvents.length === 1
+                ? `${first.type} from ${first.senderName} in ${first.targetName ?? fork.targetId}`
+                : `${fork.processedEvents.length} events in ${first.targetName ?? fork.targetId}`,
+            },
+            actions: [],
+            agentRunId: undefined,
+          });
+        }
+        // Remove from tracking maps and clean up session files
+        forkStates.delete(fork.targetId);
+        dispatchState.activeForks.delete(fork.targetId);
+        cleanupForkSession({ sessionFile: fork.sessionFile, sessionKey: fork.sessionKey, sessionsDir });
+      }
+    }
+
+    // ---------------------------------------------------------------------------
+    // Build OpenClaw inbound context
+    // ---------------------------------------------------------------------------
+    function buildInboundCtx(event: PondEvent, sessionKey: string, bodyForAgent: string): Record<string, unknown> {
+      return core.channel.reply.finalizeInboundContext({
+        Body: event.body,
+        BodyForAgent: bodyForAgent,
+        RawBody: event.body,
+        CommandBody: event.body,
+        ...(event.mediaFields ?? {}),
+        From: `pond:${event.senderId}`,
+        To: `pond:orchestrator`,
+        SessionKey: sessionKey,
+        AccountId: ctx.accountId,
+        ChatType: event.targetType ?? "unknown",
+        SenderName: event.senderName,
+        SenderId: event.senderId,
+        Provider: "pond" as const,
+        Surface: "pond" as const,
+        MessageSid: event.messageId,
+        Timestamp: Date.now(),
+        CommandAuthorized: true,
+        OriginatingChannel: "pond" as const,
+        OriginatingTo: `pond:orchestrator`,
+      });
+    }
+
+    // ---------------------------------------------------------------------------
+    // Core dispatch: route event to main or fork session
+    // ---------------------------------------------------------------------------
+    async function runDispatch(event: PondEvent, sessionKey: string, bodyForAgent: string) {
+      // Set provenance maps for wiki tools + no_reply suppression flag
+      setSessionChatId(sessionKey, event.targetId);
+      setSessionMessageId(sessionKey, event.messageId);
+      setDispatchMessageId(sessionKey, event.messageId);
+      setDispatchNoReply(sessionKey, event.noReply ?? false);
+
+      const inboundCtx = buildInboundCtx(event, sessionKey, bodyForAgent);
+      const triggerType = event.type === "task" ? "task_assign" : "mention";
+      const triggerRef = event.type === "task"
+        ? { task_id: event.targetId }
+        : { message_id: event.messageId };
+      const isTask = event.type === "task";
+
+      const ok = await dispatchToAgent({
+        core,
+        cfg: ctx.cfg,
+        client,
+        config,
+        agentUserId,
+        accountId: ctx.accountId,
+        sessionKey,
+        messageId: event.messageId,
+        inboundCtx,
+        triggerType,
+        triggerRef,
+        chatId: event.targetId.startsWith("cht_") ? event.targetId : undefined,
+        defaultTargetType: isTask ? "task" : undefined,
+        defaultTargetId: isTask ? event.targetId : undefined,
+        log,
+      });
+      if (!ok) throw new Error(`dispatch failed for ${event.messageId}`);
+    }
+
+    /**
+     * Drain buffered events one-by-one into main session.
+     * Each event gets its own dispatch (and thus its own AgentRun) to keep provenance correct.
+     *
+     * IMPORTANT: Caller must hold mainDispatching=true. This function keeps the flag
+     * raised throughout the drain to prevent re-entrance from concurrent event handlers.
+     * The flag is only lowered when the buffer is fully exhausted.
+     */
+    let draining = false;
+    async function drainMainBuffer() {
+      // Re-entrance guard: if we're already draining (e.g. fork completed during
+      // a drain iteration), the outer loop will pick up new items naturally.
+      if (draining) return;
+      draining = true;
+      try {
+        while (dispatchState.mainBuffer.length > 0 || dispatchState.pendingForkResults.length > 0) {
+          // If we only have fork results but no events, create a synthetic wake-up
+          if (dispatchState.mainBuffer.length === 0 && dispatchState.pendingForkResults.length > 0) {
+            const forkPrefix = buildForkResultPrefix(dispatchState.pendingForkResults.splice(0));
+            const syntheticEvent: PondEvent = {
+              type: "message",
+              targetId: "_orchestrator",
+              targetType: "system",
+              senderId: "system",
+              senderName: "system",
+              messageId: `synthetic-${Date.now()}`,
+              body: "[Orchestrator: fork session(s) completed — review results above]",
+            };
+            const bodyForAgent = forkPrefix + buildEventBody(syntheticEvent);
+            dispatchState.mainCurrentTargetId = undefined;
+            await runDispatch(syntheticEvent, orchestratorKey, bodyForAgent);
+            continue;
+          }
+
+          // Take ONE event at a time for correct provenance
+          const event = dispatchState.mainBuffer.shift()!;
+          const forkPrefix = buildForkResultPrefix(dispatchState.pendingForkResults.splice(0));
+          const bodyForAgent = forkPrefix + buildEventBody(event);
+
+          dispatchState.mainCurrentTargetId = event.targetId;
+          await runDispatch(event, orchestratorKey, bodyForAgent);
+          // Ack inbox after successful drain dispatch — these events were buffered
+          // without ack, so this is the first time they're confirmed processed.
+          const sourceType = event.type === "task" ? "task_activity" : "message";
+          client.ackInbox(config.org_id, { source_type: sourceType, source_id: event.messageId }).catch(() => {});
+        }
+      } finally {
+        draining = false;
+        dispatchState.mainDispatching = false;
+        dispatchState.mainCurrentTargetId = undefined;
+      }
+    }
+
+    /**
+     * Route and dispatch an inbound event.
+     * Returns true if the event was dispatched (main or fork), false if only buffered.
+     * Callers should only ack inbox when this returns true — buffered events may be
+     * lost on crash and need to be replayed from inbox on the next catch-up.
+     */
+    async function handleInboundEvent(event: PondEvent): Promise<boolean> {
+      const disposition = routeTrigger(event, dispatchState, defaultRoutingStrategy);
+
+      switch (disposition.action) {
+        case "main": {
+          // Main session is idle — dispatch directly.
+          // Set mainDispatching BEFORE the await and keep it raised through
+          // drainMainBuffer() so no concurrent event can enter this case.
+          // drainMainBuffer() lowers the flag when the buffer is fully exhausted.
+          const forkPrefix = buildForkResultPrefix(dispatchState.pendingForkResults.splice(0));
+          const bodyForAgent = forkPrefix + buildEventBody(event);
+
+          dispatchState.mainDispatching = true;
+          dispatchState.mainCurrentTargetId = event.targetId;
+          try {
+            await runDispatch(event, orchestratorKey, bodyForAgent);
+          } finally {
+            // Drain any events that buffered while we were dispatching.
+            // mainDispatching stays true — drainMainBuffer owns releasing it.
+            await drainMainBuffer();
+          }
+          return true;
+        }
+
+        case "buffer-main":
+          dispatchState.mainBuffer.push(event);
+          return false;
+
+        case "buffer-fork": {
+          // Push event into the existing fork's queue. The fork drain loop will
+          // process it and resolve the promise when done. If the fork was cleaned
+          // up between the routing decision and here (race), fallback to buffer-main.
+          const activeFork = forkStates.get(event.targetId);
+          if (!activeFork) {
+            dispatchState.mainBuffer.push(event);
+            return false;
+          }
+          return new Promise<boolean>((resolve) => {
+            activeFork.queue.push({ event, resolve });
+          });
+        }
+
+        case "new-fork": {
+          // Fork the orchestrator's transcript and dispatch in parallel.
+          const transcriptFile = resolveTranscriptFile(sessionsDir, orchestratorKey);
+          const fork = transcriptFile
+            ? forkOrchestratorSession({
+                orchestratorSessionKey: orchestratorKey,
+                accountId: ctx.accountId,
+                transcriptFile,
+                sessionsDir,
+              })
+            : null;
+
+          if (fork) {
+            const activeFork: ActiveForkState = {
+              sessionKey: fork.sessionKey,
+              sessionFile: fork.sessionFile,
+              targetId: event.targetId,
+              queue: [],
+              processedEvents: [],
+            };
+            forkStates.set(event.targetId, activeFork);
+            dispatchState.activeForks.set(event.targetId, fork.sessionKey);
+
+            // Create promise for the first event, then start the drain loop
+            const firstEventPromise = new Promise<boolean>((resolve) => {
+              activeFork.queue.push({ event, resolve });
+            });
+            // Fire-and-forget — drain loop runs concurrently, callers await per-event promises
+            runForkDrainLoop(activeFork).catch((err) => {
+              log?.error(`pond[${ctx.accountId}]: fork drain loop error: ${String(err)}`);
+            });
+            return firstEventPromise;
+          } else {
+            log?.warn(`pond[${ctx.accountId}]: fork failed, buffering event for main session`);
+            dispatchState.mainBuffer.push(event);
+            return false;
+          }
+        }
+      }
+      return false;
+    }
+
+    // ---------------------------------------------------------------------------
+    // WebSocket event handlers
+    // ---------------------------------------------------------------------------
+
     ws.onStateChange((state) => {
       log?.info(`pond[${ctx.accountId}]: connection state → ${state}`);
     });
 
-    // On hello, cache chat types and start heartbeat with server-provided interval
     ws.on("hello", async (data: HelloData) => {
       sessionId = data.session_id ?? "";
       const intervalSec = data.heartbeat_interval > 0 ? data.heartbeat_interval : 30;
       try {
-        const count = await fetchAllChats(client, config.org_id, chatTypeMap);
+        const count = await fetchAllChats(client, config.org_id, chatInfoMap);
         log?.info(`pond[${ctx.accountId}]: WebSocket connected, ${count} chats cached`);
 
-        // Cache client state only after successful connection
         setPondAccountState(ctx.accountId, {
           client,
           orgId: config.org_id,
           agentUserId,
           activeRuns: new Map(),
+          wikiMountRoot,
+          ws,
+          orchestratorSessionKey: orchestratorKey,
         });
 
-        // (Re)start heartbeat with server-provided interval
+        // (Re)start heartbeat
         if (heartbeatTimer) clearInterval(heartbeatTimer);
         lastHeartbeatAt = Date.now();
         heartbeatTimer = setInterval(() => {
@@ -242,16 +682,31 @@ export const pondGateway: ChannelGatewayAdapter<ResolvedPondAccount> = {
             uptime: os.uptime(),
           });
         }, intervalSec * 1000);
+
+        // Unified inbox catch-up (replaces separate mention/DM/task catch-up).
+        // On cold start, skip items older than COLD_START_WINDOW_MS to avoid
+        // replaying historical backlog from a previous process.
+        const isFirstHello = !hadSuccessfulHello;
+        hadSuccessfulHello = true;
+        catchUpFromInbox(isFirstHello).catch((err) => {
+          log?.warn(`pond[${ctx.accountId}]: inbox catch-up failed: ${String(err)}`);
+        });
       } catch (err) {
         log?.error(`pond[${ctx.accountId}]: failed to fetch chats: ${String(err)}`);
       }
     });
 
-    // Track chat type changes (new chats, renames, etc.)
     ws.on("chat.update", (data: ChatUpdateData) => {
       const changes = data.changes as Record<string, unknown> | undefined;
-      if (changes && typeof changes.type === "string") {
-        chatTypeMap.set(data.chat_id, changes.type as Chat["type"]);
+      if (!changes) return;
+      const existing = chatInfoMap.get(data.chat_id);
+      if (typeof changes.type === "string") {
+        chatInfoMap.set(data.chat_id, {
+          type: changes.type as Chat["type"],
+          name: (typeof changes.name === "string" ? changes.name : existing?.name) ?? null,
+        });
+      } else if (typeof changes.name === "string" && existing) {
+        chatInfoMap.set(data.chat_id, { ...existing, name: changes.name });
       }
     });
 
@@ -259,23 +714,25 @@ export const pondGateway: ChannelGatewayAdapter<ResolvedPondAccount> = {
     ws.on("message.new", async (data: MessageNewData) => {
       if (data.sender_id === agentUserId) return;
       if (data.message_type !== "text" && data.message_type !== "file") return;
+      // Dedupe: claim this message so catch-up won't re-dispatch it
+      if (!tryClaimMessage(data.id)) return;
 
       const chatId = data.chat_id;
 
-      // Resolve chat type — query API for unknown chats
-      let chatType = chatTypeMap.get(chatId);
-      if (!chatType) {
+      // Resolve chat info — query API for unknown chats
+      let chatInfo = chatInfoMap.get(chatId);
+      if (!chatInfo) {
         try {
           const chat = await client.getChat(config.org_id, chatId);
-          chatType = chat.type;
-          chatTypeMap.set(chatId, chatType);
+          chatInfo = { type: chat.type, name: chat.name ?? null };
+          chatInfoMap.set(chatId, chatInfo);
         } catch (err) {
-          log?.warn(`pond[${ctx.accountId}]: failed to resolve chat type for ${chatId}, skipping message: ${String(err)}`);
+          log?.warn(`pond[${ctx.accountId}]: failed to resolve chat for ${chatId}, skipping: ${String(err)}`);
           return;
         }
       }
 
-      // Build body text and optional media fields based on message type
+      // Build body text and optional media fields
       let body = "";
       let mediaFields: Record<string, string | undefined> = {};
 
@@ -285,106 +742,64 @@ export const pondGateway: ChannelGatewayAdapter<ResolvedPondAccount> = {
         if (!body) return;
 
         // In group chats, only respond when @mentioned or @all
-        if (chatType === "group") {
+        if (chatInfo.type === "group") {
           const mentions = content.mentions ?? [];
           const isMentioned = mentions.some(
-            (m) => m.user_id === agentUserId || m.user_id === MENTION_ALL_USER_ID
+            (m) => m.user_id === agentUserId || m.user_id === MENTION_ALL_USER_ID,
           );
           if (!isMentioned) return;
         }
       } else {
-        // file message
         const content = data.content as MediaContent;
-
-        // In group chats, file messages have no mentions field — skip
-        if (chatType === "group") return;
-
-        body = content.caption?.trim()
-          || `[file: ${content.file_name || "attachment"}]`;
-
-        // Resolve presigned download URL for the attachment
+        if (chatInfo.type === "group") return;
+        body = content.caption?.trim() || `[file: ${content.file_name || "attachment"}]`;
         if (content.attachment_id) {
           try {
             const fileRes = await client.getFileUrl(content.attachment_id);
-            mediaFields = {
-              MediaUrl: fileRes.url,
-              MediaType: content.mime_type,
-            };
+            mediaFields = { MediaUrl: fileRes.url, MediaType: content.mime_type };
           } catch (err) {
             log?.warn(`pond[${ctx.accountId}]: failed to get file URL for ${content.attachment_id}: ${String(err)}`);
-            // Degrade gracefully — agent still gets the body text
           }
         }
       }
 
-      const sessionKey = buildSessionKey(ctx.accountId, chatType, chatId);
-      setSessionChatId(sessionKey, chatId);
-
-      // Build inbound context for OpenClaw agent
-      const inboundCtx = core.channel.reply.finalizeInboundContext({
-        Body: body,
-        BodyForAgent: body,
-        RawBody: body,
-        CommandBody: body,
-        ...mediaFields,
-        From: `pond:${data.sender_id}`,
-        To: `pond:${chatId}`,
-        SessionKey: sessionKey,
-        AccountId: ctx.accountId,
-        ChatType: chatType,
-        SenderName: data.sender?.display_name ?? data.sender_id,
-        SenderId: data.sender_id,
-        Provider: "pond" as const,
-        Surface: "pond" as const,
-        MessageSid: data.id,
-        Timestamp: Date.now(),
-        CommandAuthorized: true,
-        OriginatingChannel: "pond" as const,
-        OriginatingTo: `pond:${chatId}`,
-      });
-
-      // Manage typing indicator so the user sees the agent is working.
-      // Reference-counted: concurrent dispatches for the same chat share one timer.
-      const existingDispatch = activeDispatches.get(chatId);
-      if (existingDispatch) {
-        existingDispatch.count++;
-      } else {
-        if (ws.state === "connected") ws.sendTyping(chatId, "start");
-        // Frontend auto-clears typing after 3s, so refresh at 2s to avoid flicker
-        const typingRefresh = setInterval(() => {
-          if (ws.state === "connected") ws.sendTyping(chatId, "start");
-        }, 2000);
-        activeDispatches.set(chatId, { count: 1, typingTimer: typingRefresh });
-      }
-
+      const event: PondEvent = {
+        type: "message",
+        targetId: chatId,
+        targetName: chatInfo.name ?? undefined,
+        targetType: chatInfo.type,
+        senderId: data.sender_id,
+        senderName: data.sender?.display_name ?? data.sender_id,
+        messageId: data.id,
+        body,
+        threadRootId: data.thread_root_id ?? undefined,
+        noReply: data.hints?.no_reply ?? false,
+        mediaFields: Object.keys(mediaFields).length > 0 ? mediaFields : undefined,
+      };
+
+      // Start typing for UX feedback. For buffer-main events (main is busy with
+      // same target), typing persists until the buffer drains.
+      // For fork events, typing persists until the fork dispatch completes.
+      // Both handleInboundEvent paths await their dispatches, so finally works correctly.
+      const willDispatch = !dispatchState.mainDispatching || dispatchState.mainCurrentTargetId !== chatId;
+      if (willDispatch) startTyping(chatId);
       try {
-        await dispatchToAgent({
-          core,
-          cfg: ctx.cfg,
-          client,
-          config,
-          agentUserId,
-          accountId: ctx.accountId,
-          sessionKey,
-          chatId,
-          messageId: data.id,
-          inboundCtx,
-          log,
-        });
-      } finally {
-        const dispatch = activeDispatches.get(chatId);
-        if (dispatch) {
-          dispatch.count--;
-          if (dispatch.count <= 0) {
-            clearInterval(dispatch.typingTimer);
-            activeDispatches.delete(chatId);
-            if (ws.state === "connected") ws.sendTyping(chatId, "stop");
-          }
+        const dispatched = await handleInboundEvent(event);
+        if (dispatched) {
+          client.ackInbox(config.org_id, { source_type: "message", source_id: data.id }).catch(() => {});
+        } else {
+          // Not dispatched (buffered or fork failed) — release claim so catch-up can retry
+          dispatchedMessages.delete(data.id);
         }
+      } catch (err) {
+        log?.error(`pond[${ctx.accountId}]: event dispatch failed for ${data.id}: ${String(err)}`);
+        dispatchedMessages.delete(data.id);
+      } finally {
+        if (willDispatch) stopTyping(chatId);
       }
     });
 
-    // Re-apply platform config when server pushes an update notification
+    // Re-apply platform config on server push
     ws.on("agent_config.update", async (data: AgentConfigUpdateData) => {
       log?.info(`pond[${ctx.accountId}]: config update notification (version=${data.version})`);
       try {
@@ -394,23 +809,186 @@ export const pondGateway: ChannelGatewayAdapter<ResolvedPondAccount> = {
       }
     });
 
+    // Task assignment handler
+    async function handleTaskAssignment(task: Task): Promise<boolean> {
+      const dedupeKey = `${task.id}:${task.updated_at}`;
+      if (dispatchedTasks.has(dedupeKey)) {
+        log?.info(`pond[${ctx.accountId}]: skipping already-dispatched task ${task.identifier ?? task.id}`);
+        return false;
+      }
+      dispatchedTasks.add(dedupeKey);
+      log?.info(`pond[${ctx.accountId}]: task assigned: ${task.identifier ?? task.id} "${task.title}"`);
+
+      const parts = [`Title: ${task.title}`];
+      parts.push(`Status: ${task.status}`, `Priority: ${task.priority}`);
+      if (task.description) parts.push("", task.description);
+
+      const event: PondEvent = {
+        type: "task",
+        targetId: task.id,
+        targetName: task.identifier ?? undefined,
+        targetType: "task",
+        senderId: task.creator_id,
+        senderName: "system",
+        messageId: task.id,
+        body: parts.join("\n"),
+      };
+
+      const dispatched = await handleInboundEvent(event);
+      if (!dispatched) {
+        // Buffered, not yet dispatched — release dedupe so catch-up can retry
+        dispatchedTasks.delete(dedupeKey);
+      }
+      return dispatched;
+    }
+
+    // Server event buffer overflowed — events were lost, trigger full catch-up
+    ws.on("recovery.overflow", () => {
+      log?.warn(`pond[${ctx.accountId}]: recovery.overflow — triggering full catch-up`);
+      catchUpFromInbox().catch((err) =>
+        log?.warn(`pond[${ctx.accountId}]: overflow catch-up failed: ${String(err)}`));
+    });
+
+    ws.on("task.assigned", async (data: TaskAssignedData) => {
+      if (data.assignee_id !== agentUserId) return;
+      if (data.status !== "todo" && data.status !== "in_progress") return;
+      try {
+        const dispatched = await handleTaskAssignment(data);
+        if (dispatched) {
+          client.ackInbox(config.org_id, { source_type: "task_activity", source_id: data.id }).catch(() => {});
+        }
+      } catch (err) {
+        log?.error(`pond[${ctx.accountId}]: task dispatch failed for ${data.id}: ${String(err)}`);
+      }
+    });
+
+    // ── Unified inbox catch-up ──
+    // Replays missed mentions, DMs, and task assignments via the inbox API.
+    // Adapts each item into a PondEvent and routes through handleInboundEvent.
+    async function catchUpFromInbox(coldStart = false) {
+      const minAge = coldStart ? Date.now() - COLD_START_WINDOW_MS : 0;
+      let cursor: string | undefined;
+      let processed = 0;
+      let skippedOld = 0;
+
+      do {
+        const page = await client.getInbox(config.org_id, {
+          type: "mention,agent_dm,task_assign",
+          read: "false",
+          limit: 50,
+          cursor,
+        });
+
+        for (const item of page.data ?? []) {
+          if (minAge > 0 && new Date(item.updated_at).getTime() < minAge) {
+            client.markInboxRead(config.org_id, item.id).catch(() => {});
+            skippedOld++;
+            continue;
+          }
+
+          processed++;
+          try {
+            let dispatched = false;
+            if (item.type === "task_assign" && item.source_id) {
+              // Task catch-up: fetch full task and dispatch
+              const task = await client.getTask(config.org_id, item.source_id);
+              if (task) {
+                dispatched = await handleTaskAssignment(task);
+              } else {
+                dispatched = true; // task deleted — mark read to prevent infinite retry
+              }
+            } else if (item.source_id && item.chat_id) {
+              // Message catch-up (mention or agent_dm): build PondEvent from inbox item
+              if (!tryClaimMessage(item.source_id)) continue;
+              const msg = await client.getMessage(item.source_id).catch(() => null);
+              if (!msg || msg.sender_id === agentUserId) {
+                dispatchedMessages.delete(item.source_id);
+                client.markInboxRead(config.org_id, item.id).catch(() => {});
+                continue;
+              }
+
+              let chatInfo = chatInfoMap.get(item.chat_id);
+              if (!chatInfo) {
+                try {
+                  const chat = await client.getChat(config.org_id, item.chat_id);
+                  chatInfo = { type: chat.type, name: chat.name ?? null };
+                  chatInfoMap.set(item.chat_id, chatInfo);
+                } catch {
+                  dispatchedMessages.delete(item.source_id);
+                  continue;
+                }
+              }
+
+              let body = "";
+              let catchUpMediaFields: Record<string, string | undefined> = {};
+              if (msg.message_type === "text") {
+                body = (msg.content as TextContent).text?.trim() ?? "";
+              } else if (msg.message_type === "file") {
+                const fc = msg.content as MediaContent;
+                body = fc.caption?.trim() || `[file: ${fc.file_name || "attachment"}]`;
+                if (fc.attachment_id) {
+                  try {
+                    const fileRes = await client.getFileUrl(fc.attachment_id);
+                    catchUpMediaFields = { MediaUrl: fileRes.url, MediaType: fc.mime_type };
+                  } catch { /* degrade gracefully */ }
+                }
+              }
+              if (!body) {
+                dispatchedMessages.delete(item.source_id);
+                client.markInboxRead(config.org_id, item.id).catch(() => {});
+                continue;
+              }
+
+              const event: PondEvent = {
+                type: "message",
+                targetId: item.chat_id,
+                targetName: chatInfo.name ?? undefined,
+                targetType: chatInfo.type,
+                senderId: msg.sender_id,
+                senderName: msg.sender?.display_name ?? msg.sender_id,
+                messageId: msg.id,
+                body,
+                threadRootId: msg.thread_root_id ?? undefined,
+                noReply: msg.hints?.no_reply ?? false,
+                mediaFields: Object.keys(catchUpMediaFields).length > 0 ? catchUpMediaFields : undefined,
+              };
+              dispatched = await handleInboundEvent(event);
+            }
+            if (dispatched) {
+              client.markInboxRead(config.org_id, item.id).catch(() => {});
+            }
+          } catch (err) {
+            log?.warn(`pond[${ctx.accountId}]: catch-up item ${item.id} (${item.type}) failed: ${String(err)}`);
+          }
+        }
+        cursor = page.has_more ? page.next_cursor : undefined;
+      } while (cursor);
+
+      if (processed > 0 || skippedOld > 0) {
+        log?.info(`pond[${ctx.accountId}]: inbox catch-up: processed ${processed}, skipped ${skippedOld} old item(s)`);
+      }
+    }
+
     log?.info(`pond[${ctx.accountId}]: connecting to ${wsUrl}...`);
     await ws.connect();
 
     // Clean up on abort
     ctx.abortSignal.addEventListener("abort", () => {
       if (heartbeatTimer) clearInterval(heartbeatTimer);
-      // Clean up all active typing timers to prevent leaks
       for (const [, dispatch] of activeDispatches) {
         clearInterval(dispatch.typingTimer);
       }
       activeDispatches.clear();
+      stopWikiHelper?.();
       ws.disconnect();
       removePondAccountState(ctx.accountId);
-      // Clear injected env vars so stale credentials don't leak to future subprocesses
-      delete process.env.POND_API_URL;
-      delete process.env.POND_API_KEY;
-      delete process.env.POND_ORG_ID;
+      for (const [key, value] of Object.entries(previousEnv)) {
+        if (value === undefined) {
+          delete process.env[key];
+        } else {
+          process.env[key] = value;
+        }
+      }
       log?.info(`pond[${ctx.accountId}]: disconnected`);
     });