@desplega.ai/agent-swarm 1.157.0 → 1.158.0

package/src/http/sessions.ts

@@ -1,10 +1,10 @@
 import type { IncomingMessage, ServerResponse } from "node:http";
 import { z } from "zod";
 import { countSessions, getRootTaskChain, getTaskById, listRecentSessions } from "../be/db";
-import { getTaskSteeringFields } from "../be/steering";
-import { getTaskCitations, TaskCitationSchema } from "../be/task-citations";
+import { getTaskSteeringFieldsForTasks } from "../be/steering";
+import { getTaskCitationsForTasks, TaskCitationSchema } from "../be/task-citations";
 import { mintSessionToken, revokeSessionToken } from "../be/users";
-import { AgentTaskSchema, AgentTaskStatusSchema, SteerModeSchema } from "../types";
+import { type AgentTask, AgentTaskSchema, AgentTaskStatusSchema, SteerModeSchema } from "../types";
 import { getRequestAuth } from "../utils/request-auth-context";
 import { route } from "./route-def";
 import { jsonError } from "./utils";
@@ -144,6 +144,12 @@ const listSessions = route({
      * excluded. Omit to return every session (legacy / non-UI callers).
      */
     requestedByUserId: z.string().min(1).optional(),
+    /**
+     * When present, restrict results to root tasks whose `contextKey` starts
+     * with this literal prefix. The UI contextual session panel passes its page
+     * key plus a trailing `:` (e.g. `task:ui:workflow:abc:`).
+     */
+    contextKeyPrefix: z.string().min(1).optional(),
     /** `full` restores the legacy shape (full root `AgentTask`); default is slim. */
     fields: z.enum(["full", "slim"]).optional(),
   }),
@@ -235,18 +241,20 @@ export async function handleSessions(
       source: sources,
       q: parsed.query.q,
       requestedByUserId: parsed.query.requestedByUserId,
+      contextKeyPrefix: parsed.query.contextKeyPrefix,
     };
     // List responses default to slim (root is a task summary); `?fields=full` restores it.
     const sessions =
       parsed.query.fields === "full"
         ? await listRecentSessions(baseOpts)
         : await listRecentSessions({ ...baseOpts, slim: true });
