@desplega.ai/agent-swarm 1.70.0 → 1.71.1

package/src/jira/adf.ts

@@ -0,0 +1,132 @@
+/**
+ * Atlassian Document Format (ADF) walker.
+ *
+ * Jira REST v3 returns rich-text fields (issue descriptions, comment bodies)
+ * as ADF JSON trees. We need plaintext for prompt rendering and structured
+ * mention extraction for bot-mention detection on inbound webhooks.
+ *
+ * Reference: https://developer.atlassian.com/cloud/jira/platform/apis/document/structure/
+ *
+ * Supported node types: paragraph, heading, bulletList, orderedList, listItem,
+ * text, mention, hardBreak, codeBlock, blockquote. Unknown types descend into
+ * `content` if present, else are skipped silently. In non-prod environments a
+ * debug line is emitted so unhandled cases surface during dev.
+ */
+
+type AdfNode = {
+  type?: string;
+  text?: string;
+  content?: unknown[];
+  attrs?: Record<string, unknown>;
+};
+
+function isNode(value: unknown): value is AdfNode {
+  return !!value && typeof value === "object";
+}
+
+function asNodeArray(value: unknown): AdfNode[] {
+  if (!Array.isArray(value)) return [];
+  return value.filter(isNode);
+}
+
+/**
+ * Recursively concatenate text from an ADF tree. Mentions are inlined as
+ * `@<displayName>` (or `@<accountId>` if no displayName is present).
+ *
+ * Block-level nodes insert a trailing newline so consecutive paragraphs render
+ * as separate lines. Hard breaks and list items also produce newlines.
+ */
+export function extractText(adf: unknown): string {
+  if (!isNode(adf)) return "";
+
+  const out: string[] = [];
+
+  const visit = (node: AdfNode): void => {
+    const type = typeof node.type === "string" ? node.type : "";
+
+    switch (type) {
+      case "text": {
+        if (typeof node.text === "string") out.push(node.text);
+        return;
+      }
+      case "mention": {
+        const attrs = node.attrs ?? {};
+        const text = typeof attrs.text === "string" ? attrs.text : null;
+        const id = typeof attrs.id === "string" ? attrs.id : null;
+        const display = text ?? id ?? "";
+        // Atlassian mention `text` already starts with "@" sometimes; normalize
+        // to a single leading "@".
+        out.push(display.startsWith("@") ? display : `@${display}`);
+        return;
+      }
+      case "hardBreak": {
+        out.push("\n");
+        return;
+      }
+      case "paragraph":
+      case "heading":
+      case "blockquote":
+      case "codeBlock": {
+        for (const child of asNodeArray(node.content)) visit(child);
+        out.push("\n");
+        return;
+      }
+      case "bulletList":
+      case "orderedList": {
+        for (const child of asNodeArray(node.content)) visit(child);
+        return;
+      }
+      case "listItem": {
+        out.push("- ");
+        for (const child of asNodeArray(node.content)) visit(child);
+        // Block children inside a listItem already trail a newline, so we don't
+        // double-add. But if the listItem only contained inline content, ensure
+        // we end on a newline.
+        if (out.length > 0 && !out[out.length - 1]?.endsWith("\n")) {
+          out.push("\n");
+        }
+        return;
+      }
+      case "doc": {
+        for (const child of asNodeArray(node.content)) visit(child);
+        return;
+      }
+      default: {
+        // Unknown node — descend into content if present.
+        if (process.env.NODE_ENV !== "production" && type) {
+          console.log(`[jira.adf] unknown node type: ${type}`);
+        }
+        for (const child of asNodeArray(node.content)) visit(child);
+        return;
+      }
+    }
+  };
+
+  visit(adf);
+
+  // Collapse trailing whitespace, preserve internal newlines.
+  return out.join("").replace(/\n+$/g, "");
+}
+
+/**
+ * Collect Atlassian `accountId` values from every `mention` node in the tree.
+ * Returns an empty array when no mentions exist or the input is malformed.
+ */
+export function extractMentions(adf: unknown): string[] {
+  if (!isNode(adf)) return [];
+
+  const ids: string[] = [];
+
+  const visit = (node: AdfNode): void => {
+    if (node.type === "mention") {
+      const id = node.attrs?.id;
+      if (typeof id === "string" && id.length > 0) ids.push(id);
+      return;
+    }
+    for (const child of asNodeArray(node.content)) visit(child);
+  };
+
+  visit(adf);
+
+  return ids;
+}

