@parall/agent-core 1.30.0 → 1.32.0

package/dist/gateway-base.js

@@ -1,10 +1,13 @@
-import * as os from "node:os";
-import * as fs from "node:fs";
-import * as path from "node:path";
-import { MENTION_ALL_USER_ID } from "@parall/sdk";
-import { buildEventBody, buildEventBodyForForkResult, buildForkResultPrefix, buildForkScopePrefix } from "./event-format.js";
-import { routeTrigger } from "./routing.js";
-import { clearDispatchMessageId, clearDispatchNoReply, clearSessionMessageId, setDispatchMessageId, setDispatchNoReply, setSessionChatId, setSessionMessageId, } from "./session-state.js";
+import * as os from 'node:os';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { ApiError, MENTION_ALL_USER_ID } from '@parall/sdk';
+import { buildEventBody, buildEventBodyForForkResult, buildForkResultPrefix, buildForkScopePrefix, } from './event-format.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 { isParallSendCommand, isParallNoReplyCommand, extractShellCommand, } from './bridge-workspace.js';
+import { startDispatchSpan, endDispatchSpan, recordDispatchMetric, recordMissingReply, runWithSessionKey, } from './telemetry.js';
+const LIVE_SESSION_STATUSES = new Set(['open', 'active', 'idle']);
 // Parse PRLL_SHUTDOWN_DEADLINE_MS (or any string env value) into a positive
 // integer milliseconds value, or undefined if unset/invalid. Runtimes pass
 // the result into ParallGatewayOptions.shutdownDeadlineMs; leaving it
@@ -21,17 +24,72 @@ export function parseShutdownDeadlineMs(raw) {
         return undefined;
     return Math.floor(n);
 }
