@desplega.ai/agent-swarm 1.74.0 → 1.74.2

package/src/http/trackers/jira.ts

@@ -6,6 +6,7 @@ import { clearJiraMetadata, getJiraMetadata } from "../../jira/metadata";
 import { getJiraAuthorizationUrl, handleJiraCallback } from "../../jira/oauth";
 import { handleJiraWebhook } from "../../jira/webhook";
 import { deleteJiraWebhook, registerJiraWebhook } from "../../jira/webhook-lifecycle";
+import { ensureTokenOrThrow } from "../../oauth/ensure-token";
 import { route } from "../route-def";
 import { deriveApiBaseUrl, parseQueryParams } from "../utils";
 
@@ -59,6 +60,21 @@ const jiraStatus = route({
   },
 });
 
+const jiraRefresh = route({
+  method: "post",
+  path: "/api/trackers/jira/refresh",
+  pattern: ["api", "trackers", "jira", "refresh"],
+  summary:
+    "Force a Jira OAuth token refresh and return the updated status payload. Useful when an agent observes an expired token via tracker-status / db-query and wants to recover without restarting the server or re-running 3LO.",
+  tags: ["Trackers"],
+  responses: {
+    200: { description: "Token refreshed; returns same shape as /status" },
+    409: { description: "Jira not connected (no refresh token stored)" },
+    500: { description: "Refresh failed (e.g. revoked grant, network error)" },
+    503: { description: "Jira integration not configured" },
+  },
+});
+
 const jiraWebhook = route({
   method: "post",
   path: "/api/trackers/jira/webhook/{token}",
@@ -144,6 +160,38 @@ function getRedirectUri(req: IncomingMessage): string {
   return `${deriveApiBaseUrl(req)}/api/trackers/jira/callback`;
 }
 
+function buildJiraStatusPayload(req: IncomingMessage): Record<string, unknown> {
+  const tokens = getOAuthTokens("jira");
+  const meta = getJiraMetadata();
+  const scope = tokens?.scope ?? null;
+  // Atlassian returns scopes space-separated in the token response.
+  const scopeList = scope ? scope.split(/[\s,]+/).filter(Boolean) : [];
+  const hasManageWebhookScope = scopeList.includes("manage:jira-webhook");
+
+  const status: Record<string, unknown> = {
+    provider: "jira",
+    connected: !!tokens,
+    cloudId: meta.cloudId ?? null,
+    siteUrl: meta.siteUrl ?? null,
+    tokenExpiresAt: tokens?.expiresAt ?? null,
+    scope,
+    hasManageWebhookScope,
+    webhookTokenConfigured: Boolean(process.env.JIRA_WEBHOOK_TOKEN),
+    webhookUrl: getWebhookUrl(req),
+    redirectUri: getRedirectUri(req),
+    webhookIds: meta.webhookIds ?? [],
+  };
+
+  // Phase 5: surface manual-webhook instructions when the OAuth grant
+  // doesn't include `manage:jira-webhook` (admin must register webhooks
+  // manually in the Atlassian UI).
+  if (!hasManageWebhookScope) {
+    status.manualWebhookInstructions = MANUAL_WEBHOOK_INSTRUCTIONS;
+  }
+
+  return status;
+}
+
 // ─── Handler ─────────────────────────────────────────────────────────────────
 
 export async function handleJiraTracker(
@@ -222,37 +270,46 @@ export async function handleJiraTracker(
       return true;
     }
 
+    res.writeHead(200, { "Content-Type": "application/json" });
+    res.end(JSON.stringify(buildJiraStatusPayload(req)));
+    return true;
+  }
+
+  // POST /api/trackers/jira/refresh — force-refresh the access token and
+  // return the same shape as /status. Useful when an agent observes a stale
+  // token (via tracker-status / db-query MCP) and needs to recover in-band.
+  if (jiraRefresh.match(req.method, pathSegments)) {
+    if (!isJiraEnabled()) {
+      res.writeHead(503, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ error: "Jira integration not configured" }));
+      return true;
+    }
+
     const tokens = getOAuthTokens("jira");
-    const meta = getJiraMetadata();
-    const scope = tokens?.scope ?? null;
-    // Atlassian returns scopes space-separated in the token response.
-    const scopeList = scope ? scope.split(/[\s,]+/).filter(Boolean) : [];
-
-    const hasManageWebhookScope = scopeList.includes("manage:jira-webhook");
-
-    const status: Record<string, unknown> = {
-      provider: "jira",
-      connected: !!tokens,
-      cloudId: meta.cloudId ?? null,
-      siteUrl: meta.siteUrl ?? null,
-      tokenExpiresAt: tokens?.expiresAt ?? null,
-      scope,
-      hasManageWebhookScope,
-      webhookTokenConfigured: Boolean(process.env.JIRA_WEBHOOK_TOKEN),
-      webhookUrl: getWebhookUrl(req),
-      redirectUri: getRedirectUri(req),
-      webhookIds: meta.webhookIds ?? [],
-    };
-
-    // Phase 5: surface manual-webhook instructions when the OAuth grant
-    // doesn't include `manage:jira-webhook` (admin must register webhooks
-    // manually in the Atlassian UI).
-    if (!hasManageWebhookScope) {
-      status.manualWebhookInstructions = MANUAL_WEBHOOK_INSTRUCTIONS;
+    if (!tokens?.refreshToken) {
+      res.writeHead(409, { "Content-Type": "application/json" });
+      res.end(
+        JSON.stringify({
+          error: "Jira not connected — no refresh token stored. Run 3LO via /authorize.",
+        }),
+      );
+      return true;
+    }
+
+    try {
+      // Pass a buffer larger than any plausible token lifetime so
+      // isTokenExpiringSoon() always returns true and a refresh always fires.
+      await ensureTokenOrThrow("jira", Number.MAX_SAFE_INTEGER);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      console.error("[Jira] Forced token refresh failed:", message);
+      res.writeHead(500, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ error: "Token refresh failed", details: message }));
+      return true;
     }
 
     res.writeHead(200, { "Content-Type": "application/json" });