package/src/jira/app.ts

@@ -0,0 +1,83 @@
+import { upsertOAuthApp } from "../be/db-queries/oauth";
+import { initJiraOutboundSync, teardownJiraOutboundSync } from "./outbound";
+// Side-effect import: registers all Jira event templates in the in-memory
+// registry at module load time (mirrors `src/linear/templates.ts`).
+import "./templates";
+import { resetBotAccountIdCache } from "./sync";
+import { startJiraWebhookKeepalive, stopJiraWebhookKeepalive } from "./webhook-lifecycle";
+
+let initialized = false;
+
+export function isJiraEnabled(): boolean {
+  const disabled = process.env.JIRA_DISABLE;
+  if (disabled === "true" || disabled === "1") return false;
+  const enabled = process.env.JIRA_ENABLED;
+  if (enabled === "false" || enabled === "0") return false;
+  return !!process.env.JIRA_CLIENT_ID;
+}
+
+export function resetJira(): void {
+  // Phase 3: drop the cached bot accountId so a reconnect as a different
+  // Atlassian user re-resolves identity on the next inbound webhook.
+  resetBotAccountIdCache();
+  teardownJiraOutboundSync();
+  stopJiraWebhookKeepalive();
+  initialized = false;
+}
+
+export function initJira(): boolean {
+  if (initialized) return isJiraEnabled();
+  initialized = true;
+
+  if (!isJiraEnabled()) {
+    console.log("[Jira] Integration disabled or JIRA_CLIENT_ID not set");
+    return false;
+  }
+
+  const clientId = process.env.JIRA_CLIENT_ID!;
+  const clientSecret = process.env.JIRA_CLIENT_SECRET ?? "";
+  const redirectUri =
+    process.env.JIRA_REDIRECT_URI ??
+    `http://localhost:${process.env.PORT || "3013"}/api/trackers/jira/callback`;
+
+  upsertOAuthApp("jira", {
+    clientId,
+    clientSecret,
+    authorizeUrl: "https://auth.atlassian.com/authorize",
+    tokenUrl: "https://auth.atlassian.com/oauth/token",
+    redirectUri,
+    // Atlassian uses space-separated scopes (NOT comma-separated like Linear).
+    // We persist them as-stored; the OAuth wrapper splits on "," so we keep
+    // commas here and the wrapper.ts join(",") will recombine — see oauth.ts
+    // where we override scopes from the comma-stored value back to spaces in
+    // the authorize URL via the standard `scopes` array path.
+    scopes: "read:jira-work,write:jira-work,manage:jira-webhook,offline_access,read:me",
+    // Intentionally omit metadata: cloudId/siteUrl/webhookIds are written by
+    // the OAuth callback + webhook-register flows. upsertOAuthApp preserves
+    // existing metadata on UPDATE when not passed.
+  });
+
+  initJiraOutboundSync();
+  startJiraWebhookKeepalive();
+
+  warnIfMcpBaseUrlLooksLikeAppUrl();
+
+  console.log("[Jira] Integration initialized");
+  return true;
+}
+
+/**
+ * Soft sanity check for `MCP_BASE_URL`. If it equals `APP_URL` (a common
+ * misconfig that points the webhook URL at the dashboard host), warn loudly
+ * so the operator can fix the env. We don't fail boot — Atlassian will just
+ * 404 webhook deliveries until corrected.
+ */
+function warnIfMcpBaseUrlLooksLikeAppUrl(): void {
+  const mcp = process.env.MCP_BASE_URL?.trim().replace(/\/+$/, "");
+  const app = process.env.APP_URL?.trim().replace(/\/+$/, "");
+  if (mcp && app && mcp === app) {
+    console.warn(
+      `[Jira] WARNING: MCP_BASE_URL (${mcp}) equals APP_URL — registered webhook URLs will hit the dashboard host, not the API. Atlassian will likely 404 webhook deliveries. Point MCP_BASE_URL at the API server.`,
+    );
+  }
+}

