@parall/agent-core 1.30.0 → 1.32.0

package/src/gateway-base.ts

@@ -1,7 +1,7 @@
-import * as os from "node:os";
-import * as fs from "node:fs";
-import * as path from "node:path";
-import { MENTION_ALL_USER_ID, ParallClient, ParallWs } from "@parall/sdk";
+import * as os from 'node:os';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { ApiError, MENTION_ALL_USER_ID, ParallClient, ParallWs } from '@parall/sdk';
 import type {
   AgentConfigUpdateData,
   AgentNewSessionData,
@@ -18,8 +18,13 @@ import type {
   Task,
   TaskAssignedData,
   TextContent,
-} from "@parall/sdk";
-import { buildEventBody, buildEventBodyForForkResult, buildForkResultPrefix, buildForkScopePrefix } from "./event-format.js";
+} from '@parall/sdk';
+import {
+  buildEventBody,
+  buildEventBodyForForkResult,
+  buildForkResultPrefix,
+  buildForkScopePrefix,
+} from './event-format.js';
 import type {
   CleanupForkOpts,
   DispatchAdapter,
@@ -27,28 +32,44 @@ import type {
   ForkSessionHandle,
   GatewayLogger,
   RuntimeEvent,
-} from "./dispatch-adapter.js";
-import { routeTrigger } from "./routing.js";
+} from './dispatch-adapter.js';
+import { routeTrigger } from './routing.js';
 import {
   clearDispatchMessageId,
+  clearDispatchMetrics,
   clearDispatchNoReply,
   clearSessionMessageId,
+  getDispatchMetrics,
+  recordDeliverText,
+  recordMessageSend,
+  recordNoReply,
+  recordToolCall,
+  resetDispatchMetrics,
   setDispatchMessageId,
   setDispatchNoReply,
   setSessionChatId,
   setSessionMessageId,
-} from "./session-state.js";
-import type { DispatchState, ParallEvent } from "./types.js";
+} from './session-state.js';
+import {
+  isParallSendCommand,
+  isParallNoReplyCommand,
+  extractShellCommand,
+} from './bridge-workspace.js';
+import {
+  startDispatchSpan,
+  endDispatchSpan,
+  recordDispatchMetric,
+  recordMissingReply,
+  runWithSessionKey,
+} from './telemetry.js';
+import type { DispatchState, ParallEvent } from './types.js';
+
+const LIVE_SESSION_STATUSES = new Set(['open', 'active', 'idle']);
 
 type ChatInfo = {
-  type: Chat["type"];
+  type: Chat['type'];
   name: string | null;
-  agentRoutingMode: Chat["agent_routing_mode"];
-};
-
-type ActiveDispatch = {
-  count: number;
-  typingTimer: ReturnType<typeof setInterval>;
+  agentRoutingMode: Chat['agent_routing_mode'];
 };
 
 type ForkQueueItem = {
@@ -61,6 +82,8 @@ type ActiveForkState = {
   targetId: string;
   queue: ForkQueueItem[];
   processedEvents: ParallEvent[];
+  deadlineTimer: ReturnType<typeof setTimeout> | null;
+  deadlineExceeded: boolean;
 };
 
 type DispatchableMessage = {
@@ -76,9 +99,9 @@ type DispatchableMessage = {
 };
 
 type MessageDispatchDecision =
-  | { action: "dispatch"; event: ParallEvent }
-  | { action: "skip" }
-  | { action: "retry" };
+  | { action: 'dispatch'; event: ParallEvent }
+  | { action: 'skip' }
+  | { action: 'retry' };
 
 export type ParallGatewayOptions = {
   accountId: string;
@@ -96,19 +119,32 @@ export type ParallGatewayOptions = {
   runtimeRef?: Record<string, unknown>;
   dispatchAdapter: DispatchAdapter;
   log?: GatewayLogger;
+  /** @deprecated No-op. Cold-start time filter has been removed to prevent silent dispatch loss. */
   coldStartWindowMs?: number;
   // Maximum time to wait for in-flight dispatches to finish after SIGTERM /
   // abort before forcing WS disconnect. Pod termination grace period should
   // be at least this + a few seconds for the remaining cleanup work.
   shutdownDeadlineMs?: number;
+  forkDeadlineMs?: number;
+  dispatchDeadlineMs?: number;
   contextFilePathForSession?: (sessionKey: string) => string | undefined;
   /** @deprecated Use contextFilePathForSession. Kept for runtimes that haven't migrated. */
   stepIdFilePathForSession?: (sessionKey: string) => string | undefined;
   onConfigUpdate?: (data: AgentConfigUpdateData) => Promise<void> | void;
-  onSessionReady?: (state: { activeSessionId?: string; ws: ParallWs; runtimeKey: string }) => Promise<void> | void;
-  onSessionBinding?: (state: { sessionKey: string; agentSessionId: string; runtimeSessionId: string; runtimeLaneKey: string }) => Promise<void> | void;
+  onSessionReady?: (state: {
+    activeSessionId?: string;
+    ws: ParallWs;
+    runtimeKey: string;
+  }) => Promise<void> | void;
+  onSessionBinding?: (state: {
+    sessionKey: string;
+    agentSessionId: string;
+    runtimeSessionId: string;
+    runtimeLaneKey: string;
+  }) => Promise<void> | void;
   onBeforeDisconnect?: () => Promise<void> | void;
   onNewSession?: (previousSessionId: string) => Promise<void> | void;
+  onSessionStale?: (sessionKey: string) => Promise<void> | void;
 };
 
 type AgentSessionBinding = {
@@ -134,17 +170,74 @@ export function parseShutdownDeadlineMs(raw: string | undefined): number | undef
   return Math.floor(n);
 }
 
+export function parseForkDeadlineMs(raw: string | undefined): number | undefined {
+  if (!raw) return undefined;
+  const n = Number(raw);
+  if (!Number.isFinite(n) || n <= 0 || n > 2_147_483_647) return undefined;
+  return Math.floor(n);
+}
+
+export function parseDispatchDeadlineMs(raw: string | undefined): number | undefined {
+  if (!raw) return undefined;
+  const n = Number(raw);
+  if (!Number.isFinite(n) || n < 0 || n > 2_147_483_647) return undefined;
+  return Math.floor(n);
+}
+
 function resolveStepTarget(event: ParallEvent): { target_type: string; target_id?: string } {
-  if (event.type === "task" || event.targetId.startsWith("tsk_")) {
-    return { target_type: "task", target_id: event.targetId };
+  if (event.type === 'task' || event.targetId.startsWith('tsk_')) {
+    return { target_type: 'task', target_id: event.targetId };
+  }
+  if (event.targetId.startsWith('cht_')) {
+    return { target_type: 'chat', target_id: event.targetId };
   }
-  if (event.targetId.startsWith("cht_")) {
-    return { target_type: "chat", target_id: event.targetId };
+  if (event.type === 'schedule' || event.targetId.startsWith('sch_')) {
+    return { target_type: 'schedule', target_id: event.targetId };
   }
-  if (event.type === "schedule" || event.targetId.startsWith("sch_")) {
-    return { target_type: "schedule", target_id: event.targetId };
+  if (event.type === 'wiki_comment') {
+    // target_id is the full wiki target_uri (scheme-stripped routing key). The
+    // server stores target_type freely and only publishes step WS events /
+    // projects for chat & task, so 'wiki' is an informational tag — no inline
+    // wiki step viewer exists yet.
+    return { target_type: 'wiki', target_id: event.targetId || undefined };
   }
-  return { target_type: "", target_id: event.targetId || undefined };
+  return { target_type: '', target_id: event.targetId || undefined };
+}
+
+/**
+ * Minimal parse of a wiki / changeset comment `target_uri` into its routing key
+ * and a human label, without depending on `@parall/app`'s full `prll://` parser
+ * (agent-core only depends on `@parall/sdk`). Forms:
+ *   prll://wik_abc/path/to/file.md[?rev=SHA#h=...]  → wiki page / inline anchor
+ *   prll://wcs_xyz?wiki=wik_abc                       → changeset
+ *
+ * `routingKey` is the full `target_uri` minus the `prll://` scheme — it is the
+ * gateway routing/serialization key, so distinct pages / inline anchors /
+ * changesets within the same wiki route as distinct conversations (using the
+ * bare `wik_`/`wcs_` entity id would collapse every comment in a wiki onto one
+ * lane). Stripping the scheme keeps `prll://${targetId}` correct everywhere it
+ * is reconstructed (event body, fork-scope prefix).
+ */
+function parseWikiCommentTarget(targetUri: string): {
+  routingKey: string;
+  label: string;
+  targetType: 'wiki' | 'changeset';
+} {
+  const routingKey = targetUri.replace(/^prll:\/\//, '');
+  const entityId = routingKey.match(/^([^/?#]+)/)?.[1] ?? routingKey;
+  const targetType = entityId.startsWith('wcs_') ? 'changeset' : 'wiki';
+  let label = entityId;
+  if (targetType === 'wiki') {
+    const pathMatch = routingKey.slice(entityId.length).match(/^\/([^?#]+)/);
+    if (pathMatch) {
+      try {
+        label = decodeURIComponent(pathMatch[1]);
+      } catch {
+        label = pathMatch[1];
+      }
+    }
+  }
+  return { routingKey, label, targetType };
 }
 
 async function fetchAllChats(
@@ -171,8 +264,6 @@ async function fetchAllChats(
 
 export class ParallAgentGateway {
   private readonly chatInfoMap = new Map<string, ChatInfo>();
-  private readonly activeDispatches = new Map<string, ActiveDispatch>();
-  private readonly injectedTypingCounts = new Map<string, number>();
   private readonly dispatchedTasks = new Set<string>();
   private readonly dispatchedMessages = new Set<string>();
   private readonly forkStates = new Map<string, ActiveForkState>();
@@ -183,11 +274,11 @@ export class ParallAgentGateway {
     mainBuffer: [],
   };
 
-  private sessionId = "";
+  private sessionId = '';
   private activeSessionId: string | undefined;
   private readonly sessionBindings = new Map<string, AgentSessionBinding>();
   private heartbeatTimer: ReturnType<typeof setInterval> | null = null;
-  private hadSuccessfulHello = false;
+
   private lastHeartbeatAt = Date.now();
   private draining = false;
 
@@ -201,15 +292,22 @@ export class ParallAgentGateway {
   private pendingRestartNotification: string | null = null;
 
   private readonly DISPATCHED_MESSAGES_CAP = 5000;
-  private readonly COLD_START_WINDOW_MS: number;
   // SHUTDOWN_DEADLINE_MS is read by waitForDrain via the configured value
   // below — kept as instance state so per-runtime configs can override it
   // (see parseShutdownDeadlineMs and runtime entrypoints).
   private readonly SHUTDOWN_DEADLINE_MS: number;
+  private readonly FORK_DEADLINE_MS: number;
+  private readonly DISPATCH_DEADLINE_MS: number;
 
   constructor(private readonly opts: ParallGatewayOptions) {
-    this.COLD_START_WINDOW_MS = opts.coldStartWindowMs ?? 5 * 60_000;
     this.SHUTDOWN_DEADLINE_MS = opts.shutdownDeadlineMs ?? 60_000;
+    this.FORK_DEADLINE_MS = opts.forkDeadlineMs ?? 2 * 60 * 60_000;
+    this.DISPATCH_DEADLINE_MS = opts.dispatchDeadlineMs ?? 20 * 60_000;
+    if (opts.coldStartWindowMs != null) {
+      opts.log?.warn?.(
+        'coldStartWindowMs is deprecated and ignored — cold-start time filter has been removed',
+      );
+    }
   }
 
   async run(abortSignal: AbortSignal): Promise<void> {
@@ -219,39 +317,39 @@ export class ParallAgentGateway {
       log?.info(`connection state → ${state}`);
     });
 
-    ws.on("hello", async (data: HelloData) => {
+    ws.on('hello', async (data: HelloData) => {
       await this.handleHello(data);
     });
 
-    ws.on("chat.update", (data: ChatUpdateData) => {
+    ws.on('chat.update', (data: ChatUpdateData) => {
       const changes = data.changes as Record<string, unknown> | undefined;
       if (!changes) return;
       const existing = this.chatInfoMap.get(data.chat_id);
       if (existing) {
         this.chatInfoMap.set(data.chat_id, {
           ...existing,
-          ...(typeof changes.type === "string" ? { type: changes.type as Chat["type"] } : {}),
-          ...(typeof changes.name === "string" ? { name: changes.name } : {}),
-          ...(typeof changes.agent_routing_mode === "string"
-            ? { agentRoutingMode: changes.agent_routing_mode as Chat["agent_routing_mode"] }
+          ...(typeof changes.type === 'string' ? { type: changes.type as Chat['type'] } : {}),
+          ...(typeof changes.name === 'string' ? { name: changes.name } : {}),
+          ...(typeof changes.agent_routing_mode === 'string'
+            ? { agentRoutingMode: changes.agent_routing_mode as Chat['agent_routing_mode'] }
             : {}),
         });
-      } else if (typeof changes.type === "string") {
+      } else if (typeof changes.type === 'string') {
         this.chatInfoMap.set(data.chat_id, {
-          type: changes.type as Chat["type"],
-          name: typeof changes.name === "string" ? changes.name : null,
-          agentRoutingMode: (typeof changes.agent_routing_mode === "string"
+          type: changes.type as Chat['type'],
+          name: typeof changes.name === 'string' ? changes.name : null,
+          agentRoutingMode: (typeof changes.agent_routing_mode === 'string'
             ? changes.agent_routing_mode
-            : "passive") as Chat["agent_routing_mode"],
+            : 'passive') as Chat['agent_routing_mode'],
         });
       }
     });
 
-    ws.on("message.new", async (data: MessageNewData) => {
+    ws.on('message.new', async (data: MessageNewData) => {
       await this.handleMessage(data);
     });
 
-    ws.on("agent_config.update", async (data: AgentConfigUpdateData) => {
+    ws.on('agent_config.update', async (data: AgentConfigUpdateData) => {
       this.opts.log?.info(`config update notification (version=${data.version})`);
       try {
         await this.opts.onConfigUpdate?.(data);
@@ -260,13 +358,12 @@ export class ParallAgentGateway {
       }
     });
 
-    ws.on("agent.new_session", async (data: AgentNewSessionData) => {
-      const prevId = data.previous_session_id ?? "";
+    ws.on('agent.new_session', async (data: AgentNewSessionData) => {
+      const prevId = data.previous_session_id ?? '';
       this.opts.log?.info(`new session signal received (previous=${prevId})`);
       this.sessionBindings.clear();
       if (prevId) {
-        this.pendingRestartNotification =
-          `[Harness Notification] This is a fresh session. Your previous session (${prevId}) was ended by the user and you have been restarted.`;
+        this.pendingRestartNotification = `[Harness Notification] This is a fresh session. Your previous session (${prevId}) was ended by the user and you have been restarted.`;
       }
       try {
         await this.opts.onNewSession?.(prevId);
@@ -275,47 +372,80 @@ export class ParallAgentGateway {
       }
     });
 
-    ws.on("recovery.overflow", () => {
+    ws.on('recovery.overflow', () => {
       this.opts.log?.warn(`recovery.overflow — triggering full catch-up`);
       this.catchUpFromDispatch().catch((err) =>
-        this.opts.log?.warn(`overflow catch-up failed: ${String(err)}`));
+        this.opts.log?.warn(`overflow catch-up failed: ${String(err)}`),
+      );
     });
 
-    ws.on("task.assigned", async (data: TaskAssignedData) => {
+    ws.on('task.assigned', async (data: TaskAssignedData) => {
       if (data.assignee_id !== this.opts.agentUserId) return;
-      if (data.status !== "todo" && data.status !== "in_progress") return;
+      if (data.status !== 'todo' && data.status !== 'in_progress') return;
       try {
         const dispatched = await this.handleTaskAssignment(data, data.id);
         if (dispatched) {
-          this.opts.client.ackDispatch(this.opts.config.org_id, { source_type: "task_activity", source_id: data.id }).catch(() => {});
+          this.opts.client
+            .ackDispatch(this.opts.config.org_id, {
+              source_type: 'task_activity',
+              source_id: data.id,
+            })
+            .catch(() => {});
         }
       } catch (err) {
         this.opts.log?.error(`task dispatch failed for ${data.id}: ${String(err)}`);
       }
     });
 
-    ws.on("dispatch.new", async (data: DispatchNewData) => {
-      if (data.event_type === "task_comment") {
+    ws.on('dispatch.new', async (data: DispatchNewData) => {
+      if (data.event_type === 'task_comment') {
         if (!data.source_id || !data.task_id) return;
         try {
-          const dispatched = await this.handleTaskComment(data.source_id, data.task_id, data.actor_id, data.delivery_reason);
+          const dispatched = await this.handleTaskComment(
+            data.source_id,
+            data.task_id,
+            data.actor_id,
+            data.delivery_reason,
+          );
           if (dispatched) {
             this.opts.client.ackDispatchByID(this.opts.config.org_id, data.id).catch(() => {});
           }
         } catch (err) {
-          this.opts.log?.error(`task comment dispatch failed for ${data.source_id}: ${String(err)}`);
+          this.opts.log?.error(
+            `task comment dispatch failed for ${data.source_id}: ${String(err)}`,
+          );
         }
-      } else if (data.event_type === "task_update") {
+      } else if (data.event_type === 'wiki_comment') {
+        if (!data.source_id) return;
+        try {
+          const dispatched = await this.handleWikiComment(
+            data.source_id,
+            data.actor_id,
+            data.delivery_reason,
+          );
+          if (dispatched) {
+            this.opts.client.ackDispatchByID(this.opts.config.org_id, data.id).catch(() => {});
+          }
+        } catch (err) {
+          this.opts.log?.error(
+            `wiki comment dispatch failed for ${data.source_id}: ${String(err)}`,
+          );
+        }
+      } else if (data.event_type === 'task_update') {
         if (!data.task_id) return;
         try {
-          const dispatched = await this.handleTaskDispatch(data.task_id, data.source_id ?? data.task_id, { allowCreator: true });
+          const dispatched = await this.handleTaskDispatch(
+            data.task_id,
+            data.source_id ?? data.task_id,
+            { allowCreator: true },
+          );
           if (dispatched) {
             this.opts.client.ackDispatchByID(this.opts.config.org_id, data.id).catch(() => {});
           }
         } catch (err) {
           this.opts.log?.error(`task update dispatch failed for ${data.task_id}: ${String(err)}`);
         }
-      } else if (data.event_type === "schedule.fire") {
+      } else if (data.event_type === 'schedule.fire') {
         if (!data.source_id) return;
         try {
           const dispatched = await this.fetchAndHandleScheduleFire(data.source_id, data.actor_id);
@@ -323,19 +453,27 @@ export class ParallAgentGateway {
             this.opts.client.ackDispatchByID(this.opts.config.org_id, data.id).catch(() => {});
           }
         } catch (err) {
-          this.opts.log?.error(`schedule fire dispatch failed for ${data.source_id}: ${String(err)}`);
+          this.opts.log?.error(
+            `schedule fire dispatch failed for ${data.source_id}: ${String(err)}`,
+          );
         }
-      } else if (data.event_type === "approval_decided") {
+      } else if (data.event_type === 'approval_decided') {
         if (!data.source_id) return;
         try {
-          const dispatched = await this.fetchAndHandleApprovalDecided(data.source_id, data.actor_id, data.chat_id ?? null);
+          const dispatched = await this.fetchAndHandleApprovalDecided(
+            data.source_id,
+            data.actor_id,
+            data.chat_id ?? null,
+          );
           if (dispatched) {
             this.opts.client.ackDispatchByID(this.opts.config.org_id, data.id).catch(() => {});
           }
         } catch (err) {
-          this.opts.log?.error(`approval decided dispatch failed for ${data.source_id}: ${String(err)}`);
+          this.opts.log?.error(
+            `approval decided dispatch failed for ${data.source_id}: ${String(err)}`,
+          );
         }
-      } else if (data.event_type !== "message" && data.event_type !== "task_assign") {
+      } else if (data.event_type !== 'message' && data.event_type !== 'task_assign') {
         // 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
@@ -343,15 +481,17 @@ export class ParallAgentGateway {
         // (message.new, task.assigned) above and would otherwise spam
         // info-level logs for every inbound chat message / task
         // assignment on a busy agent.
-        this.opts.log?.info(`dispatch.new with unhandled event_type=${String(data.event_type)} (id=${data.id}) — no-op`);
+        this.opts.log?.info(
+          `dispatch.new with unhandled event_type=${String(data.event_type)} (id=${data.id}) — no-op`,
+        );
       }
     });
 
-    this.opts.log?.info(`connecting to ${this.opts.connectionLabel ?? "Parall WS"}...`);
+    this.opts.log?.info(`connecting to ${this.opts.connectionLabel ?? 'Parall WS'}...`);
     await ws.connect();
 
     return new Promise<void>((resolve) => {
-      abortSignal.addEventListener("abort", async () => {
+      abortSignal.addEventListener('abort', async () => {
         await this.shutdown();
         resolve();
       });
@@ -371,65 +511,13 @@ export class ParallAgentGateway {
     return true;
   }
 
-  private startTyping(chatId: string) {
-    const existing = this.activeDispatches.get(chatId);
-    if (existing) {
-      existing.count++;
-      return;
-    }
-
-    if (this.opts.ws.state === "connected") this.opts.ws.sendTyping(chatId, "start");
-    const typingRefresh = setInterval(() => {
-      if (this.opts.ws.state === "connected") this.opts.ws.sendTyping(chatId, "start");
-    }, 2000);
-    this.activeDispatches.set(chatId, { count: 1, typingTimer: typingRefresh });
-  }
-
-  private stopTyping(chatId: string) {
-    const dispatch = this.activeDispatches.get(chatId);
-    if (!dispatch) return;
-    dispatch.count--;
-    if (dispatch.count > 0) return;
-
-    clearInterval(dispatch.typingTimer);
-    this.activeDispatches.delete(chatId);
-    if (this.opts.ws.state === "connected") this.opts.ws.sendTyping(chatId, "stop");
-  }
-
-  private shouldShowTyping(event: ParallEvent): boolean {
-    return event.type === "message" && event.targetId.startsWith("cht_") && !event.noReply;
-  }
-
-  private startInjectedTyping(event: ParallEvent) {
-    if (!this.shouldShowTyping(event)) return;
-    this.startTyping(event.targetId);
-    this.injectedTypingCounts.set(event.targetId, (this.injectedTypingCounts.get(event.targetId) ?? 0) + 1);
-  }
-
-  private takeInjectedTypingCount(chatId: string): number {
-    const count = this.injectedTypingCounts.get(chatId) ?? 0;
-    this.injectedTypingCounts.delete(chatId);
-    return count;
-  }
-
-  private async runDispatchWithTyping(
-    event: ParallEvent,
-    sessionKey: string,
-    bodyForAgent: string,
-    earlierEvents: ParallEvent[] = [],
-    captureText?: string[],
-    opts: { suppressStart?: boolean; injectedTypingCount?: number } = {},
-  ): Promise<boolean> {
-    const showTyping = !opts.suppressStart && (this.shouldShowTyping(event) || earlierEvents.some(e => this.shouldShowTyping(e)));
-    if (showTyping) this.startTyping(event.targetId);
-    try {
-      return await this.runDispatch(event, sessionKey, bodyForAgent, earlierEvents, captureText);
-    } finally {
-      if (showTyping) this.stopTyping(event.targetId);
-      for (let i = 0; i < (opts.injectedTypingCount ?? 0); i++) {
-        this.stopTyping(event.targetId);
-      }
-    }
+  private async emitDispatchReceived(event: ParallEvent): Promise<void> {
+    const sourceType = event.ackSourceType ?? (event.type === 'task' ? 'task_activity' : 'message');
+    const sourceId = event.ackSourceId ?? event.messageId;
+    await this.opts.client.markDispatchReceived(this.opts.config.org_id, {
+      source_type: sourceType,
+      source_id: sourceId,
+    });
   }
 
   private buildDispatchContext(event: ParallEvent, sessionKey: string): DispatchContext {
@@ -443,7 +531,7 @@ export class ParallAgentGateway {
       runtimeType: this.opts.runtimeType,
       runtimeKey: this.opts.runtimeKey,
       sessionId: binding?.agentSessionId,
-      chatId: (event.type === "message" || event.type === "approval") ? event.targetId : undefined,
+      chatId: event.type === 'message' || event.type === 'approval' ? event.targetId : undefined,
       triggerMessageId: event.messageId,
       noReply: event.noReply ?? false,
       contextFilePath: this.opts.contextFilePathForSession?.(sessionKey),
@@ -453,81 +541,127 @@ export class ParallAgentGateway {
     };
   }
 
+  private isSessionNotLiveError(err: unknown): boolean {
+    return (
+      err instanceof ApiError &&
+      err.status === 409 &&
+      (err.code === 'SESSION_NOT_LIVE' || err.code === 'INVALID_TRANSITION')
+    );
+  }
+
   private async createInputStep(sessionId: string, event: ParallEvent) {
     const target = resolveStepTarget(event);
     try {
-      await this.opts.client.createAgentStep(this.opts.config.org_id, this.opts.agentUserId, sessionId, {
-        step_type: "input",
-        target_type: target.target_type,
-        target_id: target.target_id,
-        content: {
-          trigger_type:
-            event.type === "task" ? "task_assign" :
-            event.type === "task_comment" ? "task_comment" :
-            event.type === "schedule" ? "schedule_fire" :
-            event.type === "approval" ? "approval_decided" :
-            "mention",
-          trigger_ref:
-            event.type === "task" ? { task_id: event.targetId } :
-            event.type === "task_comment" ? { comment_id: event.messageId, task_id: event.targetId } :
-            event.type === "schedule" ? { schedule_id: event.targetId, run_id: event.messageId } :
-            event.type === "approval" ? { approval_id: event.messageId } :
-            { message_id: event.messageId },
-          sender_id: event.senderId,
-          sender_name: event.senderName,
-          summary: event.body.substring(0, 200),
-          ...(event.sentAt ? { sent_at: event.sentAt } : {}),
+      await this.opts.client.createAgentStep(
+        this.opts.config.org_id,
+        this.opts.agentUserId,
+        sessionId,
+        {
+          step_type: 'input',
+          target_type: target.target_type,
+          target_id: target.target_id,
+          content: {
+            trigger_type:
+              event.type === 'task'
+                ? 'task_assign'
+                : event.type === 'task_comment'
+                  ? 'task_comment'
+                  : event.type === 'wiki_comment'
+                    ? 'wiki_comment'
+                    : event.type === 'schedule'
+                      ? 'schedule_fire'
+                      : event.type === 'approval'
+                        ? 'approval_decided'
+                        : 'mention',
+            trigger_ref:
+              event.type === 'task'
+                ? { task_id: event.targetId }
+                : event.type === 'task_comment'
+                  ? { comment_id: event.messageId, task_id: event.targetId }
+                  : event.type === 'wiki_comment'
+                    ? { comment_id: event.messageId, target_uri: event.replyTargetUri }
+                    : event.type === 'schedule'
+                      ? { schedule_id: event.targetId, run_id: event.messageId }
+                      : event.type === 'approval'
+                        ? { approval_id: event.messageId }
+                        : { message_id: event.messageId },
+            sender_id: event.senderId,
+            sender_name: event.senderName,
+            summary: event.body.substring(0, 200),
+            ...(event.sentAt ? { sent_at: event.sentAt } : {}),
+          },
         },
-      });
+      );
     } catch (err) {
+      if (this.isSessionNotLiveError(err)) throw err;
       this.opts.log?.warn(`failed to create input step: ${String(err)}`);
     }
   }
 
-  private async createRuntimeStep(sessionId: string, event: ParallEvent, runtimeEvent: RuntimeEvent, stepIdFilePath?: string, contextFilePath?: string) {
-
+  private async createRuntimeStep(
+    sessionId: string,
+    event: ParallEvent,
+    runtimeEvent: RuntimeEvent,
+    stepIdFilePath?: string,
+    contextFilePath?: string,
+  ) {
     const target = resolveStepTarget(event);
     try {
       switch (runtimeEvent.type) {
-        case "thinking":
-          await this.opts.client.createAgentStep(this.opts.config.org_id, this.opts.agentUserId, sessionId, {
-            step_type: "thinking",
-            target_type: target.target_type,
-            target_id: target.target_id,
-            content: { text: runtimeEvent.text },
-            group_key: runtimeEvent.groupKey,
-          });
+        case 'thinking':
+          await this.opts.client.createAgentStep(
+            this.opts.config.org_id,
+            this.opts.agentUserId,
+            sessionId,
+            {
+              step_type: 'thinking',
+              target_type: target.target_type,
+              target_id: target.target_id,
+              content: { text: runtimeEvent.text },
+              group_key: runtimeEvent.groupKey,
+            },
+          );
           break;
 
-        case "text":
-          await this.opts.client.createAgentStep(this.opts.config.org_id, this.opts.agentUserId, sessionId, {
-            step_type: "text",
-            target_type: target.target_type,
-            target_id: target.target_id,
-            content: {
-              text: runtimeEvent.text,
-              suppressed: runtimeEvent.project !== true,
+        case 'text':
+          await this.opts.client.createAgentStep(
+            this.opts.config.org_id,
+            this.opts.agentUserId,
+            sessionId,
+            {
+              step_type: 'text',
+              target_type: target.target_type,
+              target_id: target.target_id,
+              content: {
+                text: runtimeEvent.text,
+                suppressed: runtimeEvent.project !== true,
+              },
+              projection: runtimeEvent.project === true,
+              group_key: runtimeEvent.groupKey,
             },
-            projection: runtimeEvent.project === true,
-            group_key: runtimeEvent.groupKey,
-          });
+          );
           break;
 
-        case "tool_call": {
-          const step = await this.opts.client.createAgentStep(this.opts.config.org_id, this.opts.agentUserId, sessionId, {
-            step_type: "tool_call",
-            target_type: target.target_type,
-            target_id: target.target_id,
-            content: {
-              call_id: runtimeEvent.callId,
-              tool_name: runtimeEvent.toolName,
-              tool_input: runtimeEvent.input,
-              status: "running",
-              started_at: runtimeEvent.startedAt ?? new Date().toISOString(),
+        case 'tool_call': {
+          const step = await this.opts.client.createAgentStep(
+            this.opts.config.org_id,
+            this.opts.agentUserId,
+            sessionId,
+            {
+              step_type: 'tool_call',
+              target_type: target.target_type,
+              target_id: target.target_id,
+              content: {
+                call_id: runtimeEvent.callId,
+                tool_name: runtimeEvent.toolName,
+                tool_input: runtimeEvent.input,
+                status: 'running',
+                started_at: runtimeEvent.startedAt ?? new Date().toISOString(),
+              },
+              group_key: runtimeEvent.groupKey,
+              runtime_key: runtimeEvent.callId,
             },
-            group_key: runtimeEvent.groupKey,
-            runtime_key: runtimeEvent.callId,
-          });
+          );
           if (contextFilePath) {
             this.updateContextFileStepId(contextFilePath, step.id);
           } else if (stepIdFilePath) {
@@ -536,21 +670,26 @@ export class ParallAgentGateway {
           break;
         }
 
-        case "tool_result":
-          await this.opts.client.createAgentStep(this.opts.config.org_id, this.opts.agentUserId, sessionId, {
-            step_type: "tool_result",
-            target_type: target.target_type,
-            target_id: target.target_id,
-            content: {
-              call_id: runtimeEvent.callId,
-              tool_name: runtimeEvent.toolName,
-              status: runtimeEvent.error ? "error" : "success",
-              output: runtimeEvent.output,
-              duration_ms: runtimeEvent.durationMs ?? 0,
-              collapsible: true,
+        case 'tool_result':
+          await this.opts.client.createAgentStep(
+            this.opts.config.org_id,
+            this.opts.agentUserId,
+            sessionId,
+            {
+              step_type: 'tool_result',
+              target_type: target.target_type,
+              target_id: target.target_id,
+              content: {
+                call_id: runtimeEvent.callId,
+                tool_name: runtimeEvent.toolName,
+                status: runtimeEvent.error ? 'error' : 'success',
+                output: runtimeEvent.output,
+                duration_ms: runtimeEvent.durationMs ?? 0,
+                collapsible: true,
+              },
+              group_key: runtimeEvent.groupKey,
             },
-            group_key: runtimeEvent.groupKey,
-          });
+          );
           if (contextFilePath) {
             this.updateContextFileStepId(contextFilePath, null);
           } else if (stepIdFilePath) {
@@ -558,17 +697,23 @@ export class ParallAgentGateway {
           }
           break;
 
-        case "error":
-          await this.opts.client.createAgentStep(this.opts.config.org_id, this.opts.agentUserId, sessionId, {
-            step_type: "text",
-            target_type: target.target_type,
-            target_id: target.target_id,
-            content: { text: runtimeEvent.message, suppressed: false },
-            projection: false,
-          });
+        case 'error':
+          await this.opts.client.createAgentStep(
+            this.opts.config.org_id,
+            this.opts.agentUserId,
+            sessionId,
+            {
+              step_type: 'text',
+              target_type: target.target_type,
+              target_id: target.target_id,
+              content: { text: runtimeEvent.message, suppressed: false },
+              projection: false,
+            },
+          );
           break;
       }
     } catch (err) {
+      if (this.isSessionNotLiveError(err)) throw err;
       this.opts.log?.warn(`failed to create ${runtimeEvent.type} step: ${String(err)}`);
     }
   }
@@ -576,7 +721,7 @@ export class ParallAgentGateway {
   private writeContextFile(filePath: string, ctx: Record<string, unknown>) {
     try {
       fs.mkdirSync(path.dirname(filePath), { recursive: true });
-      fs.writeFileSync(filePath, JSON.stringify(ctx), "utf8");
+      fs.writeFileSync(filePath, JSON.stringify(ctx), 'utf8');
     } catch (err) {
       this.opts.log?.warn(`failed to write context file ${filePath}: ${String(err)}`);
     }
@@ -584,10 +729,10 @@ export class ParallAgentGateway {
 
   private updateContextFileStepId(filePath: string, stepId: string | null) {
     try {
-      const raw = fs.readFileSync(filePath, "utf8");
+      const raw = fs.readFileSync(filePath, 'utf8');
       const ctx = JSON.parse(raw);
       ctx.step_id = stepId;
-      fs.writeFileSync(filePath, JSON.stringify(ctx), "utf8");
+      fs.writeFileSync(filePath, JSON.stringify(ctx), 'utf8');
     } catch (err) {
       this.opts.log?.warn(`failed to update context file step_id ${filePath}: ${String(err)}`);
     }
@@ -595,10 +740,10 @@ export class ParallAgentGateway {
 
   private updateContextFileSessionId(filePath: string, sessionId: string) {
     try {
-      const raw = fs.readFileSync(filePath, "utf8");
+      const raw = fs.readFileSync(filePath, 'utf8');
       const ctx = JSON.parse(raw);
       ctx.session_id = sessionId;
-      fs.writeFileSync(filePath, JSON.stringify(ctx), "utf8");
+      fs.writeFileSync(filePath, JSON.stringify(ctx), 'utf8');
     } catch (err) {
       this.opts.log?.warn(`failed to update context file session_id ${filePath}: ${String(err)}`);
     }
@@ -608,7 +753,7 @@ export class ParallAgentGateway {
   private writeStepIdFile(filePath: string, stepId: string) {
     try {
       fs.mkdirSync(path.dirname(filePath), { recursive: true });
-      fs.writeFileSync(filePath, stepId, "utf8");
+      fs.writeFileSync(filePath, stepId, 'utf8');
     } catch (err) {
       this.opts.log?.warn(`failed to write step id file ${filePath}: ${String(err)}`);
     }
@@ -617,7 +762,7 @@ export class ParallAgentGateway {
   /** @deprecated Use writeContextFile / updateContextFileStepId. */
   private clearStepIdFile(filePath: string) {
     try {
-      fs.writeFileSync(filePath, "", "utf8");
+      fs.writeFileSync(filePath, '', 'utf8');
     } catch {
       // Best-effort cleanup.
     }
@@ -631,7 +776,7 @@ export class ParallAgentGateway {
 
   private async bindRuntimeSession(
     sessionKey: string,
-    runtimeEvent: Extract<RuntimeEvent, { type: "runtime_session" }>,
+    runtimeEvent: Extract<RuntimeEvent, { type: 'runtime_session' }>,
     contextFilePath?: string,
   ): Promise<AgentSessionBinding> {
     const runtimeLaneKey = runtimeEvent.runtimeLaneKey || sessionKey;
@@ -644,21 +789,42 @@ export class ParallAgentGateway {
       return existing;
     }
 
-    const parentSessionId = sessionKey === this.opts.runtimeKey
-      ? undefined
-      : this.sessionBindings.get(this.opts.runtimeKey)?.agentSessionId;
+    const parentSessionId =
+      sessionKey === this.opts.runtimeKey
+        ? undefined
+        : this.sessionBindings.get(this.opts.runtimeKey)?.agentSessionId;
     const runtimeRef = {
       ...(this.opts.runtimeRef ?? {}),
       ...(runtimeEvent.runtimeRef ?? {}),
     };
-    const session: AgentSessionDB = await this.opts.client.createAgentSession(this.opts.config.org_id, this.opts.agentUserId, {
-      runtime_type: this.opts.runtimeType,
-      runtime_key: runtimeLaneKey,
-      runtime_lane_key: runtimeLaneKey,
-      runtime_session_id: runtimeEvent.runtimeSessionId,
-      parent_session_id: parentSessionId,
-      runtime_ref: Object.keys(runtimeRef).length > 0 ? runtimeRef : undefined,
-    });
+    const session: AgentSessionDB = await this.opts.client.createAgentSession(
+      this.opts.config.org_id,
+      this.opts.agentUserId,
+      {
+        runtime_type: this.opts.runtimeType,
+        runtime_key: runtimeLaneKey,
+        runtime_lane_key: runtimeLaneKey,
+        runtime_session_id: runtimeEvent.runtimeSessionId,
+        parent_session_id: parentSessionId,
+        runtime_ref: Object.keys(runtimeRef).length > 0 ? runtimeRef : undefined,
+      },
+    );
+    if (!LIVE_SESSION_STATUSES.has(session.status)) {
+      this.opts.log?.warn?.(
+        `createAgentSession returned terminal session ${session.id} (${session.status}), resetting runtime for ${sessionKey}`,
+      );
+      this.sessionBindings.delete(sessionKey);
+      try {
+        await this.opts.onSessionStale?.(sessionKey);
+      } catch (e) {
+        this.opts.log?.warn?.(`onSessionStale failed: ${e}`);
+      }
+      this.opts.log?.info?.(
+        `stale session self-heal complete for ${sessionKey} — next dispatch will create a fresh session`,
+      );
+      throw new Error(`Agent session ${session.id} is terminal (${session.status})`);
+    }
+
     const binding: AgentSessionBinding = {
       sessionKey,
       agentSessionId: session.id,
@@ -699,125 +865,274 @@ export class ParallAgentGateway {
     }
 
     if (this.pendingRestartNotification) {
-      bodyForAgent = this.pendingRestartNotification + "\n\n---\n\n" + bodyForAgent;
+      bodyForAgent = this.pendingRestartNotification + '\n\n---\n\n' + bodyForAgent;
       this.pendingRestartNotification = null;
     }
 
-    setSessionChatId(sessionKey, event.targetId);
-    setSessionMessageId(sessionKey, event.messageId);
-    setDispatchMessageId(sessionKey, event.messageId);
-    setDispatchNoReply(sessionKey, event.noReply ?? false);
+    resetDispatchMetrics(sessionKey);
+    return runWithSessionKey(sessionKey, async () => {
+      let dispatchSpan: ReturnType<typeof startDispatchSpan> = null;
 
-    const dispatchContext = this.buildDispatchContext(event, sessionKey);
-    const contextFilePath = dispatchContext.contextFilePath;
-    const stepIdFilePath = dispatchContext.stepIdFilePath;
+      setSessionChatId(sessionKey, event.targetId);
+      setSessionMessageId(sessionKey, event.messageId);
+      setDispatchMessageId(sessionKey, event.messageId);
+      setDispatchNoReply(sessionKey, event.noReply ?? false);
 
-    if (contextFilePath) {
-      this.writeContextFile(contextFilePath, {
-        session_id: dispatchContext.sessionId ?? null,
-        chat_id: dispatchContext.chatId ?? null,
-        trigger_message_id: dispatchContext.triggerMessageId ?? null,
-        no_reply: dispatchContext.noReply,
-        step_id: null,
-      });
-    }
+      const dispatchContext = this.buildDispatchContext(event, sessionKey);
+      const contextFilePath = dispatchContext.contextFilePath;
+      const stepIdFilePath = dispatchContext.stepIdFilePath;
 
-    // sync: no await between the shuttingDown check above and this increment
-    // — JS event loop is single-threaded, so shutdown() cannot interleave
-    // here and miss our in-flight count.
-    this.inFlightDispatches++;
-    let binding = this.sessionBindings.get(sessionKey);
-    let inputStepsCreated = false;
-    let triggerMessageSet = false;
-    try {
-      for await (const runtimeEvent of this.opts.dispatchAdapter.dispatch({
-        event,
-        earlierEvents,
-        bodyForAgent,
-        sessionKey,
-        context: dispatchContext,
-      })) {
-        if (runtimeEvent.type === "runtime_session") {
-          binding = await this.bindRuntimeSession(sessionKey, runtimeEvent, contextFilePath);
+      if (contextFilePath) {
+        this.writeContextFile(contextFilePath, {
+          session_id: dispatchContext.sessionId ?? null,
+          chat_id: dispatchContext.chatId ?? null,
+          trigger_message_id: dispatchContext.triggerMessageId ?? null,
+          no_reply: dispatchContext.noReply,
+          step_id: null,
+        });
+      }
+
+      // sync: no await between the shuttingDown check above and this increment
+      // — JS event loop is single-threaded, so shutdown() cannot interleave
+      // here and miss our in-flight count.
+      this.inFlightDispatches++;
+
+      const deadlineTimer =
+        this.DISPATCH_DEADLINE_MS > 0
+          ? setTimeout(() => {
+              this.opts.log?.warn(
+                `dispatch deadline exceeded (${this.DISPATCH_DEADLINE_MS}ms) for ${event.messageId} on ${sessionKey}; aborting`,
+              );
+              try {
+                this.opts.dispatchAdapter.abortDispatch?.(sessionKey);
+              } catch (err) {
+                this.opts.log?.warn(`abortDispatch threw for ${sessionKey}: ${String(err)}`);
+              }
+            }, this.DISPATCH_DEADLINE_MS)
+          : null;
+
+      let binding = this.sessionBindings.get(sessionKey);
+      let inputStepsCreated = false;
+      let triggerMessageSet = false;
+      let dispatchError: unknown;
+      const pendingSendCallIds = new Set<string>();
+      try {
+        dispatchSpan = startDispatchSpan(event, this.opts.runtimeType, sessionKey);
+        for await (const runtimeEvent of this.opts.dispatchAdapter.dispatch({
+          event,
+          earlierEvents,
+          bodyForAgent,
+          sessionKey,
+          context: dispatchContext,
+        })) {
+          if (runtimeEvent.type === 'runtime_session') {
+            binding = await this.bindRuntimeSession(sessionKey, runtimeEvent, contextFilePath);
+            if (!inputStepsCreated) {
+              // Persist input steps for "earlier events" (batched events that arrived
+              // while a dispatch was in flight) inside the in-flight window so a
+              // shutdown short-circuit BEFORE this point cannot leave orphan input
+              // steps that the replacement pod would duplicate on replay.
+              if (earlierEvents.length > 0) {
+                await this.createInputStepsForEarlierEvents(binding.agentSessionId, earlierEvents);
+              }
+              await this.createInputStep(binding.agentSessionId, event);
+              inputStepsCreated = true;
+            }
+            continue;
+          }
+
+          if (!binding) {
+            const detail = runtimeEvent.type === 'error' ? `: ${runtimeEvent.message}` : '';
+            throw new Error(`runtime emitted ${runtimeEvent.type} before runtime_session${detail}`);
+          }
+          if (!triggerMessageSet) {
+            triggerMessageSet = true;
+            this.opts.client
+              .updateAgentSession(
+                this.opts.config.org_id,
+                this.opts.agentUserId,
+                binding.agentSessionId,
+                { status: 'active', trigger_message_id: event.messageId },
+              )
+              .catch((err) => this.opts.log?.warn?.(`failed to set session active: ${err}`));
+          }
           if (!inputStepsCreated) {
-            // Persist input steps for "earlier events" (batched events that arrived
-            // while a dispatch was in flight) inside the in-flight window so a
-            // shutdown short-circuit BEFORE this point cannot leave orphan input
-            // steps that the replacement pod would duplicate on replay.
             if (earlierEvents.length > 0) {
               await this.createInputStepsForEarlierEvents(binding.agentSessionId, earlierEvents);
             }
             await this.createInputStep(binding.agentSessionId, event);
             inputStepsCreated = true;
           }
-          continue;
+          if (captureText && runtimeEvent.type === 'text' && runtimeEvent.text) {
+            captureText.push(runtimeEvent.text);
+          }
+          if (runtimeEvent.type === 'text' && runtimeEvent.text.length > 0) {
+            recordDeliverText(sessionKey, runtimeEvent.text.length);
+          } else if (runtimeEvent.type === 'tool_call') {
+            recordToolCall(sessionKey);
+            const cmd = extractShellCommand(runtimeEvent.input);
+            if (isParallSendCommand(cmd)) {
+              pendingSendCallIds.add(runtimeEvent.callId);
+            } else if (isParallNoReplyCommand(cmd)) {
+              recordNoReply(sessionKey);
+            }
+          } else if (
+            runtimeEvent.type === 'tool_result' &&
+            pendingSendCallIds.delete(runtimeEvent.callId)
+          ) {
+            recordMessageSend(sessionKey, !runtimeEvent.error);
+          }
+          await this.createRuntimeStep(
+            binding.agentSessionId,
+            event,
+            runtimeEvent,
+            stepIdFilePath,
+            contextFilePath,
+          );
         }
-
         if (!binding) {
-          const detail = runtimeEvent.type === "error" ? `: ${runtimeEvent.message}` : "";
-          throw new Error(`runtime emitted ${runtimeEvent.type} before runtime_session${detail}`);
+          binding = this.sessionBindings.get(sessionKey);
         }
-        if (!triggerMessageSet) {
-          triggerMessageSet = true;
-          this.opts.client.updateAgentSession(
-            this.opts.config.org_id, this.opts.agentUserId, binding.agentSessionId,
-            { status: "active", trigger_message_id: event.messageId },
-          ).catch((err) => this.opts.log?.warn?.(`failed to set session active: ${err}`));
+        if (!binding) {
+          throw new Error('runtime completed without runtime_session');
         }
         if (!inputStepsCreated) {
           if (earlierEvents.length > 0) {
             await this.createInputStepsForEarlierEvents(binding.agentSessionId, earlierEvents);
           }
           await this.createInputStep(binding.agentSessionId, event);
-          inputStepsCreated = true;
         }
-        if (captureText && runtimeEvent.type === "text" && runtimeEvent.text) {
-          captureText.push(runtimeEvent.text);
+      } catch (err) {
+        dispatchError = err;
+        let staleDetected = this.isSessionNotLiveError(err);
+        if (!staleDetected && binding) {
+          try {
+            await this.createRuntimeStep(
+              binding.agentSessionId,
+              event,
+              {
+                type: 'error',
+                message: `Dispatch failed: ${String(err)}`,
+              },
+              stepIdFilePath,
+              contextFilePath,
+            );
+          } catch (stepErr) {
+            if (this.isSessionNotLiveError(stepErr)) staleDetected = true;
+          }
         }
-        await this.createRuntimeStep(binding.agentSessionId, event, runtimeEvent, stepIdFilePath, contextFilePath);
-      }
-      if (!binding) {
-        binding = this.sessionBindings.get(sessionKey);
-      }
-      if (!binding) {
-        throw new Error("runtime completed without runtime_session");
-      }
-      if (!inputStepsCreated) {
-        if (earlierEvents.length > 0) {
-          await this.createInputStepsForEarlierEvents(binding.agentSessionId, earlierEvents);
+        if (staleDetected && binding) {
+          this.opts.log?.warn?.(
+            `session ${binding.agentSessionId} is stale (mid-dispatch), triggering recovery for ${sessionKey}`,
+          );
+          this.sessionBindings.delete(sessionKey);
+          if (sessionKey === this.opts.runtimeKey) {
+            this.activeSessionId = undefined;
+          }
+          try {
+            await this.opts.onSessionStale?.(sessionKey);
+          } catch (e) {
+            this.opts.log?.warn?.(`onSessionStale failed: ${e}`);
+          }
+          this.opts.log?.info?.(
+            `stale session self-heal complete for ${sessionKey} — next dispatch will create a fresh session`,
+          );
+          binding = undefined;
+        }
+        throw err;
+      } finally {
+        if (deadlineTimer) clearTimeout(deadlineTimer);
+        const metricsSnapshot = getDispatchMetrics(sessionKey);
+        const durationMs = metricsSnapshot ? Date.now() - metricsSnapshot.started_at : 0;
+
+        endDispatchSpan(dispatchSpan, metricsSnapshot, dispatchError);
+        recordDispatchMetric(event, this.opts.runtimeType, durationMs);
+
+        if (
+          metricsSnapshot &&
+          !dispatchError &&
+          event.type === 'message' &&
+          event.targetId?.startsWith('cht_') &&
+          !event.noReply &&
+          metricsSnapshot.deliver_text_chunks > 0 &&
+          metricsSnapshot.message_send_successes === 0 &&
+          !metricsSnapshot.no_reply_called
+        ) {
+          recordMissingReply(this.opts.runtimeType);
+        }
+
+        clearDispatchMetrics(sessionKey);
+        if (triggerMessageSet && binding) {
+          this.opts.client
+            .updateAgentSession(
+              this.opts.config.org_id,
+              this.opts.agentUserId,
+              binding.agentSessionId,
+              { status: 'idle' },
+            )
+            .catch((err) => this.opts.log?.warn?.(`failed to set session idle: ${err}`));
+        }
+        clearSessionMessageId(sessionKey);
+        clearDispatchMessageId(sessionKey);
+        clearDispatchNoReply(sessionKey);
+        if (contextFilePath) {
+          this.updateContextFileStepId(contextFilePath, null);
+        } else if (stepIdFilePath) {
+          this.clearStepIdFile(stepIdFilePath);
+        }
+        this.inFlightDispatches--;
+        if (this.inFlightDispatches === 0 && this.drainResolvers.length > 0) {
+          const resolvers = this.drainResolvers.splice(0);
+          for (const resolve of resolvers) resolve();
         }
-        await this.createInputStep(binding.agentSessionId, event);
-      }
-    } catch (err) {
-      if (binding) {
-        await this.createRuntimeStep(binding.agentSessionId, event, {
-          type: "error",
-          message: `Dispatch failed: ${String(err)}`,
-        }, stepIdFilePath, contextFilePath);
-      }
-      throw err;
-    } finally {
-      if (triggerMessageSet && binding) {
-        this.opts.client.updateAgentSession(
-          this.opts.config.org_id, this.opts.agentUserId, binding.agentSessionId,
-          { status: "idle" },
-        ).catch((err) => this.opts.log?.warn?.(`failed to set session idle: ${err}`));
-      }
-      clearSessionMessageId(sessionKey);
-      clearDispatchMessageId(sessionKey);
-      clearDispatchNoReply(sessionKey);
-      if (contextFilePath) {
-        this.updateContextFileStepId(contextFilePath, null);
-      } else if (stepIdFilePath) {
-        this.clearStepIdFile(stepIdFilePath);
-      }
-      this.inFlightDispatches--;
-      if (this.inFlightDispatches === 0 && this.drainResolvers.length > 0) {
-        const resolvers = this.drainResolvers.splice(0);
-        for (const resolve of resolvers) resolve();
       }
+      return true;
+    }); // runWithSessionKey
+  }
+
+  private abortFork(targetId: string, reason: string) {
+    const forkState = this.forkStates.get(targetId);
+    if (!forkState) return;
+
+    this.opts.log?.warn(`aborting fork for ${targetId}: ${reason}`);
+    forkState.deadlineExceeded = true;
+
+    if (forkState.deadlineTimer) {
+      clearTimeout(forkState.deadlineTimer);
+      forkState.deadlineTimer = null;
+    }
+
+    this.dispatchState.activeForks.delete(targetId);
+    this.forkStates.delete(targetId);
+
+    for (const item of forkState.queue.splice(0)) {
+      item.resolve(false);
+    }
+
+    if (this.opts.dispatchAdapter.cleanupFork) {
+      const forkBinding = this.sessionBindings.get(forkState.fork.sessionKey);
+      const cleanupOpts: CleanupForkOpts = {
+        fork: forkState.fork,
+        context: {
+          accountId: this.opts.accountId,
+          apiUrl: this.opts.config.parall_url,
+          apiKey: this.opts.config.api_key,
+          orgId: this.opts.config.org_id,
+          agentUserId: this.opts.agentUserId,
+          runtimeType: this.opts.runtimeType,
+          runtimeKey: this.opts.runtimeKey,
+          sessionId: forkBinding?.agentSessionId,
+          noReply: false,
+          client: this.opts.client,
+          log: this.opts.log,
+        },
+      };
+      void Promise.resolve()
+        .then(() => this.opts.dispatchAdapter.cleanupFork?.(cleanupOpts))
+        .catch((err) => {
+          this.opts.log?.warn(`abortFork cleanupFork error for ${targetId}: ${String(err)}`);
+        });
     }
-    return true;
   }
 
   private async runForkDrainLoop(fork: ActiveForkState) {
@@ -830,7 +1145,7 @@ export class ParallAgentGateway {
         // shuttingDown gate and inFlightDispatches counter, so a shutdown
         // landing mid-batch cannot leave orphan steps that replay would
         // duplicate.
-        if (this.shuttingDown) {
+        if (this.shuttingDown || fork.deadlineExceeded) {
           for (const item of fork.queue.splice(0)) item.resolve(false);
           break;
         }
@@ -840,7 +1155,13 @@ export class ParallAgentGateway {
         const earlier = events.slice(0, -1);
         try {
           const batchText: string[] = [];
-          const dispatched = await this.runDispatchWithTyping(last, fork.fork.sessionKey, buildForkScopePrefix(last) + buildEventBody(last), earlier, batchText);
+          const dispatched = await this.runDispatch(
+            last,
+            fork.fork.sessionKey,
+            buildForkScopePrefix(last) + buildEventBody(last),
+            earlier,
+            batchText,
+          );
           if (!dispatched) {
             // Shutdown short-circuit — resolve un-acked so the server requeues
             // for the replacement pod and stop draining further items.
@@ -850,6 +1171,10 @@ export class ParallAgentGateway {
             break;
           }
           if (batchText.length > 0) lastCapturedText = batchText;
+          if (fork.deadlineExceeded) {
+            for (const item of items) item.resolve(false);
+            break;
+          }
           fork.processedEvents.push(...events);
           for (const item of items) {
             item.resolve(true);
@@ -867,9 +1192,13 @@ export class ParallAgentGateway {
         remaining.resolve(false);
       }
     } finally {
+      if (fork.deadlineTimer) {
+        clearTimeout(fork.deadlineTimer);
+        fork.deadlineTimer = null;
+      }
       if (fork.processedEvents.length > 0) {
         const first = fork.processedEvents[0];
-        const agentSummary = lastCapturedText.join("").trim() || undefined;
+        const agentSummary = lastCapturedText.join('').trim() || undefined;
         let historyPath: string | undefined;
         try {
           historyPath = this.opts.dispatchAdapter.getSessionHistoryPath?.(fork.fork.sessionKey);
@@ -881,9 +1210,10 @@ export class ParallAgentGateway {
           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}`,
+            summary:
+              fork.processedEvents.length === 1
+                ? `${first.type} from ${first.senderName} in ${first.targetName ?? fork.targetId}`
+                : `${fork.processedEvents.length} events in ${first.targetName ?? fork.targetId}`,
           },
           eventBodies: fork.processedEvents.map((e) => buildEventBodyForForkResult(e)),
           actions: [],
@@ -891,8 +1221,12 @@ export class ParallAgentGateway {
           historyPath,
         });
       }
-      this.forkStates.delete(fork.targetId);
-      this.dispatchState.activeForks.delete(fork.targetId);
+      if (this.forkStates.get(fork.targetId) === fork) {
+        this.forkStates.delete(fork.targetId);
+      }
+      if (this.dispatchState.activeForks.get(fork.targetId) === fork.fork.sessionKey) {
+        this.dispatchState.activeForks.delete(fork.targetId);
+      }
       const forkBinding = this.sessionBindings.get(fork.fork.sessionKey);
       if (this.opts.dispatchAdapter.cleanupFork) {
         const cleanupOpts: CleanupForkOpts = {
@@ -911,13 +1245,21 @@ export class ParallAgentGateway {
             log: this.opts.log,
           },
         };
-        await this.opts.dispatchAdapter.cleanupFork(cleanupOpts);
+        try {
+          await this.opts.dispatchAdapter.cleanupFork(cleanupOpts);
+        } catch (err) {
+          this.opts.log?.warn(`fork cleanupFork error for ${fork.targetId}: ${String(err)}`);
+        }
       }
       if (forkBinding) {
-        this.opts.client.updateAgentSession(
-          this.opts.config.org_id, this.opts.agentUserId, forkBinding.agentSessionId,
-          { status: "closed" },
-        ).catch(() => {});
+        this.opts.client
+          .updateAgentSession(
+            this.opts.config.org_id,
+            this.opts.agentUserId,
+            forkBinding.agentSessionId,
+            { status: 'closed' },
+          )
+          .catch(() => {});
         this.sessionBindings.delete(fork.fork.sessionKey);
       }
     }
@@ -947,20 +1289,31 @@ export class ParallAgentGateway {
 
         const event = events[events.length - 1];
         const earlier = events.slice(0, -1);
-        const hasPendingInjections = this.opts.dispatchAdapter.hasPendingInjections?.(this.opts.runtimeKey) ?? false;
-        const injectedTypingCount = hasPendingInjections ? this.takeInjectedTypingCount(event.targetId) : 0;
-        const pendingFork = hasPendingInjections ? [] : this.dispatchState.pendingForkResults.splice(0);
+        const hasPendingInjections =
+          this.opts.dispatchAdapter.hasPendingInjections?.(this.opts.runtimeKey) ?? false;
+        const pendingFork = hasPendingInjections
+          ? []
+          : this.dispatchState.pendingForkResults.splice(0);
         const forkPrefix = buildForkResultPrefix(pendingFork);
         this.dispatchState.mainCurrentTargetId = event.targetId;
-        this.dispatchState.mainPreDispatchBranchPoint =
-          this.opts.dispatchAdapter.getBranchPoint?.(this.opts.runtimeKey);
-        const dispatched = await this.runDispatchWithTyping(
+        this.dispatchState.mainPreDispatchBranchPoint = this.opts.dispatchAdapter.getBranchPoint?.(
+          this.opts.runtimeKey,
+        );
+        try {
+          await this.emitDispatchReceived(event);
+        } catch (err) {
+          this.opts.log?.warn?.(
+            `mark-received failed for buffered dispatch, leaving unacked for retry: ${String(err)}`,
+          );
+          this.dispatchState.mainBuffer.unshift(...events);
+          this.dispatchState.pendingForkResults.unshift(...pendingFork);
+          break;
+        }
+        const dispatched = await this.runDispatch(
           event,
           this.opts.runtimeKey,
           forkPrefix + buildEventBody(event),
           earlier,
-          undefined,
-          { suppressStart: injectedTypingCount > 0, injectedTypingCount },
         );
         if (!dispatched) {
           // Shutdown: skip the ack so the server redelivers these buffered
@@ -971,12 +1324,16 @@ export class ParallAgentGateway {
           break;
         }
         for (const bufferedEvent of events) {
-          const sourceType = bufferedEvent.ackSourceType ?? (bufferedEvent.type === "task" ? "task_activity" : "message");
+          const sourceType =
+            bufferedEvent.ackSourceType ??
+            (bufferedEvent.type === 'task' ? 'task_activity' : 'message');
           const sourceId = bufferedEvent.ackSourceId ?? bufferedEvent.messageId;
-          this.opts.client.ackDispatch(this.opts.config.org_id, {
-            source_type: sourceType,
-            source_id: sourceId,
-          }).catch(() => {});
+          this.opts.client
+            .ackDispatch(this.opts.config.org_id, {
+              source_type: sourceType,
+              source_id: sourceId,
+            })
+            .catch(() => {});
         }
       }
     } finally {
@@ -984,6 +1341,18 @@ export class ParallAgentGateway {
       this.dispatchState.mainDispatching = false;
       this.dispatchState.mainCurrentTargetId = undefined;
       this.dispatchState.mainPreDispatchBranchPoint = undefined;
+      if (!this.shuttingDown && this.dispatchState.mainBuffer.length > 0) {
+        setTimeout(() => {
+          if (
+            !this.draining &&
+            !this.dispatchState.mainDispatching &&
+            this.dispatchState.mainBuffer.length > 0
+          ) {
+            this.dispatchState.mainDispatching = true;
+            void this.drainMainBuffer();
+          }
+        }, 5000);
+      }
     }
   }
 
@@ -991,7 +1360,7 @@ export class ParallAgentGateway {
     const disposition = routeTrigger(event, this.dispatchState);
 
     switch (disposition.action) {
-      case "main": {
+      case 'main': {
         const pendingFork = this.dispatchState.pendingForkResults.splice(0);
         const forkPrefix = buildForkResultPrefix(pendingFork);
         this.dispatchState.mainDispatching = true;
@@ -999,11 +1368,26 @@ export class ParallAgentGateway {
         // Snapshot the on-disk branch point BEFORE runDispatch starts writing
         // to the session file. Fork sessions created while main is in-flight
         // use this to branch from the clean pre-dispatch state.
-        this.dispatchState.mainPreDispatchBranchPoint =
-          this.opts.dispatchAdapter.getBranchPoint?.(this.opts.runtimeKey);
+        this.dispatchState.mainPreDispatchBranchPoint = this.opts.dispatchAdapter.getBranchPoint?.(
+          this.opts.runtimeKey,
+        );
+        try {
+          await this.emitDispatchReceived(event);
+        } catch (err) {
+          this.opts.log?.warn?.(`mark-received failed, leaving unacked for retry: ${String(err)}`);
+          this.dispatchState.mainDispatching = false;
+          this.dispatchState.mainCurrentTargetId = undefined;
+          this.dispatchState.mainPreDispatchBranchPoint = undefined;
+          this.dispatchState.pendingForkResults.unshift(...pendingFork);
+          return false;
+        }
         let dispatched = false;
         try {
-          dispatched = await this.runDispatchWithTyping(event, this.opts.runtimeKey, forkPrefix + buildEventBody(event));
+          dispatched = await this.runDispatch(
+            event,
+            this.opts.runtimeKey,
+            forkPrefix + buildEventBody(event),
+          );
           if (!dispatched) {
             // Shutdown short-circuit — restore the fork results so a future
             // pod can replay them, and return false so handleMessage skips ack.
@@ -1015,7 +1399,7 @@ export class ParallAgentGateway {
         return dispatched;
       }
 
-      case "buffer-main": {
+      case 'buffer-main': {
         if (this.shuttingDown) {
           return false;
         }
@@ -1025,24 +1409,28 @@ export class ParallAgentGateway {
         this.dispatchState.mainBuffer.push(event);
         if (
           this.dispatchState.mainCurrentTargetId === event.targetId &&
-          await this.opts.dispatchAdapter.enqueueDuringDispatch?.(this.opts.runtimeKey, buildEventBody(event))
+          (await this.opts.dispatchAdapter.enqueueDuringDispatch?.(
+            this.opts.runtimeKey,
+            buildEventBody(event),
+          ))
         ) {
-          this.startInjectedTyping(event);
-          this.opts.log?.info(
-            `steer injected for ${event.messageId} (will drain for bookkeeping)`,
-          );
+          this.opts.log?.info(`steer injected for ${event.messageId} (will drain for bookkeeping)`);
         }
         // If the main dispatch cycle ended while we awaited the steer RPC,
         // our event is buffered but no drain is in flight. Re-enter the
         // drain to process it. The draining guard prevents re-entry.
-        if (!this.dispatchState.mainDispatching && !this.draining && this.dispatchState.mainBuffer.length > 0) {
+        if (
+          !this.dispatchState.mainDispatching &&
+          !this.draining &&
+          this.dispatchState.mainBuffer.length > 0
+        ) {
           this.dispatchState.mainDispatching = true;
           void this.drainMainBuffer();
         }
         return false;
       }
 
-      case "buffer-fork": {
+      case 'buffer-fork': {
         const activeFork = this.forkStates.get(event.targetId);
         if (!activeFork) {
           this.dispatchState.mainBuffer.push(event);
@@ -1053,12 +1441,21 @@ export class ParallAgentGateway {
         });
       }
 
-      case "new-fork": {
+      case 'new-fork': {
         if (!this.opts.dispatchAdapter.forkSession) {
           this.dispatchState.mainBuffer.push(event);
           return false;
         }
 
+        try {
+          await this.emitDispatchReceived(event);
+        } catch (err) {
+          this.opts.log?.warn?.(
+            `mark-received failed for fork dispatch, leaving unacked for retry: ${String(err)}`,
+          );
+          this.dispatchState.mainBuffer.push(event);
+          return false;
+        }
         const fork = await this.opts.dispatchAdapter.forkSession({
           sessionKey: this.opts.runtimeKey,
           context: this.buildDispatchContext(event, this.opts.runtimeKey),
@@ -1076,10 +1473,16 @@ export class ParallAgentGateway {
           targetId: event.targetId,
           queue: [],
           processedEvents: [],
+          deadlineTimer: null,
+          deadlineExceeded: false,
         };
         this.forkStates.set(event.targetId, activeFork);
         this.dispatchState.activeForks.set(event.targetId, fork.sessionKey);
 
+        activeFork.deadlineTimer = setTimeout(() => {
+          this.abortFork(event.targetId, `deadline exceeded (${this.FORK_DEADLINE_MS}ms)`);
+        }, this.FORK_DEADLINE_MS);
+
         const firstEventPromise = new Promise<boolean>((resolve) => {
           activeFork.queue.push({ event, resolve });
         });
@@ -1113,25 +1516,26 @@ export class ParallAgentGateway {
     chatId: string,
     message: DispatchableMessage,
   ): Promise<MessageDispatchDecision> {
-    if (message.message_type !== "text") {
-      return { action: "skip" };
+    if (message.message_type !== 'text') {
+      return { action: 'skip' };
     }
 
     const chatInfo = await this.getOrFetchChatInfo(chatId);
-    if (!chatInfo) return { action: "retry" };
+    if (!chatInfo) return { action: 'retry' };
 
     const content = message.content as TextContent;
-    const body = content.text?.trim() ?? "";
+    const body = content.text?.trim() ?? '';
     const hasAttachments = message.attachments?.length;
 
-    if (!body && !hasAttachments) return { action: "skip" };
+    if (!body && !hasAttachments) return { action: 'skip' };
 
-    if (chatInfo.type === "group" && chatInfo.agentRoutingMode !== "active") {
+    if (chatInfo.type === 'group' && chatInfo.agentRoutingMode !== 'active') {
       const mentions = content.mentions ?? [];
       const isMentioned = mentions.some(
-        (mention) => mention.user_id === this.opts.agentUserId || mention.user_id === MENTION_ALL_USER_ID,
+        (mention) =>
+          mention.user_id === this.opts.agentUserId || mention.user_id === MENTION_ALL_USER_ID,
       );
-      if (!isMentioned) return { action: "skip" };
+      if (!isMentioned) return { action: 'skip' };
     }
 
     const attachments = (message.attachments ?? []).map((a) => ({
@@ -1141,23 +1545,57 @@ export class ParallAgentGateway {
       mimeType: a.mime_type,
     }));
 
+    // Fetch unread context (best-effort, parallelized).
+    let unreadCount: number | undefined;
+    let unreadSince: string | undefined;
+    let threadReplyCount: number | undefined;
+    let threadUnreadCount: number | undefined;
+    let threadUnreadSince: string | undefined;
+    const isPassiveOrSmart = chatInfo.type === 'group' && chatInfo.agentRoutingMode !== 'active';
+    const unreadPromise = isPassiveOrSmart
+      ? this.opts.client.getUnreadCounts(this.opts.config.org_id).catch(() => undefined)
+      : Promise.resolve(undefined);
+    const threadPromise = message.thread_root_id
+      ? this.opts.client
+          .getThreadUnread(this.opts.config.org_id, chatId, message.thread_root_id)
+          .catch(() => undefined)
+      : Promise.resolve(undefined);
+    const [counts, threadUnread] = await Promise.all([unreadPromise, threadPromise]);
+    if (counts) {
+      const entry = counts[chatId];
+      if (entry && entry.count > 1) {
+        unreadCount = entry.count;
+        unreadSince = entry.since;
+      }
+    }
+    if (threadUnread) {
+      threadReplyCount = threadUnread.total;
+      threadUnreadCount = threadUnread.unread > 0 ? threadUnread.unread : undefined;
+      threadUnreadSince = threadUnread.since ?? undefined;
+    }
+
     return {
-      action: "dispatch",
+      action: 'dispatch',
       event: {
-        type: "message",
+        type: 'message',
         targetId: chatId,
         targetName: chatInfo.name ?? undefined,
         targetType: chatInfo.type,
         senderId: message.sender_id,
         senderName: message.sender?.display_name ?? message.sender_id,
         messageId: message.id,
-        body: body || "[attachment]",
+        body: body || '[attachment]',
         threadRootId: message.thread_root_id ?? undefined,
         noReply: message.hints?.no_reply ?? false,
         attachments: attachments.length > 0 ? attachments : undefined,
         sentAt: message.created_at,
-        ackSourceType: "message",
+        ackSourceType: 'message',
         ackSourceId: message.id,
+        unreadCount,
+        unreadSince,
+        threadReplyCount,
+        threadUnreadCount,
+        threadUnreadSince,
       },
     };
   }
@@ -1166,11 +1604,11 @@ export class ParallAgentGateway {
     if (this.shuttingDown) return; // drain window — let server requeue via catch-up
     const chatId = data.chat_id;
     if (data.sender_id === this.opts.agentUserId) return;
-    if (data.message_type !== "text") return;
+    if (data.message_type !== 'text') return;
     if (!this.tryClaimMessage(data.id)) return;
 
     const decision = await this.buildMessageDispatchDecision(chatId, data);
-    if (decision.action !== "dispatch") {
+    if (decision.action !== 'dispatch') {
       this.dispatchedMessages.delete(data.id);
       return;
     }
@@ -1179,7 +1617,9 @@ export class ParallAgentGateway {
     try {
       const dispatched = await this.handleInboundEvent(event);
       if (dispatched) {
-        this.opts.client.ackDispatch(this.opts.config.org_id, { source_type: "message", source_id: data.id }).catch(() => {});
+        this.opts.client
+          .ackDispatch(this.opts.config.org_id, { source_type: 'message', source_id: data.id })
+          .catch(() => {});
       } else {
         this.dispatchedMessages.delete(data.id);
       }
@@ -1203,19 +1643,19 @@ export class ParallAgentGateway {
     parts.push(`Status: ${task.status}`, `Priority: ${task.priority}`);
     if (task.project_id) parts.push(`Project: prll://${task.project_id}`);
     if (task.parent_id) parts.push(`Parent: prll://${task.parent_id}`);
-    if (task.description) parts.push("", task.description);
+    if (task.description) parts.push('', task.description);
 
     const event: ParallEvent = {
-      type: "task",
+      type: 'task',
       targetId: task.id,
       targetName: task.identifier ?? undefined,
-      targetType: "task",
+      targetType: 'task',
       senderId: task.creator_id,
-      senderName: "system",
+      senderName: 'system',
       messageId: task.id,
-      body: parts.join("\n"),
+      body: parts.join('\n'),
       sentAt: task.updated_at ?? task.created_at,
-      ackSourceType: "task_activity",
+      ackSourceType: 'task_activity',
       ackSourceId,
     };
 
@@ -1288,10 +1728,12 @@ export class ParallAgentGateway {
     let task: Task | null = null;
     try {
       task = await this.opts.client.getTask(this.opts.config.org_id, taskId);
-    } catch { /* task context is optional */ }
+    } catch {
+      /* task context is optional */
+    }
 
     const taskLabel = task ? `${task.identifier ?? task.id} "${task.title}"` : taskId;
-    this.opts.log?.info(`task comment on ${taskLabel} by ${actorId ?? "unknown"}`);
+    this.opts.log?.info(`task comment on ${taskLabel} by ${actorId ?? 'unknown'}`);
 
     const parts: string[] = [];
     if (task) {
@@ -1300,20 +1742,97 @@ export class ParallAgentGateway {
     } else {
       parts.push(`Task: prll://${taskId}`);
     }
-    parts.push(`Comment by: ${comment.author?.display_name ?? actorId ?? "unknown"} (prll://${comment.author_id})`);
-    parts.push("", comment.body);
+    parts.push(
+      `Comment by: ${comment.author?.display_name ?? actorId ?? 'unknown'} (prll://${comment.author_id})`,
+    );
+    parts.push('', comment.body);
 
     const event: ParallEvent = {
-      type: "task_comment",
+      type: 'task_comment',
       targetId: taskId,
       targetName: task?.identifier ?? undefined,
-      targetType: "task",
+      targetType: 'task',
       senderId: comment.author_id,
-      senderName: comment.author?.display_name ?? actorId ?? "unknown",
+      senderName: comment.author?.display_name ?? actorId ?? 'unknown',
       messageId: commentId,
-      body: parts.join("\n"),
+      body: parts.join('\n'),
       deliveryReason: deliveryReason ?? undefined,
-      ackSourceType: "comment",
+      ackSourceType: 'comment',
+      ackSourceId: commentId,
+    };
+
+    let dispatched: boolean;
+    try {
+      dispatched = await this.handleInboundEvent(event);
+    } catch (err) {
+      // Clear dedupe key so the event remains retryable on next catch-up.
+      this.dispatchedTasks.delete(dedupeKey);
+      throw err;
+    }
+    if (!dispatched) {
+      this.dispatchedTasks.delete(dedupeKey);
+    }
+    return dispatched;
+  }
+
+  private async handleWikiComment(
+    commentId: string,
+    actorId: string | null,
+    deliveryReason?: DispatchDeliveryReason | null,
+  ): Promise<boolean> {
+    if (this.shuttingDown) return false; // drain window — let server requeue via catch-up
+    // Shares the comment dedupe namespace with handleTaskComment; comment IDs
+    // are globally unique so wiki/task keys never collide.
+    const dedupeKey = `comment:${commentId}`;
+    if (this.dispatchedTasks.has(dedupeKey)) return false;
+    this.dispatchedTasks.add(dedupeKey);
+
+    let comment: Comment | null = null;
+    try {
+      comment = await this.opts.client.getComment(this.opts.config.org_id, commentId);
+    } catch (err: unknown) {
+      const status = (err as { status?: number })?.status;
+      // 404 (deleted) and 403 (this agent lacks wiki read access to the
+      // target) are both permanent for this dispatch — ack the stale delivery
+      // so it doesn't retry on every catch-up. Other errors are transient.
+      if (status === 404 || status === 403) {
+        this.opts.log?.info(
+          `skipping inaccessible wiki comment ${commentId} (status ${status}), acking stale dispatch`,
+        );
+        this.dispatchedTasks.delete(dedupeKey);
+        return true; // caller will ack
+      }
+      this.dispatchedTasks.delete(dedupeKey);
+      return false; // transient error — leave pending for retry
+    }
+    if (!comment) {
+      this.dispatchedTasks.delete(dedupeKey);
+      return true; // null response = gone, ack stale dispatch
+    }
+    if (comment.hints?.no_reply) {
+      this.opts.log?.info(`skipping no_reply wiki comment ${commentId}, acking stale dispatch`);
+      this.dispatchedTasks.delete(dedupeKey);
+      return true;
+    }
+
+    const target = parseWikiCommentTarget(comment.target_uri);
+    this.opts.log?.info(`wiki comment on ${target.label} by ${actorId ?? 'unknown'}`);
+
+    const event: ParallEvent = {
+      type: 'wiki_comment',
+      // Full target_uri (scheme-stripped) is the routing key so different
+      // pages / inline anchors / changesets in the same wiki don't collide on
+      // one gateway lane. replyTargetUri keeps the canonical prll:// form.
+      targetId: target.routingKey,
+      targetName: target.label,
+      targetType: target.targetType,
+      senderId: comment.author_id,
+      senderName: comment.author?.display_name ?? actorId ?? 'unknown',
+      messageId: commentId,
+      body: comment.body,
+      deliveryReason: deliveryReason ?? undefined,
+      replyTargetUri: comment.target_uri,
+      ackSourceType: 'comment',
       ackSourceId: commentId,
     };
 
@@ -1339,7 +1858,10 @@ export class ParallAgentGateway {
    * access to already-delivered run snapshots, and the runtime must not crash
    * or retry forever in that case.
    */
-  private async fetchAndHandleScheduleFire(runId: string, actorId: string | null): Promise<boolean> {
+  private async fetchAndHandleScheduleFire(
+    runId: string,
+    actorId: string | null,
+  ): Promise<boolean> {
     let run: ScheduleRun | null = null;
     try {
       run = await this.opts.client.getScheduleRun(this.opts.config.org_id, runId);
@@ -1354,7 +1876,9 @@ export class ParallAgentGateway {
         this.opts.log?.warn(`schedule run ${runId} not accessible (404), acking stale dispatch`);
         return true;
       }
-      this.opts.log?.warn(`schedule run fetch failed for ${runId}, leaving pending: ${String(err)}`);
+      this.opts.log?.warn(
+        `schedule run fetch failed for ${runId}, leaving pending: ${String(err)}`,
+      );
       return false;
     }
     if (!run) return true;
@@ -1369,20 +1893,20 @@ export class ParallAgentGateway {
     this.opts.log?.info(`schedule fired: ${run.id} (schedule ${run.schedule_id})`);
 
     const event: ParallEvent = {
-      type: "schedule",
+      type: 'schedule',
       // Route by schedule_id (not attached chat_id) so concurrent fires of
       // different schedules can fork independently — matches the PR1 primitive
       // design where "schedule triggers; target decides response" and fire
       // semantics are independent of any attached conversation.
       targetId: run.schedule_id,
-      targetType: "schedule",
-      senderId: actorId ?? "system",
-      senderName: "schedule",
+      targetType: 'schedule',
+      senderId: actorId ?? 'system',
+      senderName: 'schedule',
       messageId: run.id,
-      body: run.fired_description ?? "",
+      body: run.fired_description ?? '',
       scheduledFireAt: run.scheduled_fire_at,
       attachedUri: run.fired_attached_uri ?? undefined,
-      ackSourceType: "schedule_run",
+      ackSourceType: 'schedule_run',
       ackSourceId: run.id,
     };
 
@@ -1399,17 +1923,25 @@ export class ParallAgentGateway {
     return dispatched;
   }
 
-  private async fetchAndHandleApprovalDecided(approvalId: string, actorId: string | null, chatId: string | null): Promise<boolean> {
+  private async fetchAndHandleApprovalDecided(
+    approvalId: string,
+    actorId: string | null,
+    chatId: string | null,
+  ): Promise<boolean> {
     let approval: Approval | null = null;
     try {
       approval = await this.opts.client.getApproval(approvalId);
     } catch (err: unknown) {
       const status = (err as { status?: number })?.status;
       if (status === 404 || status === 403) {
-        this.opts.log?.warn(`approval ${approvalId} not accessible (${status}), acking stale dispatch`);
+        this.opts.log?.warn(
+          `approval ${approvalId} not accessible (${status}), acking stale dispatch`,
+        );
         return true;
       }
-      this.opts.log?.warn(`approval fetch failed for ${approvalId}, leaving pending: ${String(err)}`);
+      this.opts.log?.warn(
+        `approval fetch failed for ${approvalId}, leaving pending: ${String(err)}`,
+      );
       return false;
     }
     if (!approval) return true;
@@ -1420,15 +1952,15 @@ export class ParallAgentGateway {
     this.dispatchedTasks.add(dedupeKey);
     this.opts.log?.info(`approval decided: ${approval.id} (${approval.status})`);
 
-    const statusLabel = approval.status === "approved" ? "Approved" : "Rejected";
-    const execInfo = approval.execution_status ? ` | execution: ${approval.execution_status}` : "";
+    const statusLabel = approval.status === 'approved' ? 'Approved' : 'Rejected';
+    const execInfo = approval.execution_status ? ` | execution: ${approval.execution_status}` : '';
     const body = `${statusLabel}: ${approval.title}${execInfo}`;
 
     const event: ParallEvent = {
-      type: "approval",
+      type: 'approval',
       targetId: chatId ?? approval.chat_id,
-      senderId: actorId ?? approval.decided_by ?? "system",
-      senderName: "approver",
+      senderId: actorId ?? approval.decided_by ?? 'system',
+      senderName: 'approver',
       messageId: approval.id,
       body,
     };
@@ -1446,11 +1978,9 @@ export class ParallAgentGateway {
     return dispatched;
   }
 
-  private async catchUpFromDispatch(coldStart = false) {
-    const minAge = coldStart ? Date.now() - this.COLD_START_WINDOW_MS : 0;
+  private async catchUpFromDispatch() {
     let cursor: string | undefined;
     let processed = 0;
-    let skippedOld = 0;
 
     do {
       const page = await this.opts.client.getDispatch(this.opts.config.org_id, {
@@ -1462,36 +1992,57 @@ export class ParallAgentGateway {
         // Shutdown short-circuit: stop fetching/building work that runDispatch
         // will only reject. Items remain unacked for the replacement pod.
         if (this.shuttingDown) break;
-        if (minAge > 0 && new Date(item.created_at).getTime() < minAge) {
-          this.opts.client.ackDispatchByID(this.opts.config.org_id, item.id).catch(() => {});
-          skippedOld++;
-          continue;
-        }
 
         processed++;
         try {
           let dispatched = false;
-          if (item.event_type === "task_assign" && item.task_id) {
+          if (item.event_type === 'task_assign' && item.task_id) {
             try {
-              dispatched = await this.handleTaskDispatch(item.task_id, item.source_id ?? item.task_id);
+              dispatched = await this.handleTaskDispatch(
+                item.task_id,
+                item.source_id ?? item.task_id,
+              );
             } catch (err: unknown) {
-              this.opts.log?.warn(`catch-up task fetch failed for ${item.task_id}, leaving pending: ${String(err)}`);
+              this.opts.log?.warn(
+                `catch-up task fetch failed for ${item.task_id}, leaving pending: ${String(err)}`,
+              );
               continue;
             }
-          } else if (item.event_type === "task_update" && item.task_id) {
+          } else if (item.event_type === 'task_update' && item.task_id) {
             try {
-              dispatched = await this.handleTaskDispatch(item.task_id, item.source_id ?? item.task_id, { allowCreator: true });
+              dispatched = await this.handleTaskDispatch(
+                item.task_id,
+                item.source_id ?? item.task_id,
+                { allowCreator: true },
+              );
             } catch (err: unknown) {
-              this.opts.log?.warn(`catch-up task fetch failed for ${item.task_id}, leaving pending: ${String(err)}`);
+              this.opts.log?.warn(
+                `catch-up task fetch failed for ${item.task_id}, leaving pending: ${String(err)}`,
+              );
               continue;
             }
-          } else if (item.event_type === "task_comment" && item.source_id && item.task_id) {
-            dispatched = await this.handleTaskComment(item.source_id, item.task_id, item.actor_id, item.delivery_reason);
-          } else if (item.event_type === "schedule.fire" && item.source_id) {
+          } else if (item.event_type === 'task_comment' && item.source_id && item.task_id) {
+            dispatched = await this.handleTaskComment(
+              item.source_id,
+              item.task_id,
+              item.actor_id,
+              item.delivery_reason,
+            );
+          } else if (item.event_type === 'wiki_comment' && item.source_id) {
+            dispatched = await this.handleWikiComment(
+              item.source_id,
+              item.actor_id,
+              item.delivery_reason,
+            );
+          } else if (item.event_type === 'schedule.fire' && item.source_id) {
             dispatched = await this.fetchAndHandleScheduleFire(item.source_id, item.actor_id);
-          } else if (item.event_type === "approval_decided" && item.source_id) {
-            dispatched = await this.fetchAndHandleApprovalDecided(item.source_id, item.actor_id, item.chat_id ?? null);
-          } else if (item.event_type === "message" && item.source_id && item.chat_id) {
+          } else if (item.event_type === 'approval_decided' && item.source_id) {
+            dispatched = await this.fetchAndHandleApprovalDecided(
+              item.source_id,
+              item.actor_id,
+              item.chat_id ?? null,
+            );
+          } else if (item.event_type === 'message' && item.source_id && item.chat_id) {
             if (!this.tryClaimMessage(item.source_id)) continue;
             let msg: Awaited<ReturnType<typeof this.opts.client.getMessage>> | null = null;
             let msgFetchFailed = false;
@@ -1503,7 +2054,9 @@ export class ParallAgentGateway {
                 msg = null;
               } else {
                 msgFetchFailed = true;
-                this.opts.log?.warn(`catch-up message fetch failed for ${item.source_id}, leaving pending: ${String(err)}`);
+                this.opts.log?.warn(
+                  `catch-up message fetch failed for ${item.source_id}, leaving pending: ${String(err)}`,
+                );
               }
             }
             if (msgFetchFailed) {
@@ -1517,11 +2070,11 @@ export class ParallAgentGateway {
             }
 
             const decision = await this.buildMessageDispatchDecision(item.chat_id, msg);
-            if (decision.action === "retry") {
+            if (decision.action === 'retry') {
               this.dispatchedMessages.delete(item.source_id);
               continue;
             }
-            if (decision.action === "skip") {
+            if (decision.action === 'skip') {
               this.dispatchedMessages.delete(item.source_id);
               this.opts.client.ackDispatchByID(this.opts.config.org_id, item.id).catch(() => {});
               continue;
@@ -1533,7 +2086,9 @@ export class ParallAgentGateway {
             this.opts.client.ackDispatchByID(this.opts.config.org_id, item.id).catch(() => {});
           }
         } catch (err) {
-          this.opts.log?.warn(`catch-up dispatch ${item.id} (${item.event_type}) failed: ${String(err)}`);
+          this.opts.log?.warn(
+            `catch-up dispatch ${item.id} (${item.event_type}) failed: ${String(err)}`,
+          );
         }
       }
       // Stop paginating once shutdown begins — the inner loop already broke,
@@ -1541,14 +2096,21 @@ export class ParallAgentGateway {
       cursor = !this.shuttingDown && page.has_more ? page.next_cursor : undefined;
     } while (cursor);
 
-    if (processed > 0 || skippedOld > 0) {
-      this.opts.log?.info(`dispatch catch-up: processed ${processed}, skipped ${skippedOld} old item(s)`);
+    if (processed > 0) {
+      this.opts.log?.info(`dispatch catch-up: processed ${processed}`);
     }
   }
 
   private async handleHello(data: HelloData) {
     const { client, config, log } = this.opts;
-    this.sessionId = data.session_id ?? "";
+    this.sessionId = data.session_id ?? '';
+    if (this.forkStates.size > 0) {
+      const targetIds = [...this.forkStates.keys()];
+      log?.info(`aborting ${targetIds.length} active fork(s) on reconnect`);
+      for (const targetId of targetIds) {
+        this.abortFork(targetId, 'ws reconnect');
+      }
+    }
     const intervalSec = data.heartbeat_interval > 0 ? data.heartbeat_interval : 30;
     try {
       const count = await fetchAllChats(client, config.org_id, this.chatInfoMap);
@@ -1570,7 +2132,7 @@ export class ParallAgentGateway {
           log?.warn(`heartbeat drift ${drift}ms — event loop may be blocked`);
         }
         this.lastHeartbeatAt = now;
-        if (this.opts.ws.state !== "connected") return;
+        if (this.opts.ws.state !== 'connected') return;
         this.opts.ws.sendAgentHeartbeat(this.sessionId, {
           hostname: os.hostname(),
           cores: os.cpus().length,
@@ -1580,9 +2142,7 @@ export class ParallAgentGateway {
         });
       }, intervalSec * 1000);
 
-      const isFirstHello = !this.hadSuccessfulHello;
-      this.hadSuccessfulHello = true;
-      this.catchUpFromDispatch(isFirstHello).catch((err) => {
+      this.catchUpFromDispatch().catch((err) => {
         log?.warn(`dispatch catch-up failed: ${String(err)}`);
       });
     } catch (err) {
@@ -1634,10 +2194,6 @@ export class ParallAgentGateway {
     }
 
     if (this.heartbeatTimer) clearInterval(this.heartbeatTimer);
-    for (const [, dispatch] of this.activeDispatches) {
-      clearInterval(dispatch.typingTimer);
-    }
-    this.activeDispatches.clear();
 
     await this.opts.onBeforeDisconnect?.();