-    res.end(JSON.stringify(status));
+    res.end(JSON.stringify(buildJiraStatusPayload(req)));
     return true;
   }
 

package/src/http/trackers/linear.ts

@@ -8,6 +8,7 @@ import {
   revokeLinearToken,
 } from "../../linear/oauth";
 import { handleLinearWebhook } from "../../linear/webhook";
+import { ensureTokenOrThrow } from "../../oauth/ensure-token";
 import { route } from "../route-def";
 import { deriveApiBaseUrl, parseQueryParams } from "../utils";
 
@@ -57,6 +58,21 @@ const linearStatus = route({
   },
 });
 
+const linearRefresh = route({
+  method: "post",
+  path: "/api/trackers/linear/refresh",
+  pattern: ["api", "trackers", "linear", "refresh"],
+  summary:
+    "Force a Linear OAuth token refresh and return the updated status payload. Useful when an agent observes an expired token and wants to recover without restarting the server or re-running OAuth.",
+  tags: ["Trackers"],
+  responses: {
+    200: { description: "Token refreshed; returns same shape as /status" },
+    409: { description: "Linear not connected (no refresh token stored)" },
+    500: { description: "Refresh failed" },
+    503: { description: "Linear integration not configured" },
+  },
+});
+
 const linearWebhook = route({
   method: "post",
   path: "/api/trackers/linear/webhook",
@@ -86,6 +102,22 @@ const linearDisconnect = route({
   },
 });
 
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+
+function buildLinearStatusPayload(req: IncomingMessage): Record<string, unknown> {
+  const tokens = getOAuthTokens("linear");
+  const baseUrl = deriveApiBaseUrl(req);
+
+  return {
+    provider: "linear",
+    connected: !!tokens,
+    tokenExpiry: tokens?.expiresAt ?? null,
+    scope: tokens?.scope ?? null,
+    webhookUrl: `${baseUrl}/api/trackers/linear/webhook`,
+    redirectUri: `${baseUrl}/api/trackers/linear/callback`,
+  };
+}
+
 // ─── Handler ─────────────────────────────────────────────────────────────────
 
 export async function handleLinearTracker(
@@ -164,20 +196,44 @@ export async function handleLinearTracker(
       return true;
     }
 
+    res.writeHead(200, { "Content-Type": "application/json" });
+    res.end(JSON.stringify(buildLinearStatusPayload(req)));
+    return true;
+  }
+
+  // POST /api/trackers/linear/refresh — force-refresh the Linear access token.
+  // Mirrors the Jira refresh route; recovery path for agents that observe a
+  // stale token in oauth_tokens.
+  if (linearRefresh.match(req.method, pathSegments)) {
+    if (!isLinearEnabled()) {
+      res.writeHead(503, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ error: "Linear integration not configured" }));
+      return true;
+    }
+
     const tokens = getOAuthTokens("linear");