package/src/jira/client.ts

@@ -0,0 +1,82 @@
+import { getOAuthTokens } from "../be/db-queries/oauth";
+import { ensureToken } from "../oauth/ensure-token";
+import { getJiraMetadata } from "./metadata";
+
+/**
+ * Resolve a fresh Jira access token (refreshes if expiring soon).
+ *
+ * Throws if no tokens are stored — callers should treat this as "not yet
+ * connected" rather than a programmer error.
+ */
+export async function getJiraAccessToken(): Promise<string> {
+  await ensureToken("jira");
+  const tokens = getOAuthTokens("jira");
+  if (!tokens) {
+    throw new Error("Jira not connected — no OAuth tokens stored");
+  }
+  return tokens.accessToken;
+}
+
+/**
+ * Resolve the current workspace `cloudId` from `oauth_apps.metadata`.
+ *
+ * Throws if the OAuth callback hasn't completed yet (no cloudId persisted).
+ */
+export function getJiraCloudId(): string {
+  const meta = getJiraMetadata();
+  if (!meta.cloudId) {
+    throw new Error("Jira cloudId not resolved — complete OAuth before calling Jira REST API");
+  }
+  return meta.cloudId;
+}
+
+/**
+ * Typed fetch wrapper for the Atlassian Jira REST API.
+ *
+ * - Prepends `https://api.atlassian.com/ex/jira/{cloudId}` to `path`.
+ * - Sets `Authorization: Bearer <token>` and `Accept: application/json`.
+ * - Sets `Content-Type: application/json` when a body is provided.
+ * - On 401: refreshes the token (forced via `ensureToken("jira", 0)`) and
+ *   retries once.
+ * - On 429: respects `Retry-After` (in seconds) with a single retry.
+ *
+ * Returns the raw `Response` — callers handle `response.json()`/`response.text()`
+ * themselves so we don't impose a parse contract.
+ */
+export async function jiraFetch(path: string, init?: RequestInit): Promise<Response> {
+  if (!path.startsWith("/")) {
+    throw new Error(`jiraFetch path must start with '/' — got: ${path}`);
+  }
+
+  const send = async (token: string): Promise<Response> => {
+    const cloudId = getJiraCloudId();
+    const url = `https://api.atlassian.com/ex/jira/${cloudId}${path}`;
+    const headers = new Headers(init?.headers);
+    headers.set("Authorization", `Bearer ${token}`);
+    if (!headers.has("Accept")) headers.set("Accept", "application/json");
+    if (init?.body && !headers.has("Content-Type")) {
+      headers.set("Content-Type", "application/json");
+    }
+    return fetch(url, { ...init, headers });
+  };
+
+  let token = await getJiraAccessToken();
+  let response = await send(token);
+
+  if (response.status === 401) {
+    // Force refresh — bufferMs=0 means "always refresh if any expiry is set"
+    await ensureToken("jira", 0);
+    token = await getJiraAccessToken();
+    response = await send(token);
+  }
+
+  if (response.status === 429) {
+    const retryAfterRaw = response.headers.get("Retry-After");
+    const retryAfter = retryAfterRaw ? Number.parseInt(retryAfterRaw, 10) : NaN;
+    const delayMs = Number.isFinite(retryAfter) && retryAfter > 0 ? retryAfter * 1000 : 1000;
+    await new Promise((resolve) => setTimeout(resolve, delayMs));
+    response = await send(token);
+  }
+
+  return response;
+}

package/src/jira/index.ts

