@calltelemetry/openclaw-linear 0.8.1 → 0.8.3

package/src/pipeline/webhook.ts

@@ -29,10 +29,20 @@ interface AgentProfile {
 
 const PROFILES_PATH = join(process.env.HOME ?? "/home/claw", ".openclaw", "agent-profiles.json");
 
+// ── Cached profile loader (5s TTL) ─────────────────────────────────
+let profilesCache: { data: Record<string, AgentProfile>; loadedAt: number } | null = null;
+const PROFILES_CACHE_TTL_MS = 5_000;
+
 function loadAgentProfiles(): Record<string, AgentProfile> {
+  const now = Date.now();
+  if (profilesCache && now - profilesCache.loadedAt < PROFILES_CACHE_TTL_MS) {
+    return profilesCache.data;
+  }
   try {
     const raw = readFileSync(PROFILES_PATH, "utf8");
-    return JSON.parse(raw).agents ?? {};
+    const data = JSON.parse(raw).agents ?? {};
+    profilesCache = { data, loadedAt: now };
+    return data;
   } catch {
     return {};
   }
@@ -64,19 +74,45 @@ function resolveAgentFromAlias(alias: string, profiles: Record<string, AgentProf
 // Track issues with active agent runs to prevent concurrent duplicate runs.
 const activeRuns = new Set<string>();
 
-// Dedup: track recently processed keys to avoid double-handling
+// Dedup: track recently processed keys to avoid double-handling.
+// Periodic sweep (every 10s) instead of O(n) scan on every call.
 const recentlyProcessed = new Map<string, number>();
+const DEDUP_TTL_MS = 60_000;
+const SWEEP_INTERVAL_MS = 10_000;
+let lastSweep = Date.now();
+
 function wasRecentlyProcessed(key: string): boolean {
   const now = Date.now();
-  // Clean old entries
-  for (const [k, ts] of recentlyProcessed) {
-    if (now - ts > 60_000) recentlyProcessed.delete(k);
+  if (now - lastSweep > SWEEP_INTERVAL_MS) {
+    for (const [k, ts] of recentlyProcessed) {
+      if (now - ts > DEDUP_TTL_MS) recentlyProcessed.delete(k);
+    }
+    lastSweep = now;
   }
   if (recentlyProcessed.has(key)) return true;
   recentlyProcessed.set(key, now);
   return false;
 }
 
+/** @internal — test-only; clears all in-memory dedup state. */
+export function _resetForTesting(): void {
+  activeRuns.clear();
+  recentlyProcessed.clear();
+  profilesCache = null;
+  linearApiCache = null;
+  lastSweep = Date.now();
+}
+
+/** @internal — test-only; add an issue ID to the activeRuns set. */
+export function _addActiveRunForTesting(issueId: string): void {
+  activeRuns.add(issueId);
+}
+
+/** @internal — test-only; pre-registers a key as recently processed. */
+export function _markAsProcessedForTesting(key: string): void {
+  wasRecentlyProcessed(key);
+}
+
 async function readJsonBody(req: IncomingMessage, maxBytes: number) {
   const chunks: Buffer[] = [];
   let total = 0;
@@ -101,7 +137,16 @@ async function readJsonBody(req: IncomingMessage, maxBytes: number) {
   });
 }
 
+// ── Cached LinearApi instance (30s TTL) ────────────────────────────
+let linearApiCache: { instance: LinearAgentApi; createdAt: number } | null = null;
+const LINEAR_API_CACHE_TTL_MS = 30_000;
+
 function createLinearApi(api: OpenClawPluginApi): LinearAgentApi | null {
+  const now = Date.now();
+  if (linearApiCache && now - linearApiCache.createdAt < LINEAR_API_CACHE_TTL_MS) {
+    return linearApiCache.instance;
+  }
+
   const pluginConfig = (api as any).pluginConfig as Record<string, unknown> | undefined;
   const resolved = resolveLinearToken(pluginConfig);
 
@@ -110,12 +155,54 @@ function createLinearApi(api: OpenClawPluginApi): LinearAgentApi | null {
   const clientId = (pluginConfig?.clientId as string) ?? process.env.LINEAR_CLIENT_ID;
   const clientSecret = (pluginConfig?.clientSecret as string) ?? process.env.LINEAR_CLIENT_SECRET;
 
-  return new LinearAgentApi(resolved.accessToken, {
+  const instance = new LinearAgentApi(resolved.accessToken, {
     refreshToken: resolved.refreshToken,
     expiresAt: resolved.expiresAt,
     clientId: clientId ?? undefined,
     clientSecret: clientSecret ?? undefined,
   });
+  linearApiCache = { instance, createdAt: now };
+  return instance;
+}
+
+// ── Comment wrapper that pre-registers comment ID for dedup ────────
+// When we create a comment, Linear fires Comment.create webhook back to us.
+// Register the comment ID immediately so the webhook handler skips it.
+// The `opts` parameter posts as a named OpenClaw agent identity (e.g.
+// createAsUser: "Mal" with avatar) — requires OAuth actor=app scope.
+async function createCommentWithDedup(
+  linearApi: LinearAgentApi,
+  issueId: string,
+  body: string,
+  opts?: { createAsUser?: string; displayIconUrl?: string },
+): Promise<string> {
+  const commentId = await linearApi.createComment(issueId, body, opts);
+  wasRecentlyProcessed(`comment:${commentId}`);
+  return commentId;
+}
+
+/**
+ * Post a comment as agent identity with prefix fallback.
+ * With gql() partial-success fix, the catch only fires for real failures.
+ */
+async function postAgentComment(
+  api: OpenClawPluginApi,
+  linearApi: LinearAgentApi,
+  issueId: string,
+  body: string,
+  label: string,
+  agentOpts?: { createAsUser: string; displayIconUrl: string },
+): Promise<void> {
+  if (!agentOpts) {
+    await createCommentWithDedup(linearApi, issueId, `**[${label}]** ${body}`);
+    return;
+  }
+  try {
+    await createCommentWithDedup(linearApi, issueId, body, agentOpts);
+  } catch (identityErr) {
+    api.logger.warn(`Agent identity comment failed: ${identityErr}`);
+    await createCommentWithDedup(linearApi, issueId, `**[${label}]** ${body}`);
+  }
 }
 
 function resolveAgentId(api: OpenClawPluginApi): string {
@@ -155,158 +242,14 @@ export async function handleLinearWebhook(
   emitDiagnostic(api, { event: "webhook_received", webhookType: payload.type, webhookAction: payload.action });
 
 
-  // ── AppUserNotification — OAuth app webhook for agent mentions/assignments
+  // ── AppUserNotification — IGNORED ─────────────────────────────────
+  // AppUserNotification duplicates events already handled by the workspace
+  // webhook (Comment.create for mentions, Issue.update for assignments).
+  // Processing both causes double agent runs. Ack and discard.
   if (payload.type === "AppUserNotification") {
+    api.logger.info(`AppUserNotification ignored (duplicate of workspace webhook): ${payload.notification?.type} appUserId=${payload.appUserId}`);
     res.statusCode = 200;
     res.end("ok");
-
-    const notification = payload.notification;
-    const notifType = notification?.type;
-    api.logger.info(`AppUserNotification: ${notifType} appUserId=${payload.appUserId}`);
-
-    const issue = notification?.issue;
-    const comment = notification?.comment ?? notification?.parentComment;
-
-    if (!issue?.id) {
-      api.logger.error("AppUserNotification missing issue data");
-      return true;
-    }
-
-    const linearApi = createLinearApi(api);
-    if (!linearApi) {
-      api.logger.error("No Linear access token — cannot process agent notification");
-      return true;
-    }
-
-    const agentId = resolveAgentId(api);
-
-    // Fetch full issue details
-    let enrichedIssue: any = issue;
-    try {
-      enrichedIssue = await linearApi.getIssueDetails(issue.id);
-    } catch (err) {
-      api.logger.warn(`Could not fetch issue details: ${err}`);
-    }
-
-    const description = enrichedIssue?.description ?? issue?.description ?? "(no description)";
-    const comments = enrichedIssue?.comments?.nodes ?? [];
-    const commentSummary = comments
-      .slice(-5)
-      .map((c: any) => `  - **${c.user?.name ?? "Unknown"}**: ${c.body?.slice(0, 200)}`)
-      .join("\n");
-
-    const notifIssueRef = enrichedIssue?.identifier ?? issue.id;
-    const message = [
-      `You are an orchestrator responding to a Linear issue notification. Your text output will be automatically posted as a comment on the issue (do NOT post a comment yourself — the handler does it).`,
-      ``,
-      `**Tool access:**`,
-      `- \`linearis\` CLI: READ ONLY. You can read issues (\`linearis issues read ${notifIssueRef}\`), list, and search. Do NOT use linearis to update, close, comment, or modify issues.`,
-      `- \`code_run\`: Dispatch coding work to a worker. Workers return text — they cannot access linearis.`,
-      `- Standard tools: exec, read, edit, write, web_search, etc.`,
-      ``,
-      `**Your role:** Dispatcher. For work requests, use \`code_run\`. You do NOT update issue status — the audit system handles lifecycle.`,
-      ``,
-      `## Issue: ${notifIssueRef} — ${enrichedIssue?.title ?? issue.title ?? "(untitled)"}`,
-      `**Status:** ${enrichedIssue?.state?.name ?? "Unknown"} | **Assignee:** ${enrichedIssue?.assignee?.name ?? "Unassigned"}`,
-      ``,
-      `**Description:**`,
-      description,
-      commentSummary ? `\n**Recent comments:**\n${commentSummary}` : "",
-      comment?.body ? `\n**Triggering comment:**\n> ${comment.body}` : "",
-      ``,
-      `Respond concisely. For work requests, dispatch via \`code_run\` and summarize the result.`,
-    ].filter(Boolean).join("\n");
-
-    // Dispatch agent with session lifecycle (non-blocking)
-    void (async () => {
-      const profiles = loadAgentProfiles();
-      const defaultProfile = Object.entries(profiles).find(([, p]) => p.isDefault);
-      const label = defaultProfile?.[1]?.label ?? profiles[agentId]?.label ?? agentId;
-      const avatarUrl = defaultProfile?.[1]?.avatarUrl ?? profiles[agentId]?.avatarUrl;
-      let agentSessionId: string | null = null;
-
-      try {
-        // 1. Create agent session (non-fatal)
-        const sessionResult = await linearApi.createSessionOnIssue(issue.id);
-        agentSessionId = sessionResult.sessionId;
-        if (agentSessionId) {
-          api.logger.info(`Created agent session ${agentSessionId} for notification`);
-          setActiveSession({
-            agentSessionId,
-            issueIdentifier: enrichedIssue?.identifier ?? issue.id,
-            issueId: issue.id,
-            agentId,
-            startedAt: Date.now(),
-          });
-        } else {
-          api.logger.warn(`Could not create agent session for notification: ${sessionResult.error ?? "unknown"}`);
-        }
-
-        // 2. Emit thought
-        if (agentSessionId) {
-          await linearApi.emitActivity(agentSessionId, {
-            type: "thought",
-            body: `Reviewing ${enrichedIssue?.identifier ?? issue.id}...`,
-          }).catch(() => {});
-        }
-
-        // 3. Run agent with streaming
-        const sessionId = `linear-notif-${notification?.type ?? "unknown"}-${Date.now()}`;
-        const { runAgent } = await import("../agent/agent.js");
-        const result = await runAgent({
-          api,
-          agentId,
-          sessionId,
-          message,
-          timeoutMs: 3 * 60_000,
-          streaming: agentSessionId ? { linearApi, agentSessionId } : undefined,
-        });
-
-        const responseBody = result.success
-          ? result.output
-          : `Something went wrong while processing this. The system will retry automatically if possible. If this keeps happening, run \`openclaw openclaw-linear doctor\` to check for issues.`;
-
-        // 5. Post branded comment (fallback to prefix)
-        const brandingOpts = avatarUrl
-          ? { createAsUser: label, displayIconUrl: avatarUrl }
-          : undefined;
-
-        try {
-          if (brandingOpts) {
-            await linearApi.createComment(issue.id, responseBody, brandingOpts);
-          } else {
-            await linearApi.createComment(issue.id, `**[${label}]** ${responseBody}`);
-          }
-        } catch (brandErr) {
-          api.logger.warn(`Branded comment failed, falling back to prefix: ${brandErr}`);
-          await linearApi.createComment(issue.id, `**[${label}]** ${responseBody}`);
-        }
-
-        // 6. Emit response (closes session)
-        if (agentSessionId) {
-          const truncated = responseBody.length > 2000
-            ? responseBody.slice(0, 2000) + "…"
-            : responseBody;
-          await linearApi.emitActivity(agentSessionId, {
-            type: "response",
-            body: truncated,
-          }).catch(() => {});
-        }
-
-        api.logger.info(`Posted agent response to ${enrichedIssue?.identifier ?? issue.id}`);
-      } catch (err) {
-        api.logger.error(`AppUserNotification handler error: ${err}`);
-        if (agentSessionId) {
-          await linearApi.emitActivity(agentSessionId, {
-            type: "error",
-            body: `Failed to process notification: ${String(err).slice(0, 500)}`,
-          }).catch(() => {});
-        }
-      } finally {
-        clearActiveSession(issue.id);
-      }
-    })();
-
     return true;
   }
 
@@ -330,7 +273,17 @@ export async function handleLinearWebhook(
       return true;
     }
 
-    // Dedup: skip if we already handled this session
+    // Guard: check activeRuns FIRST (O(1), no side effects).
+    // This catches sessions created by our own handlers (Comment dispatch,
+    // Issue triage, handleDispatch) which all set activeRuns BEFORE calling
+    // createSessionOnIssue(). Checking this first prevents the race condition
+    // where the webhook arrives before wasRecentlyProcessed is registered.
+    if (activeRuns.has(issue.id)) {
+      api.logger.info(`Agent already running for ${issue?.identifier ?? issue?.id} — skipping session ${session.id}`);
+      return true;
+    }
+
+    // Secondary dedup: skip if we already handled this exact session ID
     if (wasRecentlyProcessed(`session:${session.id}`)) {
       api.logger.info(`AgentSession ${session.id} already handled — skipping`);
       return true;
@@ -346,13 +299,7 @@ export async function handleLinearWebhook(
     const previousComments = payload.previousComments ?? [];
     const guidance = payload.guidance;
 
-    api.logger.info(`AgentSession created: ${session.id} for issue ${issue?.identifier ?? issue?.id} (comments: ${previousComments.length}, guidance: ${guidance ? "yes" : "no"})`);
-
-    // Guard: skip if an agent run is already active for this issue
-    if (activeRuns.has(issue.id)) {
-      api.logger.info(`Agent already running for ${issue?.identifier ?? issue?.id} — skipping session ${session.id}`);
-      return true;
-    }
+    api.logger.info(`AgentSession created: ${session.id} for issue ${issue?.identifier ?? issue?.id} (comments: ${previousComments.length}, guidance: ${guidance ? "yes" : "no"})`)
 
     // Extract the user's latest message from previousComments
     // The last comment is the most recent user message
@@ -442,31 +389,21 @@ export async function handleLinearWebhook(
           ? result.output
           : `Something went wrong while processing this. The system will retry automatically if possible. If this keeps happening, run \`openclaw openclaw-linear doctor\` to check for issues.`;
 
-        // Post as comment
-        const avatarUrl = defaultProfile?.[1]?.avatarUrl ?? profiles[agentId]?.avatarUrl;
-        const brandingOpts = avatarUrl
-          ? { createAsUser: label, displayIconUrl: avatarUrl }
-          : undefined;
-
-        try {
-          if (brandingOpts) {
-            await linearApi.createComment(issue.id, responseBody, brandingOpts);
-          } else {
-            await linearApi.createComment(issue.id, `**[${label}]** ${responseBody}`);
-          }
-        } catch (brandErr) {
-          api.logger.warn(`Branded comment failed: ${brandErr}`);
-          await linearApi.createComment(issue.id, `**[${label}]** ${responseBody}`);
-        }
-
-        // Emit response (closes session)
-        const truncated = responseBody.length > 2000
-          ? responseBody.slice(0, 2000) + "\u2026"
-          : responseBody;
-        await linearApi.emitActivity(session.id, {
+        // Emit response via session (preferred — avoids duplicate comment).
+        // Fall back to a regular comment only if emitActivity fails.
+        const labeledResponse = `**[${label}]** ${responseBody}`;
+        const emitted = await linearApi.emitActivity(session.id, {
           type: "response",
-          body: truncated,
-        }).catch(() => {});
+          body: labeledResponse,
+        }).then(() => true).catch(() => false);
+
+        if (!emitted) {
+          const avatarUrl = defaultProfile?.[1]?.avatarUrl ?? profiles[agentId]?.avatarUrl;
+          const agentOpts = avatarUrl
+            ? { createAsUser: label, displayIconUrl: avatarUrl }
+            : undefined;
+          await postAgentComment(api, linearApi, issue.id, responseBody, label, agentOpts);
+        }
 
         api.logger.info(`Posted agent response to ${enrichedIssue?.identifier ?? issue.id} (session ${session.id})`);
       } catch (err) {
@@ -620,29 +557,20 @@ export async function handleLinearWebhook(
           ? result.output
           : `Something went wrong while processing this. The system will retry automatically if possible. If this keeps happening, run \`openclaw openclaw-linear doctor\` to check for issues.`;
 
-        const avatarUrl = defaultProfile?.[1]?.avatarUrl ?? profiles[agentId]?.avatarUrl;
-        const brandingOpts = avatarUrl
-          ? { createAsUser: label, displayIconUrl: avatarUrl }
-          : undefined;
-
-        try {
-          if (brandingOpts) {
-            await linearApi.createComment(issue.id, responseBody, brandingOpts);
-          } else {
-            await linearApi.createComment(issue.id, `**[${label}]** ${responseBody}`);
-          }
-        } catch (brandErr) {
-          api.logger.warn(`Branded comment failed: ${brandErr}`);
-          await linearApi.createComment(issue.id, `**[${label}]** ${responseBody}`);
-        }
-
-        const truncated = responseBody.length > 2000
-          ? responseBody.slice(0, 2000) + "\u2026"
-          : responseBody;
-        await linearApi.emitActivity(session.id, {
+        // Emit response via session (preferred). Fall back to comment if it fails.
+        const labeledResponse = `**[${label}]** ${responseBody}`;
+        const emitted = await linearApi.emitActivity(session.id, {
           type: "response",
-          body: truncated,
-        }).catch(() => {});
+          body: labeledResponse,
+        }).then(() => true).catch(() => false);
+
+        if (!emitted) {
+          const avatarUrl = defaultProfile?.[1]?.avatarUrl ?? profiles[agentId]?.avatarUrl;
+          const agentOpts = avatarUrl
+            ? { createAsUser: label, displayIconUrl: avatarUrl }
+            : undefined;
+          await postAgentComment(api, linearApi, issue.id, responseBody, label, agentOpts);
+        }
 
         api.logger.info(`Posted follow-up response to ${enrichedIssue?.identifier ?? issue.id} (session ${session.id})`);
       } catch (err) {
@@ -697,6 +625,14 @@ export async function handleLinearWebhook(
       }
     } catch { /* proceed if viewerId check fails */ }
 
+    // Early guard: skip if an agent run is already active for this issue.
+    // Avoids wasted LLM intent classification (~2-5s) when result would
+    // be discarded anyway by activeRuns check in dispatchCommentToAgent().
+    if (activeRuns.has(issue.id)) {
+      api.logger.info(`Comment on ${issue.identifier ?? issue.id}: active run — skipping`);
+      return true;
+    }
+
     // Load agent profiles
     const profiles = loadAgentProfiles();
     const agentNames = Object.keys(profiles);
@@ -791,7 +727,7 @@ export async function handleLinearWebhook(
           void (async () => {
             try {
               await endPlanningSession(planSession.projectId, "approved", planStatePath);
-              await linearApi.createComment(
+              await createCommentWithDedup(linearApi,
                 planSession.rootIssueId,
                 `## Plan Approved\n\nPlan for **${planSession.projectName}** has been approved. Dispatching to workers.`,
               );
@@ -824,7 +760,7 @@ export async function handleLinearWebhook(
         void (async () => {
           try {
             await endPlanningSession(planSession.projectId, "abandoned", planStatePath);
-            await linearApi.createComment(
+            await createCommentWithDedup(linearApi,
               planSession.rootIssueId,
               `Planning mode ended for **${planSession.projectName}**. Session abandoned.`,
             );
@@ -884,6 +820,16 @@ export async function handleLinearWebhook(
     res.end("ok");
 
     const issue = payload.data;
+
+    // Guard: check activeRuns FIRST (synchronous, O(1)) before any async work.
+    // Linear can send duplicate Issue.update webhooks <20ms apart for the same
+    // assignment change. Without this sync guard, both pass through the async
+    // getViewerId() call before either registers with wasRecentlyProcessed().
+    if (activeRuns.has(issue?.id)) {
+      api.logger.info(`Issue.update ${issue?.identifier ?? issue?.id}: active run — skipping`);
+      return true;
+    }
+
     const updatedFrom = payload.updatedFrom ?? {};
 
     // Check both assigneeId and delegateId — Linear uses delegateId for agent delegation
@@ -921,7 +867,8 @@ export async function handleLinearWebhook(
     const trigger = isDelegatedToUs ? "delegated" : "assigned";
     api.logger.info(`Issue ${trigger} to our app user (${viewerId}), executing pipeline`);
 
-    // Dedup on assignment/delegation
+    // Secondary dedup: catch duplicate webhooks that both passed the activeRuns
+    // check before either could register (belt-and-suspenders with the sync guard).
     const dedupKey = `${trigger}:${issue.id}:${viewerId}`;
     if (wasRecentlyProcessed(dedupKey)) {
       api.logger.info(`${trigger} ${issue.id} -> ${viewerId} already processed — skipping`);
@@ -965,6 +912,14 @@ export async function handleLinearWebhook(
 
     const agentId = resolveAgentId(api);
 
+    // Guard: prevent duplicate runs on same issue (also blocks AgentSessionEvent
+    // webhooks that arrive from sessions we create during triage)
+    if (activeRuns.has(issue.id)) {
+      api.logger.info(`Issue.create: ${issue.identifier ?? issue.id} already has active run — skipping triage`);
+      return true;
+    }
+    activeRuns.add(issue.id);
+
     // Dispatch triage (non-blocking)
     void (async () => {
       const profiles = loadAgentProfiles();
@@ -1031,7 +986,7 @@ export async function handleLinearWebhook(
         if (agentSessionId) {
           await linearApi.emitActivity(agentSessionId, {
             type: "thought",
-            body: `Triaging new issue ${enrichedIssue?.identifier ?? issue.id}...`,
+            body: `${label} is triaging new issue ${enrichedIssue?.identifier ?? issue.id}...`,
           }).catch(() => {});
         }
 
@@ -1087,6 +1042,10 @@ export async function handleLinearWebhook(
           message,
           timeoutMs: 3 * 60_000,
           streaming: agentSessionId ? { linearApi, agentSessionId } : undefined,
+          // Triage is strictly read-only: the agent can read/search the
+          // codebase but all write-capable tools are denied via config
+          // policy.  The only artifacts are a Linear comment + issue updates.
+          readOnly: true,
         });
 
         const responseBody = result.success
@@ -1135,30 +1094,26 @@ export async function handleLinearWebhook(
           }
         }
 
-        // Post branded triage comment
-        const brandingOpts = avatarUrl
-          ? { createAsUser: label, displayIconUrl: avatarUrl }
-          : undefined;
-
-        try {
-          if (brandingOpts) {
-            await linearApi.createComment(issue.id, commentBody, brandingOpts);
-          } else {
-            await linearApi.createComment(issue.id, `**[${label}]** ${commentBody}`);
-          }
-        } catch (brandErr) {
-          api.logger.warn(`Branded comment failed, falling back to prefix: ${brandErr}`);
-          await linearApi.createComment(issue.id, `**[${label}]** ${commentBody}`);
-        }
-
+        // When a session exists, prefer emitActivity (avoids duplicate comment).
+        // Otherwise, post as a regular comment.
         if (agentSessionId) {
-          const truncated = commentBody.length > 2000
-            ? commentBody.slice(0, 2000) + "…"
-            : commentBody;
-          await linearApi.emitActivity(agentSessionId, {
+          const labeledComment = `**[${label}]** ${commentBody}`;
+          const emitted = await linearApi.emitActivity(agentSessionId, {
             type: "response",
-            body: truncated,
-          }).catch(() => {});
+            body: labeledComment,
+          }).then(() => true).catch(() => false);
+
+          if (!emitted) {
+            const agentOpts = avatarUrl
+              ? { createAsUser: label, displayIconUrl: avatarUrl }
+              : undefined;
+            await postAgentComment(api, linearApi, issue.id, commentBody, label, agentOpts);
+          }
+        } else {
+          const agentOpts = avatarUrl
+            ? { createAsUser: label, displayIconUrl: avatarUrl }
+            : undefined;
+          await postAgentComment(api, linearApi, issue.id, commentBody, label, agentOpts);
         }
 
         api.logger.info(`Triage complete for ${enrichedIssue?.identifier ?? issue.id}`);
@@ -1172,6 +1127,7 @@ export async function handleLinearWebhook(
         }
       } finally {
         clearActiveSession(issue.id);
+        activeRuns.delete(issue.id);
       }
     })();
 
@@ -1271,7 +1227,7 @@ async function dispatchCommentToAgent(
     if (agentSessionId) {
       await linearApi.emitActivity(agentSessionId, {
         type: "thought",
-        body: `Processing comment on ${issueRef}...`,
+        body: `${label} is processing comment on ${issueRef}...`,
       }).catch(() => {});
     }
 
@@ -1291,31 +1247,26 @@ async function dispatchCommentToAgent(
       ? result.output
       : `Something went wrong while processing this. The system will retry automatically if possible.`;
 
-    // Post branded comment
-    const brandingOpts = avatarUrl
-      ? { createAsUser: label, displayIconUrl: avatarUrl }
-      : undefined;
-
-    try {
-      if (brandingOpts) {
-        await linearApi.createComment(issue.id, responseBody, brandingOpts);
-      } else {
-        await linearApi.createComment(issue.id, `**[${label}]** ${responseBody}`);
-      }
-    } catch (brandErr) {
-      api.logger.warn(`Branded comment failed, falling back to prefix: ${brandErr}`);
-      await linearApi.createComment(issue.id, `**[${label}]** ${responseBody}`);
-    }
-
-    // Emit response (closes session)
+    // When a session exists, prefer emitActivity (avoids duplicate comment).
+    // Otherwise, post as a regular comment.
     if (agentSessionId) {
-      const truncated = responseBody.length > 2000
-        ? responseBody.slice(0, 2000) + "…"
-        : responseBody;
-      await linearApi.emitActivity(agentSessionId, {
+      const labeledResponse = `**[${label}]** ${responseBody}`;
+      const emitted = await linearApi.emitActivity(agentSessionId, {
         type: "response",
-        body: truncated,
-      }).catch(() => {});
+        body: labeledResponse,
+      }).then(() => true).catch(() => false);
+
+      if (!emitted) {
+        const agentOpts = avatarUrl
+          ? { createAsUser: label, displayIconUrl: avatarUrl }
+          : undefined;
+        await postAgentComment(api, linearApi, issue.id, responseBody, label, agentOpts);
+      }
+    } else {
+      const agentOpts = avatarUrl
+        ? { createAsUser: label, displayIconUrl: avatarUrl }
+        : undefined;
+      await postAgentComment(api, linearApi, issue.id, responseBody, label, agentOpts);
     }
 
     api.logger.info(`Posted ${agentId} response to ${issueRef}`);
@@ -1361,7 +1312,7 @@ async function handleDispatch(
       const planState = await readPlanningState(planStatePath);
       if (isInPlanningMode(planState, planProjectId)) {
         api.logger.info(`dispatch: ${identifier} is in planning-mode project — skipping`);
-        await linearApi.createComment(
+        await createCommentWithDedup(linearApi,
           issue.id,
           `**Can't dispatch yet** — this project is in planning mode.\n\n**To continue:** Comment on the planning issue with your requirements, then say **"finalize plan"** when ready.\n\n**To cancel planning:** Comment **"abandon"** on the planning issue.`,
         );
@@ -1384,7 +1335,7 @@ async function handleDispatch(
     if (!isStale && inMemory) {
       // Truly still running in this gateway process
       api.logger.info(`dispatch: ${identifier} actively running (status: ${existing.status}, age: ${Math.round(ageMs / 1000)}s) — skipping`);
-      await linearApi.createComment(
+      await createCommentWithDedup(linearApi,
         issue.id,
         `**Already running** as **${existing.tier}** — status: **${existing.status}**, started ${Math.round(ageMs / 60_000)}m ago.\n\nWorktree: \`${existing.worktreePath}\`\n\n**Options:**\n- Check progress: \`/dispatch status ${identifier}\`\n- Force restart: \`/dispatch retry ${identifier}\` (only works when stuck)\n- Escalate: \`/dispatch escalate ${identifier} "reason"\``,
       );
@@ -1456,7 +1407,7 @@ async function handleDispatch(
     }
   } catch (err) {
     api.logger.error(`@dispatch: worktree creation failed: ${err}`);
-    await linearApi.createComment(
+    await createCommentWithDedup(linearApi,
       issue.id,
       `**Dispatch failed** — couldn't create the worktree.\n\n> ${String(err).slice(0, 200)}\n\n**What to try:**\n- Check that the base repo exists\n- Re-assign this issue to try again\n- Check logs: \`journalctl --user -u openclaw-gateway --since "5 min ago"\``,
     );
@@ -1481,6 +1432,9 @@ async function handleDispatch(
   }
 
   // 6. Create agent session on Linear
+  // Mark active BEFORE session creation so that any AgentSessionEvent.created
+  // webhook arriving from this call is blocked by the activeRuns guard.
+  activeRuns.add(issue.id);
   let agentSessionId: string | undefined;
   try {
     const sessionResult = await linearApi.createSessionOnIssue(issue.id);
@@ -1557,7 +1511,7 @@ async function handleDispatch(
     `- All dispatches: \`/dispatch list\``,
   ].join("\n");
 
-  await linearApi.createComment(issue.id, statusComment);
+  await createCommentWithDedup(linearApi, issue.id, statusComment);
 
   if (agentSessionId) {
     await linearApi.emitActivity(agentSessionId, {
@@ -1583,7 +1537,7 @@ async function handleDispatch(
   }
 
   // 11. Run v2 pipeline: worker → audit → verdict (non-blocking)
-  activeRuns.add(issue.id);
+  // (activeRuns already set in step 6 above)
 
   // Instantiate notifier (Discord, Slack, or both — config-driven)
   const notify: NotifyFn = createNotifierFromConfig(pluginConfig, api.runtime, api);