-    const baseUrl = deriveApiBaseUrl(req);
-
-    const status = {
-      provider: "linear",
-      connected: !!tokens,
-      tokenExpiry: tokens?.expiresAt ?? null,
-      scope: tokens?.scope ?? null,
-      webhookUrl: `${baseUrl}/api/trackers/linear/webhook`,
-      redirectUri: `${baseUrl}/api/trackers/linear/callback`,
-    };
+    if (!tokens?.refreshToken) {
+      res.writeHead(409, { "Content-Type": "application/json" });
+      res.end(
+        JSON.stringify({
+          error: "Linear not connected — no refresh token stored. Run OAuth via /authorize.",
+        }),
+      );
+      return true;
+    }
+
+    try {
+      await ensureTokenOrThrow("linear", Number.MAX_SAFE_INTEGER);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      console.error("[Linear] Forced token refresh failed:", message);
+      res.writeHead(500, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ error: "Token refresh failed", details: message }));
+      return true;
+    }
 
     res.writeHead(200, { "Content-Type": "application/json" });
-    res.end(JSON.stringify(status));
+    res.end(JSON.stringify(buildLinearStatusPayload(req)));
     return true;
   }
 

package/src/http/utils.ts

@@ -57,6 +57,21 @@ export function jsonError(res: ServerResponse, error: string, status = 400) {
   res.end(JSON.stringify({ error }));
 }
 
+/**
+ * Send a 400 response for a workflow `triggerSchema` validation failure.
+ * Frozen wire shape: `{ error: "TriggerSchemaError", message, details: string[] }`.
+ * `details` carries the per-field validator output so callers can render
+ * field-level diagnostics (FE tester, MCP, etc.).
+ */
+export function triggerSchemaErrorResponse(
+  res: ServerResponse,
+  message: string,
+  details: string[],
+) {
+  res.writeHead(400, { "Content-Type": "application/json" });
+  res.end(JSON.stringify({ error: "TriggerSchemaError", message, details }));
+}
+
 /**
  * Derive the API base URL for outbound-facing values (webhook URLs, OAuth
  * redirect URIs). Returns a URL with no trailing slash.

package/src/http/workflow-events.ts

@@ -0,0 +1,107 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import { z } from "zod";
+import { getWorkflowRun } from "../be/db";
+import { workflowEventBus } from "../workflows/event-bus";
+import { route } from "./route-def";
+import { json, jsonError } from "./utils";
+
+// ─── Route Definitions ───────────────────────────────────────────────────────
+
+/**
+ * Run-scoped event signal: emits `name` on `workflowEventBus` with the payload
+ * augmented by `_runId` (so wait-states with `scope: 'run'` can correlate).
+ *
+ * Existing built-in bus events from `src/be/db.ts` carry `workflowRunId`; the
+ * matcher in `src/workflows/resume.ts` accepts either field name.
+ */
+const runScopedSignalRoute = route({
+  method: "post",
+  path: "/api/workflow-runs/{runId}/events",
+  pattern: ["api", "workflow-runs", null, "events"],
+  summary: "Fire a run-scoped event signal",
+  description:
+    "Emits an event onto the workflow event bus with `_runId` injected. " +
+    "Used by wait nodes in `event` mode with `scope: 'run'`. The body's `name` " +
+    "is the bus event name; `payload` is forwarded as-is plus `_runId`.",
+  tags: ["WorkflowEvents"],
+  params: z.object({ runId: z.string().uuid() }),
+  body: z.object({
+    name: z.string().min(1),
+    payload: z.record(z.string(), z.unknown()).optional(),
+  }),
+  responses: {
+    200: { description: "Event emitted" },
+    404: { description: "Workflow run not found" },
+    400: { description: "Validation error" },
+  },
+  auth: { apiKey: true },
+});
+
+/**
+ * Global broadcast: emits `name` on `workflowEventBus` with the raw payload.
+ * Wait-states with `scope: 'global'` may resolve from these signals.
+ */
+const globalSignalRoute = route({
+  method: "post",
+  path: "/api/workflow-events",
+  pattern: ["api", "workflow-events"],
+  summary: "Fire a global workflow event signal",
+  description:
+    "Emits an event onto the workflow event bus. Wait-states with " +
+    "`scope: 'global'` may match. Run-scoped waits will NOT match this " +
+    "broadcast unless the payload carries a matching `workflowRunId`.",
+  tags: ["WorkflowEvents"],
+  body: z.object({
+    name: z.string().min(1),
+    payload: z.record(z.string(), z.unknown()).optional(),
+  }),
+  responses: {
+    200: { description: "Event emitted" },
+    400: { description: "Validation error" },
+  },
+  auth: { apiKey: true },
+});
+
+// ─── Handler ─────────────────────────────────────────────────────────────────
+
+export async function handleWorkflowEvents(
+  req: IncomingMessage,
+  res: ServerResponse,
+  pathSegments: string[],
+  queryParams: URLSearchParams,
+): Promise<boolean> {
+  // POST /api/workflow-runs/{runId}/events
+  if (runScopedSignalRoute.match(req.method, pathSegments)) {
+    const parsed = await runScopedSignalRoute.parse(req, res, pathSegments, queryParams);
+    if (!parsed) return true;
+
+    const run = getWorkflowRun(parsed.params.runId);
+    if (!run) {
+      jsonError(res, "Workflow run not found", 404);
+      return true;
+    }
+
+    const payload = { ...(parsed.body.payload ?? {}), _runId: parsed.params.runId };
+    workflowEventBus.emit(parsed.body.name, payload);
+
+    json(res, {
+      ok: true,
+      name: parsed.body.name,
+      runId: parsed.params.runId,
+    });
+    return true;
+  }
+
+  // POST /api/workflow-events
+  if (globalSignalRoute.match(req.method, pathSegments)) {
+    const parsed = await globalSignalRoute.parse(req, res, pathSegments, queryParams);
+    if (!parsed) return true;
+
+    workflowEventBus.emit(parsed.body.name, parsed.body.payload ?? {});
+
+    json(res, { ok: true, name: parsed.body.name });
+    return true;
+  }
+
+  return false;
+}