@@ -0,0 +1,24 @@
+export { extractMentions, extractText } from "./adf";
+export { initJira, isJiraEnabled, resetJira } from "./app";
+export {
+  handleCommentEvent,
+  handleIssueDeleteEvent,
+  handleIssueEvent,
+  resetBotAccountIdCache,
+  resolveBotAccountId,
+} from "./sync";
+export {
+  handleJiraWebhook,
+  isDuplicateDelivery,
+  markDelivery,
+  synthesizeDeliveryId,
+  verifyJiraWebhookToken,
+} from "./webhook";
+export type { RegisterJiraWebhookResult } from "./webhook-lifecycle";
+export {
+  deleteJiraWebhook,
+  refreshJiraWebhooks,
+  registerJiraWebhook,
+  startJiraWebhookKeepalive,
+  stopJiraWebhookKeepalive,
+} from "./webhook-lifecycle";

package/src/jira/metadata.ts

@@ -0,0 +1,117 @@
+import { getDb } from "../be/db";
+import { getOAuthApp } from "../be/db-queries/oauth";
+import type { JiraOAuthAppMetadata } from "./types";
+
+/**
+ * Read the typed metadata blob for the `jira` provider.
+ *
+ * Falls back to an empty object if the provider row doesn't exist or the
+ * metadata column is unparseable JSON. We never throw on shape coercion —
+ * the keys are all optional and downstream callers already null-check.
+ */
+export function getJiraMetadata(): JiraOAuthAppMetadata {
+  const app = getOAuthApp("jira");
+  if (!app) return {};
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(app.metadata || "{}");
+  } catch {
+    return {};
+  }
+
+  if (!parsed || typeof parsed !== "object") return {};
+
+  const meta = parsed as Record<string, unknown>;
+  const out: JiraOAuthAppMetadata = {};
+
+  if (typeof meta.cloudId === "string") out.cloudId = meta.cloudId;
+  if (typeof meta.siteUrl === "string") out.siteUrl = meta.siteUrl;
+  if (Array.isArray(meta.webhookIds)) {
+    out.webhookIds = meta.webhookIds.filter(
+      (entry): entry is { id: number; expiresAt: string; jql: string } =>
+        !!entry &&
+        typeof entry === "object" &&
+        typeof (entry as { id?: unknown }).id === "number" &&
+        typeof (entry as { expiresAt?: unknown }).expiresAt === "string" &&
+        typeof (entry as { jql?: unknown }).jql === "string",
+    );
+  }
+
+  return out;
+}
+
+/**
+ * Read-modify-write merge of the Jira `oauth_apps.metadata` blob.
+ *
+ * Wrapped in a single SQLite transaction so concurrent writers can't stomp
+ * each other's keys (e.g. Phase 2 cloudId write + Phase 5 webhookIds write).
+ *
+ * Merge semantics:
+ *   - Scalar keys (`cloudId`, `siteUrl`): shallow merge — partial overwrites
+ *     existing value if defined.
+ *   - `webhookIds`: id-keyed merge — entries in `partial.webhookIds` replace
+ *     existing entries with the same `id`, untouched ids are preserved.
+ *
+ * Throws if the `jira` provider row doesn't exist (caller must run `initJira()`
+ * before any metadata writes).
+ */
+export function updateJiraMetadata(partial: Partial<JiraOAuthAppMetadata>): void {
+  const db = getDb();
+  const txn = db.transaction(() => {
+    const row = db.query("SELECT metadata FROM oauth_apps WHERE provider = 'jira'").get() as {
+      metadata: string | null;
+    } | null;
+
+    if (!row) {
+      throw new Error(
+        "[jira.metadata] oauth_apps row missing for provider='jira' — call initJira() first",
+      );
+    }
+
+    let current: JiraOAuthAppMetadata = {};
+    try {
+      const parsed = JSON.parse(row.metadata || "{}");
+      if (parsed && typeof parsed === "object") {
+        current = parsed as JiraOAuthAppMetadata;
+      }
+    } catch {
+      // Fall through with empty object
+    }
+
+    const merged: JiraOAuthAppMetadata = { ...current };
+
+    if (partial.cloudId !== undefined) merged.cloudId = partial.cloudId;
+    if (partial.siteUrl !== undefined) merged.siteUrl = partial.siteUrl;
+
+    if (partial.webhookIds !== undefined) {
+      const byId = new Map<number, { id: number; expiresAt: string; jql: string }>();
+      for (const existing of current.webhookIds ?? []) {
+        byId.set(existing.id, existing);
+      }
+      for (const incoming of partial.webhookIds) {
+        byId.set(incoming.id, incoming);
+      }
+      merged.webhookIds = [...byId.values()];
+    }
+
+    db.query(
+      "UPDATE oauth_apps SET metadata = ?, updatedAt = strftime('%Y-%m-%dT%H:%M:%fZ', 'now') WHERE provider = 'jira'",
+    ).run(JSON.stringify(merged));
+  });
+
+  txn();
+}
+
+/**
+ * Reset the Jira `oauth_apps.metadata` blob to `{}`. Used by the disconnect
+ * flow to drop cloudId, siteUrl, and webhookIds in one shot. The row itself
+ * stays — `initJira()` requires the `oauth_apps` row to exist.
+ */
+export function clearJiraMetadata(): void {
+  getDb()
+    .query(
+      "UPDATE oauth_apps SET metadata = '{}', updatedAt = strftime('%Y-%m-%dT%H:%M:%fZ', 'now') WHERE provider = 'jira'",
+    )
+    .run();
+}