-    // Filter-aware total: same `source`/`q`/`requestedByUserId` WHERE as the
-    // list query, so the UI pager reflects the filtered result set.
+    // Filter-aware total: same WHERE as the list query, so the UI pager
+    // reflects the filtered result set.
     const total = await countSessions({
       source: sources,
       q: parsed.query.q,
       requestedByUserId: parsed.query.requestedByUserId,
+      contextKeyPrefix: parsed.query.contextKeyPrefix,
     });
     listSessions.respond(res, 200, {
       sessions,
@@ -266,20 +274,19 @@ export async function handleSessions(
       return true;
     }
     const chain = await getRootTaskChain(parsed.params.rootTaskId);
-    getSession.respond(res, 200, {
-      root: {
-        ...root,
-        ...(await getTaskSteeringFields(root)),
-        citations: await getTaskCitations(root.id),
-      },
-      chain: await Promise.all(
-        chain.map(async (task) => ({
-          ...task,
-          ...(await getTaskSteeringFields(task)),
-          citations: await getTaskCitations(task.id),
-        })),
-      ),
+    // Fixed query count regardless of chain length: one agents lookup and one
+    // citations lookup for the whole chain (chunked past 500 ids).
+    const tasks = [root, ...chain];
+    const [steering, citations] = await Promise.all([
+      getTaskSteeringFieldsForTasks(tasks),
+      getTaskCitationsForTasks(tasks.map((task) => task.id)),
+    ]);
+    const decorate = (task: AgentTask) => ({
+      ...task,
+      ...steering.get(task.id)!,
+      citations: citations.get(task.id)!,
     });
+    getSession.respond(res, 200, { root: decorate(root), chain: chain.map(decorate) });
     return true;
   }
 

package/src/http/stats.ts

@@ -18,6 +18,7 @@ import { AgentLogSchema, ScheduledTaskSchema, ServiceSchema } from "../types";
 import { isMultiRuntimeEnabled } from "../utils/multi-runtime";
 import { resolveHttpFavoriteOwner } from "./favorite-owner";
 import { route } from "./route-def";
+import { scheduleSummaryWithFavoriteSchema } from "./schedules";
 
 // ─── Response schemas ────────────────────────────────────────────────────────
 
@@ -183,6 +184,8 @@ const listScheduledTasks = route({
   path: "/api/scheduled-tasks",
   pattern: ["api", "scheduled-tasks"],
   summary: "List scheduled tasks",
+  description:
+    "Returns full schedules by default. Pass `fields=slim` for the list-view shape, which swaps the full `taskTemplate` for a bounded `taskTemplatePreview`. Fetch one schedule in full via `GET /api/schedules/{id}`.",
   tags: ["Stats"],
   query: z.object({
     enabled: z.enum(["true", "false"]).optional(),
@@ -192,11 +195,18 @@ const listScheduledTasks = route({
     targetType: z.enum(["agent-task", "workflow", "script"]).optional(),
     workflowId: z.string().uuid().optional(),
     scriptName: z.string().optional(),
+    /** `slim` is the list-view shape (no full `taskTemplate`); default is full. */
+    fields: z.enum(["full", "slim"]).optional(),
   }),
   responses: {
     200: {
       description: "Scheduled tasks list",
-      schema: z.object({ scheduledTasks: z.array(ScheduledTaskSchema) }),
+      schema: z.object({
+        scheduledTasks: z.union([
+          z.array(ScheduledTaskSchema),
+          z.array(scheduleSummaryWithFavoriteSchema),
+        ]),
+      }),
     },
   },
 });
@@ -301,7 +311,7 @@ export async function handleStats(
   if (listScheduledTasks.match(req.method, pathSegments)) {
     const parsed = await listScheduledTasks.parse(req, res, pathSegments, queryParams);
     if (!parsed) return true;
-    const scheduledTasks = await getScheduledTasks({
+    const filters = {
       enabled: parsed.query.enabled !== undefined ? parsed.query.enabled === "true" : undefined,
       name: parsed.query.name || undefined,
       scheduleType: (parsed.query.scheduleType as "recurring" | "one_time") || undefined,
@@ -312,13 +322,15 @@ export async function handleStats(
       targetType: parsed.query.targetType,
       workflowId: parsed.query.workflowId,
       scriptName: parsed.query.scriptName,
-    });
+    };
     const favoriteScope = (await resolveHttpFavoriteOwner(req, myAgentId))?.scope;
+    const favoriteOpts = { favoriteScope, itemType: "schedule" as const };
+    // Opt-in: API, MCP and script callers that don't ask keep the full rows.
     listScheduledTasks.respond(res, 200, {
-      scheduledTasks: await withFavoriteFlags(scheduledTasks, {
-        favoriteScope,
-        itemType: "schedule",
-      }),
+      scheduledTasks:
+        parsed.query.fields === "slim"
+          ? await withFavoriteFlags(await getScheduledTasks(filters, { slim: true }), favoriteOpts)
+          : await withFavoriteFlags(await getScheduledTasks(filters), favoriteOpts),
     });
     return true;
   }

package/src/http/status.ts

@@ -36,6 +36,7 @@ import {
 import { getEmbeddingProvider } from "../be/memory";
 import { getFileStorageProvider } from "../fs/registry";
 import { getSlackConfiguration } from "../slack/config";
+import { getSlackConnectionState } from "../slack/connection-state";
 import { type AgentCredStatus, AutomationIntegrationIdSchema, ProviderNameSchema } from "../types";
 import { route } from "./route-def";
 import { json, jsonError } from "./utils";
@@ -438,6 +439,15 @@ function slackMilestone(state: AutomationSetupStates["slack"]): SetupMilestone {
     };
   }
 
+  if (config.mode === "socket" && getSlackConnectionState() === "connected") {
+    return {
+      id: "slack",
+      label: "Slack configured",
+      state: "verified",
+      action_url: automationIntegrationFixUrl("slack"),
+    };
+  }
+
   return {
     id: "slack",
     label: "Slack configured",
@@ -445,7 +455,7 @@ function slackMilestone(state: AutomationSetupStates["slack"]): SetupMilestone {
     hint:
       config.mode === "http"
         ? "HTTP credentials are configured, but HTTP ingress is unavailable until the receiver is installed."
-        : "Socket Mode credentials are configured; a live connection has not been verified.",
+        : "Socket Mode credentials are configured, but the bot is not connected to Slack.",
     action_url: automationIntegrationFixUrl("slack"),
   };
 }

package/src/http/tasks.ts

@@ -113,6 +113,21 @@ const AgentTaskSummarySchema = AgentTaskSchema.pick({
   totalCostUsd: true,
 });
 
+/** `/api/tasks?fields=timeline` item — mirrors `AgentTaskTimelineItem` in ../types. */
+const AgentTaskTimelineItemSchema = AgentTaskSchema.pick({
+  id: true,
+  agentId: true,
+  parentTaskId: true,
+  task: true,
+  title: true,
+  status: true,
+  createdAt: true,
+  lastUpdatedAt: true,
+  finishedAt: true,
+  peakContextTokens: true,
+  totalCostUsd: true,
+});
+
 /** Shared by cancel/pause/resume — each sends `{ success: true, task }` on success. */
 const TaskActionResultSchema = z.object({
   success: z.literal(true),
@@ -173,7 +188,7 @@ const listTasks = route({
   pattern: ["api", "tasks"],
   summary: "List tasks with filters",
   description:
-    "Returns tasks with the full `task` text replaced by a bounded `taskPreview` and completion/integration blobs dropped by default — list views only need the preview. Pass `fields=full` to restore the full `AgentTask`. Fetch a single task in full via `GET /api/tasks/{id}`.",
+    "Returns tasks with the full `task` text replaced by a bounded `taskPreview` and completion/integration blobs dropped by default — list views only need the preview. Pass `fields=full` to restore the full `AgentTask`, or `fields=timeline` for the narrow shape the dashboard timeline draws. Fetch a single task in full via `GET /api/tasks/{id}`. `total` (the filtered row count, ignoring limit/offset) is computed only with `includeTotal=true`.",
   tags: ["Tasks"],
   query: z.object({
     /** Single status, or comma-separated list (e.g. "failed,cancelled"). */
@@ -200,15 +215,25 @@ const listTasks = route({
     orderBy: z.enum(["lastUpdatedAt", "createdAt"]).optional(),
     limit: z.coerce.number().int().optional(),
     offset: z.coerce.number().int().optional(),
-    /** `full` restores the legacy shape (full `task` text + all fields); default is slim. */
-    fields: z.enum(["full", "slim"]).optional(),
+    /**
+     * `full` restores the legacy shape (full `task` text + all fields);
+     * `timeline` is the dashboard timeline's narrow shape; default is slim.
+     */
+    fields: z.enum(["full", "slim", "timeline"]).optional(),
+    /** `true` adds `total`, a filtered COUNT(*) that pagers need. Omitted by default. */
+    includeTotal: z.enum(["true", "false"]).optional(),
   }),
   responses: {
     200: {
       description: "Paginated task list",
       schema: z.object({
-        tasks: z.union([z.array(AgentTaskSchema), z.array(AgentTaskSummarySchema)]),
-        total: z.number().int(),
+        tasks: z.union([
+          z.array(AgentTaskSchema),
+          z.array(AgentTaskSummarySchema),
+          z.array(AgentTaskTimelineItemSchema),
+        ]),
+        /** Present only when the request passed `includeTotal=true`. */
+        total: z.number().int().optional(),
       }),
     },
     400: { description: "Validation error (e.g. unknown status token)" },
@@ -785,9 +810,16 @@ export async function handleTasks(
     const tasks =
       parsed.query.fields === "full"
         ? await getAllTasks(filters)
-        : await getAllTasks(filters, { slim: true });
-    const total = await getTasksCount(filters);
-    listTasks.respond(res, 200, { tasks, total });
+        : parsed.query.fields === "timeline"
+          ? await getAllTasks(filters, { fields: "timeline" })
+          : await getAllTasks(filters, { slim: true });
+    // The COUNT(*) re-scans every matching row, so only pagers pay for it.
+    if (parsed.query.includeTotal === "true") {
+      const total = await getTasksCount(filters);
+      listTasks.respond(res, 200, { tasks, total });
+    } else {
+      listTasks.respond(res, 200, { tasks });
+    }
     return true;
   }
 

package/src/http/webhooks.ts

@@ -52,6 +52,7 @@ import type { KapsoConfig } from "../integrations/kapso/config";
 import { getKapsoConfig } from "../integrations/kapso/config";
 import type { KapsoWebhookPayload } from "../integrations/kapso/inbound";
 import { resolveKapsoRequestedByUserId, routeKapsoInbound } from "../integrations/kapso/inbound";
+import { TaskCreationBlockedError } from "../tasks/errors";
 import { getExecutorRegistry } from "../workflows";
 import { workflowEventBus } from "../workflows/event-bus";
 import { handleWebhookTrigger, verifyHmacSignature, WebhookError } from "../workflows/triggers";
@@ -67,8 +68,34 @@ import { route } from "./route-def";
 const WebhookDispatchResultSchema = z.object({
   created: z.boolean(),
   taskId: z.string().optional(),
+  skipped: z.boolean().optional(),
+  reason: z.string().optional(),
+  extension: z.object({ id: z.string(), name: z.string() }).optional(),
 });
 
+type WebhookDispatchResult = z.infer<typeof WebhookDispatchResultSchema>;
+
+/**
+ * Runs a webhook's task-creating handler. A `pre.task.create` extension block
+ * is an expected outcome, not a server error: the delivery is acked with a
+ * skipped result so the provider does not retry and the caller still emits the
+ * delivery's workflow events. Any other error propagates.
+ */
+async function runBlockableHandler(
+  source: string,
+  handler: () => Promise<WebhookDispatchResult>,
+): Promise<WebhookDispatchResult> {
+  try {
+    return await handler();
+  } catch (err) {
+    if (!(err instanceof TaskCreationBlockedError)) throw err;
+    console.log(
+      `[${source}] Task creation blocked by extension ${err.extension.name}: ${err.reason}`,
+    );
+    return { created: false, skipped: true, reason: err.reason, extension: err.extension };
+  }
+}
+
 const githubWebhook = route({
   method: "post",
   path: "/api/github/webhook",
@@ -249,37 +276,32 @@ export async function handleWebhooks(
 
     console.log(`[GitHub] Received ${eventType} event`);
 
-    let result: { created: boolean; taskId?: string } = { created: false };
+    let result: WebhookDispatchResult = { created: false };
 
     try {
-      switch (eventType) {
-        case "pull_request":
-          result = await handlePullRequest(body as PullRequestEvent);
-          break;
-        case "issues":
-          result = await handleIssue(body as IssueEvent);
-          break;
-        case "issue_comment":
-          result = await handleComment(body as CommentEvent, "issue_comment");
-          break;
-        case "pull_request_review_comment":
-          result = await handleComment(body as CommentEvent, "pull_request_review_comment");
-          break;
-        case "pull_request_review":
-          result = await handlePullRequestReview(body as PullRequestReviewEvent);
-          break;
-        case "check_run":
-          result = await handleCheckRun(body as CheckRunEvent);
-          break;
-        case "check_suite":
-          result = await handleCheckSuite(body as CheckSuiteEvent);
-          break;
-        case "workflow_run":
-          result = await handleWorkflowRun(body as WorkflowRunEvent);
-          break;
-        default:
-          console.log(`[GitHub] Ignoring unsupported event type: ${eventType}`);
-      }
+      result = await runBlockableHandler("GitHub", async () => {
+        switch (eventType) {
+          case "pull_request":
+            return await handlePullRequest(body as PullRequestEvent);
+          case "issues":
+            return await handleIssue(body as IssueEvent);
+          case "issue_comment":
+            return await handleComment(body as CommentEvent, "issue_comment");
+          case "pull_request_review_comment":
+            return await handleComment(body as CommentEvent, "pull_request_review_comment");
+          case "pull_request_review":
+            return await handlePullRequestReview(body as PullRequestReviewEvent);
+          case "check_run":
+            return await handleCheckRun(body as CheckRunEvent);
+          case "check_suite":
+            return await handleCheckSuite(body as CheckSuiteEvent);
+          case "workflow_run":
+            return await handleWorkflowRun(body as WorkflowRunEvent);
+          default:
+            console.log(`[GitHub] Ignoring unsupported event type: ${eventType}`);
+            return { created: false };
+        }
+      });
 
       // Emit workflow trigger event for matching event types
       switch (eventType) {
@@ -376,25 +398,24 @@ export async function handleWebhooks(
     const objectKind = body.object_kind as string | undefined;
     console.log(`[GitLab] Received ${objectKind} event`);
 
-    let result: { created: boolean; taskId?: string } = { created: false };
+    let result: WebhookDispatchResult = { created: false };
 
     try {
-      switch (objectKind) {
-        case "merge_request":
-          result = await handleMergeRequest(body as unknown as MergeRequestEvent);
-          break;
-        case "issue":
-          result = await handleGitLabIssue(body as unknown as GitLabIssueEvent);
-          break;
-        case "note":
-          result = await handleNote(body as unknown as NoteEvent);
-          break;
-        case "pipeline":
-          result = await handlePipeline(body as unknown as PipelineEvent);
-          break;
-        default:
-          console.log(`[GitLab] Ignoring unsupported event type: ${objectKind}`);
-      }
+      result = await runBlockableHandler("GitLab", async () => {
+        switch (objectKind) {
+          case "merge_request":
+            return await handleMergeRequest(body as unknown as MergeRequestEvent);
+          case "issue":
+            return await handleGitLabIssue(body as unknown as GitLabIssueEvent);
+          case "note":
+            return await handleNote(body as unknown as NoteEvent);
+          case "pipeline":
+            return await handlePipeline(body as unknown as PipelineEvent);
+          default:
+            console.log(`[GitLab] Ignoring unsupported event type: ${objectKind}`);
+            return { created: false };
+        }
+      });
 
       // Emit workflow trigger events for GitLab
       switch (objectKind) {

package/src/http/workflows.ts

@@ -10,7 +10,6 @@ import {
   getWorkflowRunStepsByRunId,
   getWorkflowVersion,
   getWorkflowVersions,
-  listWorkflowRuns,
   listWorkflowRunsPage,
   listWorkflows,
   type updateWorkflow,
@@ -29,6 +28,7 @@ import {
   WorkflowRunSchema,
   WorkflowRunStatusSchema,
   WorkflowRunStepSchema,
+  WorkflowRunSummarySchema,
   WorkflowSchema,
   WorkflowVersionSchema,
 } from "../types";
@@ -68,9 +68,12 @@ const ExecutorTypeInfoSchema = z.object({
   outputSchema: z.record(z.string(), z.unknown()),
 });
 
+/** Page size when a caller sends no `limit`. */
+const DEFAULT_WORKFLOW_RUNS_LIMIT = 50;
+
 /** Mirrors `WorkflowRunPage` in src/be/db.ts. */
 const WorkflowRunPageSchema = z.object({
-  runs: z.array(WorkflowRunSchema),
+  runs: z.array(WorkflowRunSummarySchema),
   page: z.object({
     limit: z.number().int(),
     offset: z.number().int(),
@@ -273,7 +276,8 @@ const listWorkflowRunsRoute = route({
   method: "get",
   path: "/api/workflows/{id}/runs",
   pattern: ["api", "workflows", null, "runs"],
-  summary: "List runs for a workflow",
+  summary: "List runs for a workflow, newest first",
+  description: `Returns one page of runs without \`context\` (fetch it with GET /api/workflow-runs/{id}). \`limit\` defaults to ${DEFAULT_WORKFLOW_RUNS_LIMIT} and is capped at 100; follow \`page.nextOffset\` while \`page.hasMore\` is true.`,
   tags: ["Workflows"],
   params: z.object({ id: z.string() }),
   query: z.object({
@@ -283,8 +287,8 @@ const listWorkflowRunsRoute = route({
   }),
   responses: {
     200: {
-      description: "Workflow run list",
-      schema: z.union([z.array(WorkflowRunSchema), WorkflowRunPageSchema]),
+      description: "One page of workflow runs",
+      schema: WorkflowRunPageSchema,
     },
   },
 });
@@ -847,21 +851,12 @@ export async function handleWorkflows(
   if (listWorkflowRunsRoute.match(req.method, pathSegments)) {
     const parsed = await listWorkflowRunsRoute.parse(req, res, pathSegments, queryParams);
     if (!parsed) return true;
-    const paginationRequested =
-      parsed.query?.limit !== undefined || parsed.query?.offset !== undefined;
-    if (paginationRequested) {
-      const page = await listWorkflowRunsPage(parsed.params.id, {
-        status: parsed.query?.status,
-        limit: parsed.query?.limit ?? 20,
-        offset: parsed.query?.offset ?? 0,
-      });
-      listWorkflowRunsRoute.respond(res, 200, page);
-      return true;
-    }
-    // Preserve the pre-pagination response for the UI when limit/offset are
-    // omitted: a bare array containing every matching run.
-    const runs = await listWorkflowRuns(parsed.params.id, { status: parsed.query?.status });
-    listWorkflowRunsRoute.respond(res, 200, runs);
+    const page = await listWorkflowRunsPage(parsed.params.id, {
+      status: parsed.query?.status,
+      limit: parsed.query?.limit ?? DEFAULT_WORKFLOW_RUNS_LIMIT,
+      offset: parsed.query?.offset ?? 0,
+    });
+    listWorkflowRunsRoute.respond(res, 200, page);
     return true;
   }
 

package/src/linear/outbound.ts

@@ -102,6 +102,31 @@ async function handleTaskProgress(data: unknown): Promise<void> {
   });
 }
 
+// Linear documents no size limit for a comment or an AgentActivity body. 30k chars stays under
+// the 32,767 figure other Linear integrations use, and fits any realistic task output.
+export const LINEAR_BODY_MAX = 30_000;
+
+/**
+ * Build the body of the single Linear comment that carries a task's outcome.
+ *
+ * The text goes in as-is: no `+++ Title … +++` wrapper (Linear renders that as a
+ * collapsed section) and no boilerplate. A body over `LINEAR_BODY_MAX` is cut and ends
+ * with a visible note that points at the swarm task for the full text.
+ */
+export function formatLinearOutcomeBody(text: string, taskId: string): string {
+  if (text.length <= LINEAR_BODY_MAX) return text;
+
+  const dashboardUrl = (process.env.SWARM_DASHBOARD_URL || process.env.APP_URL)?.replace(
+    /\/+$/,
+    "",
+  );
+  const where = dashboardUrl ? `${dashboardUrl}/tasks/${taskId}` : `swarm task \`${taskId}\``;
+  const note = (shown: number) =>
+    `\n\n---\n_Truncated: showing ${shown} of ${text.length} characters. Full text: ${where}_`;
+  const shown = LINEAR_BODY_MAX - note(LINEAR_BODY_MAX).length;
+  return `${text.slice(0, shown).trimEnd()}${note(shown)}`;
+}
+
 async function handleTaskCompleted(data: unknown): Promise<void> {
   const { taskId, output } = data as { taskId: string; output?: string };
   if (!taskId) return;
@@ -112,11 +137,11 @@ async function handleTaskCompleted(data: unknown): Promise<void> {
   if (shouldSkipForLoopPrevention(sync)) return;
 
   const sessionId = taskSessionMap.get(taskId);
-  const body = output
-    ? `Task completed.\n\n+++ Output\n${output.slice(0, 2000)}\n+++`
-    : "Task completed.";
+  const body = output?.trim() ? formatLinearOutcomeBody(output, taskId) : "Task completed.";
 
-  // Prefer AgentSession activity (shows in the agent panel) over issue comment (avoids duplication)
+  // One comment only. A `response` activity ends the AgentSession and Linear renders it as a
+  // comment on the issue, so it carries the output itself. The plain comment below runs only
+  // when there is no session to end.
   if (sessionId) {
     endAgentSession(sessionId, body, "response").catch((err) => {
       console.error(`[Linear Outbound] Failed to end AgentSession for task ${taskId}:`, err);
@@ -133,10 +158,7 @@ async function handleTaskCompleted(data: unknown): Promise<void> {
         console.log("[Linear Outbound] No Linear client available, skipping sync for", taskId);
         return;
       }
-      const comment = output
-        ? `Task completed by swarm agent.\n\n+++ Output\n${output.slice(0, 2000)}\n+++`
-        : "Task completed by swarm agent.";
-      await client.createComment({ issueId: sync.externalId, body: comment });
+      await client.createComment({ issueId: sync.externalId, body });
       console.log(`[Linear Outbound] Posted completion comment for task ${taskId}`);
     } catch (error) {
       console.error(
@@ -162,11 +184,14 @@ async function handleTaskFailed(data: unknown): Promise<void> {
   if (shouldSkipForLoopPrevention(sync)) return;
 
   const sessionId = taskSessionMap.get(taskId);
-  const body = failureReason
-    ? `Task failed.\n\n+++ Error Details\n${failureReason.slice(0, 2000)}\n+++`
+  // Keep the one-line "Task failed." lead: without it a plain fallback comment reads like
+  // a normal answer.
+  const body = failureReason?.trim()
+    ? formatLinearOutcomeBody(`Task failed.\n\n${failureReason}`, taskId)
     : "Task failed.";
 
-  // Prefer AgentSession error activity over issue comment (avoids duplication)
+  // One comment only: the `error` activity ends the AgentSession and carries the reason.
+  // The plain comment below runs only when there is no session to end.
   if (sessionId) {
     endAgentSession(sessionId, body, "error").catch((err) => {
       console.error(`[Linear Outbound] Failed to end AgentSession for task ${taskId}:`, err);
@@ -183,10 +208,7 @@ async function handleTaskFailed(data: unknown): Promise<void> {
         console.log("[Linear Outbound] No Linear client available, skipping sync for", taskId);
         return;
       }
-      const comment = failureReason
-        ? `Task failed.\n\n+++ Error Details\n${failureReason.slice(0, 2000)}\n+++`
-        : "Task failed.";
-      await client.createComment({ issueId: sync.externalId, body: comment });
+      await client.createComment({ issueId: sync.externalId, body });
       console.log(`[Linear Outbound] Posted failure comment for task ${taskId}`);
     } catch (error) {
       console.error(