package/src/http/workflows.ts

@@ -16,19 +16,20 @@ import {
   CooldownConfigSchema,
   InputValueSchema,
   TriggerConfigSchema,
-  WorkflowDefinitionPatchSchema,
   WorkflowDefinitionSchema,
   WorkflowNodePatchSchema,
+  WorkflowPatchSchema,
   WorkflowRunStatusSchema,
 } from "../types";
 import { getExecutorRegistry, startWorkflowExecution } from "../workflows";
 import { applyDefinitionPatch, generateEdges, validateDefinition } from "../workflows/definition";
 import { TriggerSchemaError } from "../workflows/engine";
+import { validateJsonSchema } from "../workflows/json-schema-validator";
 import { cancelWorkflowRun, retryFailedRun } from "../workflows/resume";
 import { handleWebhookTrigger, WebhookError } from "../workflows/triggers";
 import { snapshotWorkflow } from "../workflows/version";
 import { route } from "./route-def";
-import { json, jsonError, parseBody } from "./utils";
+import { json, jsonError, parseBody, triggerSchemaErrorResponse } from "./utils";
 
 // ─── Route Definitions ───────────────────────────────────────────────────────
 
@@ -112,7 +113,7 @@ const patchWorkflowRoute = route({
   summary: "Patch a workflow definition (create/update/delete nodes)",
   tags: ["Workflows"],
   params: z.object({ id: z.string() }),
-  body: WorkflowDefinitionPatchSchema,
+  body: WorkflowPatchSchema,
   responses: {
     200: { description: "Workflow patched (version snapshot created)" },
     400: { description: "Invalid patch or resulting definition" },
@@ -163,6 +164,20 @@ const triggerWorkflowRoute = route({
   },
 });
 
+const validateTriggerRoute = route({
+  method: "post",
+  path: "/api/workflows/{id}/trigger/validate",
+  pattern: ["api", "workflows", null, "trigger", "validate"],
+  summary: "Validate a payload against the workflow's triggerSchema (no run)",
+  tags: ["Workflows"],
+  params: z.object({ id: z.string() }),
+  responses: {
+    200: { description: "Payload matches the workflow's triggerSchema (or workflow has none)" },
+    400: { description: "Payload failed validation; body matches the TriggerSchemaError contract" },
+    404: { description: "Workflow not found" },
+  },
+});
+
 const listWorkflowRunsRoute = route({
   method: "get",
   path: "/api/workflows/{id}/runs",
@@ -349,7 +364,7 @@ export async function handleWorkflows(
       json(res, result, 201);
     } catch (err) {
       if (err instanceof TriggerSchemaError) {
-        jsonError(res, err.message, 400);
+        triggerSchemaErrorResponse(res, err.message, err.validationErrors);
       } else if (err instanceof WebhookError) {
         jsonError(res, err.message, err.statusCode);
       } else {
@@ -510,7 +525,13 @@ export async function handleWorkflows(
       // Snapshot failure should not block the update
     }
 
-    const workflow = updateWorkflow(id, { definition: patchResult.definition });
+    const updateArgs: Parameters<typeof updateWorkflow>[1] = {
+      definition: patchResult.definition,
+    };
+    if (parsed.body.triggerSchema !== undefined) {
+      updateArgs.triggerSchema = parsed.body.triggerSchema;
+    }
+    const workflow = updateWorkflow(id, updateArgs);
     if (!workflow) {
       res.writeHead(404);
       res.end();
@@ -585,6 +606,34 @@ export async function handleWorkflows(
     return true;
   }
 
+  if (validateTriggerRoute.match(req.method, pathSegments)) {
+    const parsed = await validateTriggerRoute.parse(req, res, pathSegments, queryParams);
+    if (!parsed) return true;
+    const workflow = getWorkflow(parsed.params.id);
+    if (!workflow) {
+      res.writeHead(404);
+      res.end();
+      return true;
+    }
+    const body = await parseBody<Record<string, unknown>>(req);
+    const triggerData = (body?.triggerData ?? body) as unknown;
+    if (!workflow.triggerSchema) {
+      json(res, { valid: true, schema: null });
+      return true;
+    }
+    const errors = validateJsonSchema(workflow.triggerSchema, triggerData);
+    if (errors.length > 0) {
+      triggerSchemaErrorResponse(
+        res,
+        `Trigger schema validation failed: ${errors.join("; ")}`,
+        errors,
+      );
+      return true;
+    }
+    json(res, { valid: true });
+    return true;
+  }
+
   if (triggerWorkflowRoute.match(req.method, pathSegments)) {
     const parsed = await triggerWorkflowRoute.parse(req, res, pathSegments, queryParams);
     if (!parsed) return true;
@@ -605,7 +654,7 @@ export async function handleWorkflows(
       runId = await startWorkflowExecution(workflow, body, getExecutorRegistry());
     } catch (err) {
       if (err instanceof TriggerSchemaError) {
-        jsonError(res, err.message, 400);
+        triggerSchemaErrorResponse(res, err.message, err.validationErrors);
         return true;
       }
       throw err;

package/src/jira/sync.ts

@@ -75,17 +75,30 @@ export async function resolveBotAccountId(): Promise<string | null> {
 
   try {
     await ensureToken("jira");
-    const tokens = getOAuthTokens("jira");
+    let tokens = getOAuthTokens("jira");
     if (!tokens?.accessToken) {
       console.warn("[Jira Sync] No Jira access token; cannot resolve bot accountId");
       return null;
     }
-    const res = await fetch("https://api.atlassian.com/me", {
-      headers: {
-        Authorization: `Bearer ${tokens.accessToken}`,
-        Accept: "application/json",
-      },
-    });
+    const callMe = async (accessToken: string) =>
+      fetch("https://api.atlassian.com/me", {
+        headers: {
+          Authorization: `Bearer ${accessToken}`,
+          Accept: "application/json",
+        },
+      });
+    let res = await callMe(tokens.accessToken);
+    // Mirror jiraFetch's 401-retry pattern: a token may go stale between the
+    // proactive ensureToken call and the request reaching Atlassian.
+    if (res.status === 401) {
+      await ensureToken("jira", 0);
+      tokens = getOAuthTokens("jira");
+      if (!tokens?.accessToken) {
+        console.warn("[Jira Sync] /me returned 401 and refresh produced no token");
+        return null;
+      }
+      res = await callMe(tokens.accessToken);
+    }
     if (!res.ok) {
       console.warn(`[Jira Sync] /me returned ${res.status}; cannot resolve bot accountId`);
       return null;

package/src/linear/gate.ts

@@ -0,0 +1,122 @@
+/**
+ * Linear assignment-time gating: decides whether an incoming AgentSessionEvent
+ * should trigger swarm task creation based on the issue's workflow state and
+ * labels.
+ *
+ * Rules:
+ * - The set of allowed `WorkflowState.type` values is configurable via
+ *   `LINEAR_ALLOWED_STATES` (CSV). Default: `unstarted,started,completed,canceled`,
+ *   which matches Linear's enum minus `triage` and `backlog` ("tracked but not
+ *   ready").
+ * - The override label name is configurable via `LINEAR_SWARM_READY_LABEL`.
+ *   Default: `swarm-ready`. Matching is case-insensitive.
+ * - If the state cannot be resolved (null), default to allow (fail-open) so
+ *   assignments aren't silently swallowed by missing data.
+ */
+
+export const DEFAULT_SWARM_READY_LABEL = "swarm-ready";
+export const DEFAULT_ALLOWED_STATE_TYPES = [
+  "unstarted",
+  "started",
+  "completed",
+  "canceled",
+] as const;
+
+/** Backwards-compat alias kept so tests can reference the default override label. */
+export const SWARM_READY_LABEL = DEFAULT_SWARM_READY_LABEL;
+
+export interface LinearGateConfig {
+  /** Lowercased `WorkflowState.type` values that should trigger task creation. */
+  allowedStateTypes: Set<string>;
+  /** Lowercased label name that bypasses the state gate. */
+  swarmReadyLabel: string;
+}
+
+export interface LinearGateInput {
+  /** Linear `WorkflowState.type` value. Null if unknown. */
+  stateType: string | null;
+  /** Names of labels attached to the issue. Case-insensitive matching. */
+  labelNames: string[];
+}
+
+export type LinearGateDecision =
+  | { create: true; reason: "ready" | "label-override" }
+  | { create: false; reason: string };
+
+/**
+ * Resolve the gate config from environment variables, with sensible defaults.
+ * Read on each call so tests / runtime overrides are picked up without restart.
+ */
+export function getLinearGateConfig(): LinearGateConfig {
+  const statesEnv = process.env.LINEAR_ALLOWED_STATES;
+  const allowedStateTypes = parseStateList(statesEnv);
+
+  const labelEnv = process.env.LINEAR_SWARM_READY_LABEL?.trim();
+  const swarmReadyLabel = (
+    labelEnv && labelEnv.length > 0 ? labelEnv : DEFAULT_SWARM_READY_LABEL
+  ).toLowerCase();
+
+  return { allowedStateTypes, swarmReadyLabel };
+}
+
+function parseStateList(csv: string | undefined): Set<string> {
+  if (csv === undefined) {
+    return new Set(DEFAULT_ALLOWED_STATE_TYPES);
+  }
+  // An explicit empty value locks down all states (only label override works).
+  return new Set(
+    csv
+      .split(",")
+      .map((s) => s.trim().toLowerCase())
+      .filter((s) => s.length > 0),
+  );
+}
+
+/**
+ * Pure decision function: should this Linear assignment create a swarm task?
+ *
+ * Exported separately from the side-effecting webhook handler so it can be
+ * unit-tested without spinning up the DB or Linear API. Config is injectable
+ * for tests; production callers can rely on the env-driven default.
+ */
+export function shouldCreateTaskFromLinearEvent(
+  input: LinearGateInput,
+  config: LinearGateConfig = getLinearGateConfig(),
+): LinearGateDecision {
+  const labelMatch = config.swarmReadyLabel;
+  const hasReadyLabel = input.labelNames.some((name) => name.trim().toLowerCase() === labelMatch);
+  if (hasReadyLabel) {
+    return { create: true, reason: "label-override" };
+  }
+
+  const stateType = input.stateType?.toLowerCase() ?? null;
+  // Fail-open: if we couldn't resolve the state, default to today's behavior
+  // rather than silently swallowing assignments.
+  if (stateType === null) {
+    return { create: true, reason: "ready" };
+  }
+  if (!config.allowedStateTypes.has(stateType)) {
+    return { create: false, reason: stateType };
+  }
+  return { create: true, reason: "ready" };
+}
+
+/**
+ * Build the user-facing message posted on a skipped Linear assignment.
+ */
+export function buildSkipMessage(
+  reason: string,
+  swarmReadyLabel: string = getLinearGateConfig().swarmReadyLabel,
+): string {
+  const stateLabel = titleCase(reason);
+  return [
+    `Agent Swarm received the assignment but skipped — this issue is in ${stateLabel}.`,
+    "",
+    `To trigger work, move it to an allowed workflow state (e.g. **Todo** or **In Progress**), or add the \`${swarmReadyLabel}\` label and re-assign the agent.`,
+  ].join("\n");
+}
+
+function titleCase(s: string): string {
+  if (s.length === 0) return s;
+  return (s[0] ?? "").toUpperCase() + s.slice(1);
+}