package/src/jira/oauth.ts

@@ -0,0 +1,98 @@
+import { getOAuthApp } from "../be/db-queries/oauth";
+import { buildAuthorizationUrl, exchangeCode, type OAuthProviderConfig } from "../oauth/wrapper";
+import { updateJiraMetadata } from "./metadata";
+import type { JiraAccessibleResource } from "./types";
+
+const ACCESSIBLE_RESOURCES_URL = "https://api.atlassian.com/oauth/token/accessible-resources";
+
+/**
+ * Build the OAuth provider config for the generic wrapper.
+ *
+ * - `audience=api.atlassian.com` is required by the Atlassian 3LO flow.
+ * - We intentionally OMIT `prompt: "consent"`: forcing consent on every reconnect
+ *   is UX noise. Atlassian's default (skip consent if scopes haven't changed)
+ *   is what we want. (Plan errata I6.)
+ * - `scopeSeparator: " "` is critical — Atlassian wants space-separated scopes
+ *   per RFC 6749, unlike Linear which requires commas.
+ */
+export function getJiraOAuthConfig(): OAuthProviderConfig | null {
+  const app = getOAuthApp("jira");
+  if (!app) return null;
+
+  return {
+    provider: "jira",
+    clientId: app.clientId,
+    clientSecret: app.clientSecret,
+    authorizeUrl: app.authorizeUrl,
+    tokenUrl: app.tokenUrl,
+    redirectUri: app.redirectUri,
+    scopes: app.scopes.split(","),
+    scopeSeparator: " ",
+    extraParams: { audience: "api.atlassian.com" },
+  };
+}
+
+export async function getJiraAuthorizationUrl(): Promise<string | null> {
+  const config = getJiraOAuthConfig();
+  if (!config) return null;
+  const result = await buildAuthorizationUrl(config);
+  return result.url;
+}
+
+/**
+ * Handle the OAuth callback: exchange the authorization code for tokens (which
+ * `exchangeCode` persists via storeOAuthTokens), then resolve the workspace
+ * `cloudId` via the Atlassian accessible-resources endpoint and persist it
+ * into `oauth_apps.metadata`.
+ *
+ * v1 single-workspace constraint: we always pick the first resource and throw
+ * if the list is empty. Multi-workspace is a v2 concern.
+ */
+export async function handleJiraCallback(
+  code: string,
+  state: string,
+): Promise<{
+  accessToken: string;
+  refreshToken?: string;
+  expiresIn?: number;
+  scope?: string;
+  cloudId: string;
+  siteUrl: string;
+}> {
+  const config = getJiraOAuthConfig();
+  if (!config) throw new Error("Jira OAuth not configured");
+
+  const tokens = await exchangeCode(config, code, state);
+
+  const response = await fetch(ACCESSIBLE_RESOURCES_URL, {
+    headers: {
+      Authorization: `Bearer ${tokens.accessToken}`,
+      Accept: "application/json",
+    },
+  });
+
+  if (!response.ok) {
+    const errorText = await response.text();
+    throw new Error(`Jira accessible-resources fetch failed (${response.status}): ${errorText}`);
+  }
+
+  const resources = (await response.json()) as JiraAccessibleResource[];
+  if (!Array.isArray(resources) || resources.length === 0) {
+    throw new Error(
+      "Jira OAuth completed but no accessible resources returned — does the consenting user have access to any Jira site?",
+    );
+  }
+
+  const first = resources[0];
+  if (!first || typeof first.id !== "string" || typeof first.url !== "string") {
+    throw new Error("Jira accessible-resources returned malformed entry (missing id/url)");
+  }
+
+  updateJiraMetadata({ cloudId: first.id, siteUrl: first.url });
+
+  return {
+    ...tokens,
+    cloudId: first.id,
+    siteUrl: first.url,
+  };
+}