+export function parseForkDeadlineMs(raw) {
+    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) {
+    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) {
-    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) {
+    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(client, orgId, chatInfoMap) {
     let cursor;
@@ -53,8 +111,6 @@ async function fetchAllChats(client, orgId, chatInfoMap) {
 export class ParallAgentGateway {
     opts;
     chatInfoMap = new Map();
-    activeDispatches = new Map();
-    injectedTypingCounts = new Map();
     dispatchedTasks = new Set();
     dispatchedMessages = new Set();
     forkStates = new Map();
@@ -64,11 +120,10 @@ export class ParallAgentGateway {
         pendingForkResults: [],
         mainBuffer: [],
     };
-    sessionId = "";
+    sessionId = '';
     activeSessionId;
     sessionBindings = new Map();
     heartbeatTimer = null;
-    hadSuccessfulHello = false;
     lastHeartbeatAt = Date.now();
     draining = false;
     // Graceful shutdown state. When SIGTERM / abort fires, `shuttingDown` flips
@@ -80,25 +135,30 @@ export class ParallAgentGateway {
     drainResolvers = [];
     pendingRestartNotification = null;
     DISPATCHED_MESSAGES_CAP = 5000;
-    COLD_START_WINDOW_MS;
     // 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).
     SHUTDOWN_DEADLINE_MS;
+    FORK_DEADLINE_MS;
+    DISPATCH_DEADLINE_MS;
     constructor(opts) {
         this.opts = opts;
-        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) {
         const { ws, log } = this.opts;
         ws.onStateChange((state) => {
             log?.info(`connection state → ${state}`);
         });
-        ws.on("hello", async (data) => {
+        ws.on('hello', async (data) => {
             await this.handleHello(data);
         });
-        ws.on("chat.update", (data) => {
+        ws.on('chat.update', (data) => {
             const changes = data.changes;
             if (!changes)
                 return;
@@ -106,27 +166,27 @@ export class ParallAgentGateway {
             if (existing) {
                 this.chatInfoMap.set(data.chat_id, {
                     ...existing,
-                    ...(typeof changes.type === "string" ? { type: changes.type } : {}),
-                    ...(typeof changes.name === "string" ? { name: changes.name } : {}),
-                    ...(typeof changes.agent_routing_mode === "string"
+                    ...(typeof changes.type === 'string' ? { type: changes.type } : {}),
+                    ...(typeof changes.name === 'string' ? { name: changes.name } : {}),
+                    ...(typeof changes.agent_routing_mode === 'string'
                         ? { agentRoutingMode: changes.agent_routing_mode }
                         : {}),
                 });
             }
-            else if (typeof changes.type === "string") {
+            else if (typeof changes.type === 'string') {
                 this.chatInfoMap.set(data.chat_id, {
                     type: changes.type,
-                    name: typeof changes.name === "string" ? changes.name : null,
-                    agentRoutingMode: (typeof changes.agent_routing_mode === "string"
+                    name: typeof changes.name === 'string' ? changes.name : null,
+                    agentRoutingMode: (typeof changes.agent_routing_mode === 'string'
                         ? changes.agent_routing_mode
-                        : "passive"),
+                        : 'passive'),
                 });
             }
         });
-        ws.on("message.new", async (data) => {
+        ws.on('message.new', async (data) => {
             await this.handleMessage(data);
         });
-        ws.on("agent_config.update", async (data) => {
+        ws.on('agent_config.update', async (data) => {
             this.opts.log?.info(`config update notification (version=${data.version})`);
             try {
                 await this.opts.onConfigUpdate?.(data);
@@ -135,13 +195,12 @@ export class ParallAgentGateway {
                 this.opts.log?.warn(`config update failed: ${String(err)}`);
             }
         });
-        ws.on("agent.new_session", async (data) => {
-            const prevId = data.previous_session_id ?? "";
+        ws.on('agent.new_session', async (data) => {
+            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);
@@ -150,27 +209,32 @@ export class ParallAgentGateway {
                 this.opts.log?.warn(`onNewSession callback failed: ${String(err)}`);
             }
         });
-        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)}`));
         });
-        ws.on("task.assigned", async (data) => {
+        ws.on('task.assigned', async (data) => {
             if (data.assignee_id !== this.opts.agentUserId)
                 return;
-            if (data.status !== "todo" && data.status !== "in_progress")
+            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) => {
-            if (data.event_type === "task_comment") {
+        ws.on('dispatch.new', async (data) => {
+            if (data.event_type === 'task_comment') {
                 if (!data.source_id || !data.task_id)
                     return;
                 try {
@@ -183,7 +247,20 @@ export class ParallAgentGateway {
                     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 {
@@ -196,7 +273,7 @@ export class ParallAgentGateway {
                     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 {
@@ -209,7 +286,7 @@ export class ParallAgentGateway {
                     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 {
@@ -222,7 +299,7 @@ export class ParallAgentGateway {
                     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
@@ -233,10 +310,10 @@ export class ParallAgentGateway {
                 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((resolve) => {
-            abortSignal.addEventListener("abort", async () => {
+            abortSignal.addEventListener('abort', async () => {
                 await this.shutdown();
                 resolve();
             });
@@ -256,60 +333,13 @@ export class ParallAgentGateway {
         this.dispatchedMessages.add(id);
         return true;
     }
-    startTyping(chatId) {
-        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 });
-    }
-    stopTyping(chatId) {
-        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");
-    }
-    shouldShowTyping(event) {
-        return event.type === "message" && event.targetId.startsWith("cht_") && !event.noReply;
-    }
-    startInjectedTyping(event) {
-        if (!this.shouldShowTyping(event))
-            return;
-        this.startTyping(event.targetId);
-        this.injectedTypingCounts.set(event.targetId, (this.injectedTypingCounts.get(event.targetId) ?? 0) + 1);
-    }
-    takeInjectedTypingCount(chatId) {
-        const count = this.injectedTypingCounts.get(chatId) ?? 0;
-        this.injectedTypingCounts.delete(chatId);
-        return count;
-    }
-    async runDispatchWithTyping(event, sessionKey, bodyForAgent, earlierEvents = [], captureText, opts = {}) {
-        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);
-            }
-        }
+    async emitDispatchReceived(event) {
+        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,
+        });
     }
     buildDispatchContext(event, sessionKey) {
         const binding = this.sessionBindings.get(sessionKey);
@@ -322,7 +352,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),
@@ -331,24 +361,41 @@ export class ParallAgentGateway {
             log: this.opts.log,
         };
     }
+    isSessionNotLiveError(err) {
+        return (err instanceof ApiError &&
+            err.status === 409 &&
+            (err.code === 'SESSION_NOT_LIVE' || err.code === 'INVALID_TRANSITION'));
+    }
     async createInputStep(sessionId, event) {
         const target = resolveStepTarget(event);
         try {
             await this.opts.client.createAgentStep(this.opts.config.org_id, this.opts.agentUserId, sessionId, {
-                step_type: "input",
+                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 },
+                    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),
@@ -357,6 +404,8 @@ export class ParallAgentGateway {
             });
         }
         catch (err) {
+            if (this.isSessionNotLiveError(err))
+                throw err;
             this.opts.log?.warn(`failed to create input step: ${String(err)}`);
         }
     }
@@ -364,18 +413,18 @@ export class ParallAgentGateway {
         const target = resolveStepTarget(event);
         try {
             switch (runtimeEvent.type) {
-                case "thinking":
+                case 'thinking':
                     await this.opts.client.createAgentStep(this.opts.config.org_id, this.opts.agentUserId, sessionId, {
-                        step_type: "thinking",
+                        step_type: 'thinking',
                         target_type: target.target_type,
                         target_id: target.target_id,
                         content: { text: runtimeEvent.text },
                         group_key: runtimeEvent.groupKey,
                     });
                     break;
-                case "text":
+                case 'text':
                     await this.opts.client.createAgentStep(this.opts.config.org_id, this.opts.agentUserId, sessionId, {
-                        step_type: "text",
+                        step_type: 'text',
                         target_type: target.target_type,
                         target_id: target.target_id,
                         content: {
@@ -386,16 +435,16 @@ export class ParallAgentGateway {
                         group_key: runtimeEvent.groupKey,
                     });
                     break;
-                case "tool_call": {
+                case 'tool_call': {
                     const step = await this.opts.client.createAgentStep(this.opts.config.org_id, this.opts.agentUserId, sessionId, {
-                        step_type: "tool_call",
+                        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",
+                            status: 'running',
                             started_at: runtimeEvent.startedAt ?? new Date().toISOString(),
                         },
                         group_key: runtimeEvent.groupKey,
@@ -409,15 +458,15 @@ export class ParallAgentGateway {
                     }
                     break;
                 }
-                case "tool_result":
+                case 'tool_result':
                     await this.opts.client.createAgentStep(this.opts.config.org_id, this.opts.agentUserId, sessionId, {
-                        step_type: "tool_result",
+                        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",
+                            status: runtimeEvent.error ? 'error' : 'success',
                             output: runtimeEvent.output,
                             duration_ms: runtimeEvent.durationMs ?? 0,
                             collapsible: true,
@@ -431,9 +480,9 @@ export class ParallAgentGateway {
                         this.clearStepIdFile(stepIdFilePath);
                     }
                     break;
-                case "error":
+                case 'error':
                     await this.opts.client.createAgentStep(this.opts.config.org_id, this.opts.agentUserId, sessionId, {
-                        step_type: "text",
+                        step_type: 'text',
                         target_type: target.target_type,
                         target_id: target.target_id,
                         content: { text: runtimeEvent.message, suppressed: false },
@@ -443,13 +492,15 @@ export class ParallAgentGateway {
             }
         }
         catch (err) {
+            if (this.isSessionNotLiveError(err))
+                throw err;
             this.opts.log?.warn(`failed to create ${runtimeEvent.type} step: ${String(err)}`);
         }
     }
     writeContextFile(filePath, ctx) {
         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)}`);
@@ -457,10 +508,10 @@ export class ParallAgentGateway {
     }
     updateContextFileStepId(filePath, stepId) {
         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)}`);
@@ -468,10 +519,10 @@ export class ParallAgentGateway {
     }
     updateContextFileSessionId(filePath, sessionId) {
         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)}`);
@@ -481,7 +532,7 @@ export class ParallAgentGateway {
     writeStepIdFile(filePath, stepId) {
         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)}`);
@@ -490,7 +541,7 @@ export class ParallAgentGateway {
     /** @deprecated Use writeContextFile / updateContextFileStepId. */
     clearStepIdFile(filePath) {
         try {
-            fs.writeFileSync(filePath, "", "utf8");
+            fs.writeFileSync(filePath, '', 'utf8');
         }
         catch {
             // Best-effort cleanup.
@@ -524,6 +575,18 @@ export class ParallAgentGateway {
             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 = {
             sessionKey,
             agentSessionId: session.id,
@@ -554,118 +617,237 @@ export class ParallAgentGateway {
             return false;
         }
         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);
-        const dispatchContext = this.buildDispatchContext(event, sessionKey);
-        const contextFilePath = dispatchContext.contextFilePath;
-        const stepIdFilePath = dispatchContext.stepIdFilePath;
-        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++;
-        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);
+        resetDispatchMetrics(sessionKey);
+        return runWithSessionKey(sessionKey, async () => {
+            let dispatchSpan = null;
+            setSessionChatId(sessionKey, event.targetId);
+            setSessionMessageId(sessionKey, event.messageId);
+            setDispatchMessageId(sessionKey, event.messageId);
+            setDispatchNoReply(sessionKey, event.noReply ?? false);
+            const dispatchContext = this.buildDispatchContext(event, sessionKey);
+            const contextFilePath = dispatchContext.contextFilePath;
+            const stepIdFilePath = dispatchContext.stepIdFilePath;
+            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;
+            const pendingSendCallIds = new Set();
+            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);
-                }
-                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);
+            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.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);
+                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;
             }
-            this.inFlightDispatches--;
-            if (this.inFlightDispatches === 0 && this.drainResolvers.length > 0) {
-                const resolvers = this.drainResolvers.splice(0);
-                for (const resolve of resolvers)
-                    resolve();
+            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();
+                }
             }
+            return true;
+        }); // runWithSessionKey
+    }
+    abortFork(targetId, reason) {
+        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 = {
+                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;
     }
     async runForkDrainLoop(fork) {
         let lastCapturedText = [];
@@ -677,7 +859,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;
@@ -688,7 +870,7 @@ export class ParallAgentGateway {
                 const earlier = events.slice(0, -1);
                 try {
                     const batchText = [];
-                    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.
@@ -699,6 +881,11 @@ export class ParallAgentGateway {
                     }
                     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);
@@ -717,9 +904,13 @@ export class ParallAgentGateway {
             }
         }
         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;
                 try {
                     historyPath = this.opts.dispatchAdapter.getSessionHistoryPath?.(fork.fork.sessionKey);
@@ -742,8 +933,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 = {
@@ -762,10 +957,17 @@ 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);
             }
         }
@@ -792,13 +994,22 @@ 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 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(event, this.opts.runtimeKey, forkPrefix + buildEventBody(event), earlier, undefined, { suppressStart: injectedTypingCount > 0, injectedTypingCount });
+                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);
                 if (!dispatched) {
                     // Shutdown: skip the ack so the server redelivers these buffered
                     // events to the replacement pod via dispatch catch-up. Put both the
@@ -808,12 +1019,15 @@ 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, {
+                    this.opts.client
+                        .ackDispatch(this.opts.config.org_id, {
                         source_type: sourceType,
                         source_id: sourceId,
-                    }).catch(() => { });
+                    })
+                        .catch(() => { });
                 }
             }
         }
@@ -822,12 +1036,22 @@ 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);
+            }
         }
     }
     async handleInboundEvent(event) {
         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;
@@ -835,11 +1059,21 @@ 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.
@@ -851,7 +1085,7 @@ export class ParallAgentGateway {
                 }
                 return dispatched;
             }
-            case "buffer-main": {
+            case 'buffer-main': {
                 if (this.shuttingDown) {
                     return false;
                 }
@@ -860,20 +1094,21 @@ export class ParallAgentGateway {
                 // gap between the steer await and the push.
                 this.dispatchState.mainBuffer.push(event);
                 if (this.dispatchState.mainCurrentTargetId === event.targetId &&
-                    await this.opts.dispatchAdapter.enqueueDuringDispatch?.(this.opts.runtimeKey, buildEventBody(event))) {
-                    this.startInjectedTyping(event);
+                    (await this.opts.dispatchAdapter.enqueueDuringDispatch?.(this.opts.runtimeKey, buildEventBody(event)))) {
                     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);
@@ -883,11 +1118,19 @@ export class ParallAgentGateway {
                     activeFork.queue.push({ event, resolve });
                 });
             }
-            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),
@@ -903,9 +1146,14 @@ 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((resolve) => {
                     activeFork.queue.push({ event, resolve });
                 });
@@ -936,22 +1184,22 @@ export class ParallAgentGateway {
         }
     }
     async buildMessageDispatchDecision(chatId, message) {
-        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" };
+            return { action: 'retry' };
         const content = message.content;
-        const body = content.text?.trim() ?? "";
+        const body = content.text?.trim() ?? '';
         const hasAttachments = message.attachments?.length;
         if (!body && !hasAttachments)
-            return { action: "skip" };
-        if (chatInfo.type === "group" && chatInfo.agentRoutingMode !== "active") {
+            return { action: 'skip' };
+        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);
             if (!isMentioned)
-                return { action: "skip" };
+                return { action: 'skip' };
         }
         const attachments = (message.attachments ?? []).map((a) => ({
             id: a.id,
@@ -959,23 +1207,56 @@ export class ParallAgentGateway {
             fileSize: a.file_size,
             mimeType: a.mime_type,
         }));
+        // Fetch unread context (best-effort, parallelized).
+        let unreadCount;
+        let unreadSince;
+        let threadReplyCount;
+        let threadUnreadCount;
+        let threadUnreadSince;
+        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,
             },
         };
     }
@@ -985,12 +1266,12 @@ export class ParallAgentGateway {
         const chatId = data.chat_id;
         if (data.sender_id === this.opts.agentUserId)
             return;
-        if (data.message_type !== "text")
+        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;
         }
@@ -998,7 +1279,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);
@@ -1026,18 +1309,18 @@ export class ParallAgentGateway {
         if (task.parent_id)
             parts.push(`Parent: prll://${task.parent_id}`);
         if (task.description)
-            parts.push("", task.description);
+            parts.push('', task.description);
         const event = {
-            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,
         };
         const dispatched = await this.handleInboundEvent(event);
@@ -1100,9 +1383,11 @@ export class ParallAgentGateway {
         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 = [];
         if (task) {
             parts.push(`Task: ${task.title} (prll://${task.id})`);
@@ -1111,19 +1396,87 @@ 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 = {
-            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;
+        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;
+    }
+    async handleWikiComment(commentId, actorId, deliveryReason) {
+        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 = null;
+        try {
+            comment = await this.opts.client.getComment(this.opts.config.org_id, commentId);
+        }
+        catch (err) {
+            const status = err?.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 = {
+            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,
         };
         let dispatched;
@@ -1180,20 +1533,20 @@ export class ParallAgentGateway {
         this.dispatchedTasks.add(dedupeKey);
         this.opts.log?.info(`schedule fired: ${run.id} (schedule ${run.schedule_id})`);
         const event = {
-            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,
         };
         let dispatched;
@@ -1232,14 +1585,14 @@ export class ParallAgentGateway {
             return false;
         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 = {
-            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,
         };
@@ -1256,11 +1609,9 @@ export class ParallAgentGateway {
         }
         return dispatched;
     }
-    async catchUpFromDispatch(coldStart = false) {
-        const minAge = coldStart ? Date.now() - this.COLD_START_WINDOW_MS : 0;
+    async catchUpFromDispatch() {
         let cursor;
         let processed = 0;
-        let skippedOld = 0;
         do {
             const page = await this.opts.client.getDispatch(this.opts.config.org_id, {
                 limit: 50,
@@ -1271,15 +1622,10 @@ export class ParallAgentGateway {
                 // 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);
                         }
@@ -1288,7 +1634,7 @@ export class ParallAgentGateway {
                             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 });
                         }
@@ -1297,16 +1643,19 @@ export class ParallAgentGateway {
                             continue;
                         }
                     }
-                    else if (item.event_type === "task_comment" && item.source_id && item.task_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 === "schedule.fire" && item.source_id) {
+                    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) {
+                    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 === 'message' && item.source_id && item.chat_id) {
                         if (!this.tryClaimMessage(item.source_id))
                             continue;
                         let msg = null;
@@ -1334,11 +1683,11 @@ export class ParallAgentGateway {
                             continue;
                         }
                         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;
@@ -1357,13 +1706,20 @@ export class ParallAgentGateway {
             // and the next page would be wasted API work the replacement pod redoes.
             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}`);
         }
     }
     async handleHello(data) {
         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);
@@ -1384,7 +1740,7 @@ export class ParallAgentGateway {
                     log?.warn(`heartbeat drift ${drift}ms — event loop may be blocked`);
                 }
                 this.lastHeartbeatAt = now;
-                if (this.opts.ws.state !== "connected")
+                if (this.opts.ws.state !== 'connected')
                     return;
                 this.opts.ws.sendAgentHeartbeat(this.sessionId, {
                     hostname: os.hostname(),
@@ -1394,9 +1750,7 @@ export class ParallAgentGateway {
                     uptime: os.uptime(),
                 });
             }, 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)}`);
             });
         }
@@ -1445,10 +1799,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?.();
         this.opts.ws.disconnect();
         this.opts.log?.info(`disconnected`);