package/src/jira/outbound.ts

@@ -0,0 +1,155 @@
+import { getTrackerSync, updateTrackerSync } from "../be/db-queries/tracker";
+import { workflowEventBus } from "../workflows/event-bus";
+import { jiraFetch } from "./client";
+
+let subscribed = false;
+
+const LOOP_PREVENTION_WINDOW_MS = 5_000;
+const OUTPUT_TRUNCATE_CHARS = 4000;
+
+/**
+ * Subscribe Jira outbound sync to swarm task lifecycle events.
+ *
+ * For each event, looks up the `tracker_sync` row keyed on
+ * `(provider="jira", entityType="task", swarmId=<taskId>)`. If the task
+ * originated from a Jira issue, posts a plaintext comment via REST v2 to that
+ * issue, then flips `lastSyncOrigin → "swarm"` so the inbound webhook can
+ * skip the just-posted comment.
+ *
+ * Tasks WITHOUT a `tracker_sync` row (most swarm tasks) are silently ignored —
+ * the sync row's existence is the gate for "this task came from Jira and should
+ * post lifecycle updates back".
+ *
+ * Idempotent — calling twice is a no-op.
+ *
+ * Rate-limiting (v1): we rely on `jiraFetch`'s built-in 429 retry-with-
+ * `Retry-After` (single retry). If 100+ tasks complete simultaneously across
+ * many issues we may exhaust the retry budget and lose comments. Documented
+ * as a known v1 limitation; a per-issue debounce / bounded outbound queue
+ * could be added in v2 if it becomes a real problem.
+ */
+export function initJiraOutboundSync(): void {
+  if (subscribed) return;
+  subscribed = true;
+
+  workflowEventBus.on("task.created", handleTaskCreated);
+  workflowEventBus.on("task.completed", handleTaskCompleted);
+  workflowEventBus.on("task.failed", handleTaskFailed);
+  workflowEventBus.on("task.cancelled", handleTaskCancelled);
+  console.log("[Jira] Outbound sync subscribed to event bus");
+}
+
+export function teardownJiraOutboundSync(): void {
+  if (!subscribed) return;
+  subscribed = false;
+
+  workflowEventBus.off("task.created", handleTaskCreated);
+  workflowEventBus.off("task.completed", handleTaskCompleted);
+  workflowEventBus.off("task.failed", handleTaskFailed);
+  workflowEventBus.off("task.cancelled", handleTaskCancelled);
+  console.log("[Jira] Outbound sync unsubscribed from event bus");
+}
+
+async function handleTaskCreated(data: unknown): Promise<void> {
+  const { taskId, task } = data as { taskId?: string; task?: string };
+  if (!taskId) return;
+
+  const summary = (task ?? "").trim();
+  // Use Unicode emoji directly — Jira REST v2 plaintext bodies do NOT expand
+  // shortcode forms like `:rocket:` (verified in Phase 3 manual testing).
+  const body = summary ? `🚀 Swarm task started: ${summary}` : "🚀 Swarm task started.";
+
+  await postLifecycleComment(taskId, "task.created", body);
+}
+
+async function handleTaskCompleted(data: unknown): Promise<void> {
+  const { taskId, output } = data as { taskId?: string; output?: string };
+  if (!taskId) return;
+
+  const trimmed = (output ?? "").slice(0, OUTPUT_TRUNCATE_CHARS);
+  const ellipsized = output && output.length > OUTPUT_TRUNCATE_CHARS ? `${trimmed}…` : trimmed;
+  const body = ellipsized
+    ? `✅ Swarm task completed.\n\n${ellipsized}`
+    : "✅ Swarm task completed.";
+
+  await postLifecycleComment(taskId, "task.completed", body);
+}
+
+async function handleTaskFailed(data: unknown): Promise<void> {
+  const { taskId, failureReason } = data as {
+    taskId?: string;
+    failureReason?: string;
+  };
+  if (!taskId) return;
+
+  const reason = failureReason ?? "(no failure reason recorded)";
+  const body = `❌ Swarm task failed.\n\n${reason}`;
+
+  await postLifecycleComment(taskId, "task.failed", body);
+}
+
+async function handleTaskCancelled(data: unknown): Promise<void> {
+  const { taskId } = data as { taskId?: string };
+  if (!taskId) return;
+
+  await postLifecycleComment(taskId, "task.cancelled", "⛔ Swarm task cancelled.");
+}
+
+async function postLifecycleComment(
+  taskId: string,
+  eventName: string,
+  body: string,
+): Promise<void> {
+  const sync = getTrackerSync("jira", "task", taskId);
+  if (!sync) return;
+
+  if (shouldSkipForLoopPrevention(sync)) {
+    console.log(
+      `[Jira Outbound] Skipping ${eventName} for task ${taskId} — recent external sync (loop prevention)`,
+    );
+    return;
+  }
+
+  // Prefer the readable key (e.g. "KAN-1") over the numeric issue id; both
+  // work with the REST v2 comment endpoint, but the key is what users see in
+  // logs.
+  const issueRef = sync.externalIdentifier ?? sync.externalId;
+
+  try {
+    const response = await jiraFetch(`/rest/api/2/issue/${issueRef}/comment`, {
+      method: "POST",
+      body: JSON.stringify({ body }),
+    });
+
+    if (!response.ok) {
+      const text = await response.text().catch(() => "<unreadable body>");
+      console.error(
+        `[Jira Outbound] Failed to post ${eventName} comment for task ${taskId} → ${issueRef}: HTTP ${response.status} ${text}`,
+      );
+      // Don't update tracker_sync on failure — leave the prior origin/timestamp
+      // intact so a subsequent event isn't loop-suppressed by a partial write.
+      return;
+    }
+
+    updateTrackerSync(sync.id, {
+      lastSyncOrigin: "swarm",
+      lastSyncedAt: new Date().toISOString(),
+    });
+    console.log(`[Jira Outbound] Posted ${eventName} comment for task ${taskId} → ${issueRef}`);
+  } catch (error) {
+    console.error(
+      `[Jira Outbound] Error posting ${eventName} comment for task ${taskId} → ${issueRef}:`,
+      error instanceof Error ? error.message : error,
+    );
+  }
+}
+
+function shouldSkipForLoopPrevention(sync: {
+  lastSyncOrigin: string | null;
+  lastSyncedAt: string;
+}): boolean {
+  if (sync.lastSyncOrigin !== "external") return false;
+  const lastSyncTime = new Date(sync.lastSyncedAt).getTime();
+  if (Number.isNaN(lastSyncTime)) return false;
+  return Date.now() - lastSyncTime < LOOP_PREVENTION_WINDOW_MS;
+}