@desplega.ai/agent-swarm 1.74.0 → 1.74.2

package/src/linear/sync.ts

@@ -10,6 +10,12 @@ import { ensureToken } from "../oauth/ensure-token";
 import { resolveTemplate } from "../prompts/resolver";
 import { linearContextKey } from "../tasks/context-key";
 import { createTaskWithSiblingAwareness } from "../tasks/sibling-awareness";
+import {
+  buildSkipMessage,
+  getLinearGateConfig,
+  type LinearGateInput,
+  shouldCreateTaskFromLinearEvent,
+} from "./gate";
 // Side-effect import: registers all Linear event templates in the in-memory registry
 import "./templates";
 
@@ -228,6 +234,104 @@ export function mapLinearStatusToSwarm(linearStateName: string): string | null {
   return LINEAR_STATUS_MAP[linearStateName] ?? null;
 }
 
+/**
+ * Try to read state.type and label names directly from the webhook payload.
+ *
+ * Returns null if neither field is present so the caller can fetch via
+ * GraphQL. As of the Linear AgentSessionEvent webhook schema (April 2026),
+ * `agentSession.issue` only includes `id`, `identifier`, `title`, `url`,
+ * `description`, `team`, and `teamId` — but we still try inline extraction
+ * to keep tests hermetic and to be forward-compatible if Linear ever extends
+ * the payload.
+ */
+function extractInlineGateInput(issue: Record<string, unknown>): LinearGateInput | null {
+  const stateRaw = issue.state as Record<string, unknown> | undefined;
+  const stateType =
+    stateRaw && typeof stateRaw.type === "string" ? (stateRaw.type as string) : null;
+
+  const labelsRaw = issue.labels;
+  let labelNames: string[] | null = null;
+  if (Array.isArray(labelsRaw)) {
+    labelNames = labelsRaw
+      .map((l) =>
+        l && typeof l === "object" ? String((l as Record<string, unknown>).name ?? "") : "",
+      )
+      .filter((n) => n.length > 0);
+  } else if (
+    labelsRaw &&
+    typeof labelsRaw === "object" &&
+    Array.isArray((labelsRaw as { nodes?: unknown }).nodes)
+  ) {
+    labelNames = ((labelsRaw as { nodes: unknown[] }).nodes ?? [])
+      .map((l) =>
+        l && typeof l === "object" ? String((l as Record<string, unknown>).name ?? "") : "",
+      )
+      .filter((n) => n.length > 0);
+  }
+
+  if (stateType === null && labelNames === null) return null;
+  return { stateType, labelNames: labelNames ?? [] };
+}
+
+const ISSUE_GATE_QUERY = `
+  query AgentSwarmIssueGate($id: String!) {
+    issue(id: $id) {
+      state { type }
+      labels { nodes { name } }
+    }
+  }
+`;
+
+/**
+ * Fetch the workflow-state type and label names for an issue via GraphQL.
+ * Used as a fallback when the AgentSessionEvent payload doesn't include them
+ * inline (today, it never does).
+ *
+ * Exported for testing — not part of the public API.
+ */
+export async function _fetchIssueGatingInfo(issueId: string): Promise<LinearGateInput> {
+  await ensureToken("linear");
+  const tokens = getOAuthTokens("linear");
+  if (!tokens) {
+    console.log(
+      `[Linear Sync] No OAuth tokens; cannot fetch issue ${issueId} gating info — defaulting to allow.`,
+    );
+    return { stateType: null, labelNames: [] };
+  }
+  const res = await fetch("https://api.linear.app/graphql", {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      Authorization: `Bearer ${tokens.accessToken}`,
+    },
+    body: JSON.stringify({ query: ISSUE_GATE_QUERY, variables: { id: issueId } }),
+  });
+  if (!res.ok) {
+    console.error(
+      `[Linear Sync] Failed to fetch issue ${issueId} gating info: ${res.status} ${res.statusText}`,
+    );
+    return { stateType: null, labelNames: [] };
+  }
+  const json = (await res.json()) as {
+    data?: {
+      issue?: {
+        state?: { type?: string };
+        labels?: { nodes?: Array<{ name?: string }> };
+      };
+    };
+    errors?: unknown[];
+  };
+  if (json.errors) {
+    console.error("[Linear Sync] GraphQL errors fetching issue gating info:", json.errors);
+    return { stateType: null, labelNames: [] };
+  }
+  const stateType = json.data?.issue?.state?.type ?? null;
+  const labelNames = (json.data?.issue?.labels?.nodes ?? [])
+    .map((n) => n?.name ?? "")
+    .filter((n) => n.length > 0);
+  return { stateType, labelNames };
+}
+
 /**
  * Find the lead agent to receive Linear tasks.
  * Returns null if no lead is available (task will go to pool).
@@ -320,6 +424,30 @@ export async function handleAgentSessionEvent(event: Record<string, unknown>): P
     );
   }
 
+  // State gate: only trigger task creation when the issue is in an allowed
+  // workflow state (Todo / In Progress / etc). States outside the allowlist
+  // (Backlog, Triage by default) are skipped unless the swarm-ready label
+  // override is attached. Both the allowlist and the override label name are
+  // configurable via LINEAR_ALLOWED_STATES and LINEAR_SWARM_READY_LABEL.
+  const gateConfig = getLinearGateConfig();
+  const inlineGate = extractInlineGateInput(issue);
+  const gateInput = inlineGate ?? (await _fetchIssueGatingInfo(issueId));
+  const decision = shouldCreateTaskFromLinearEvent(gateInput, gateConfig);
+  if (!decision.create) {
+    console.log(
+      `[Linear Sync] Issue ${issueIdentifier} skipped — workflow state "${decision.reason}" is gated (labels: [${gateInput.labelNames.join(", ")}])`,
+    );
+    if (sessionId) {
+      const skipMsg = buildSkipMessage(decision.reason, gateConfig.swarmReadyLabel);
+      // Use response so the AgentSession auto-completes — leaves a visible
+      // comment on the issue without orphaning the session in pending state.
+      endAgentSession(sessionId, skipMsg, "response").catch((err) => {
+        console.error("[Linear Sync] Failed to post skip response on AgentSession:", err);
+      });
+    }
+    return;
+  }
+
   const lead = findLeadAgent();
 
   const sessionSection = sessionUrl ? `\nSession: ${sessionUrl}` : "";

package/src/oauth/keepalive.ts

@@ -1,7 +1,20 @@
 import { ensureTokenOrThrow } from "./ensure-token";
 
-const TWELVE_HOURS_MS = 12 * 60 * 60 * 1000;
-const THIRTEEN_HOURS_MS = 13 * 60 * 60 * 1000;
+// Tick every 50 minutes with a 65-minute "expiring soon" buffer.
+//
+// Atlassian (and Linear) issue 1h access tokens. With this cadence the DB row
+// is always rotated before its current access token expires, so anything that
+// reads oauth_tokens.accessToken directly without going through jiraFetch /
+// linear-outbound (e.g. agents using the read-only db-query MCP) sees a
+// not-yet-expired token. The 65-min buffer is wider than the access-token
+// lifetime, so isTokenExpiringSoon always returns true and every tick rotates.
+//
+// Touching the row this often also serves the original "keep the refresh
+// token alive" goal — Atlassian expires inactive refresh tokens after 90 days,
+// and Linear's behavior is similar; refreshing every 50 min trivially keeps
+// both providers active.
+const KEEPALIVE_INTERVAL_MS = 50 * 60 * 1000;
+const KEEPALIVE_BUFFER_MS = 65 * 60 * 1000;
 const SLACK_ALERTS_CHANNEL = process.env.SLACK_ALERTS_CHANNEL || "C08JCRURPBV";
 
 const KEEPALIVE_PROVIDERS = ["linear", "jira"] as const;
@@ -9,20 +22,25 @@ const KEEPALIVE_PROVIDERS = ["linear", "jira"] as const;
 let keepaliveInterval: ReturnType<typeof setInterval> | null = null;
 
 /**
- * Proactively refresh OAuth tokens on a schedule to prevent expiry.
- * If refresh fails, posts a Slack notification so someone can re-auth manually.
+ * Proactively refresh OAuth tokens on a schedule.
  *
- * Why both Linear and Jira: Atlassian rotates refresh tokens and expires them
- * after 90 days of inactivity, so a swarm that doesn't touch Jira for a long
- * stretch will silently lose the ability to refresh. Touching the token every
- * 12h keeps the refresh token alive and surfaces a dead one as an alert
- * instead of a runtime 401.
+ * Two purposes, both served by the same tick:
+ *
+ *  1. Access-token freshness in the DB. Anything that reads
+ *     `oauth_tokens.accessToken` directly (db-query MCP, future MCP servers,
+ *     `tracker-status`) needs a not-yet-expired value. The 50-min cadence
+ *     keeps the row ahead of the 1h access-token lifetime.
+ *  2. Refresh-token liveness. Atlassian rotates refresh tokens and expires
+ *     them after ~90 days of inactivity, so silent gaps in usage would kill
+ *     the integration. Refreshing on every tick keeps the refresh token
+ *     active and surfaces a dead one as a Slack alert instead of a runtime
+ *     401 in the middle of an agent task.
  */
 async function runKeepalive(): Promise<void> {
   for (const provider of KEEPALIVE_PROVIDERS) {
     console.log(`[OAuth Keepalive] Running scheduled token refresh for ${provider}...`);
     try {
-      await ensureTokenOrThrow(provider, THIRTEEN_HOURS_MS);
+      await ensureTokenOrThrow(provider, KEEPALIVE_BUFFER_MS);
       console.log(`[OAuth Keepalive] ${provider} token check completed successfully`);
     } catch (err) {
       const message = err instanceof Error ? err.message : String(err);
@@ -56,7 +74,8 @@ async function notifySlack(text: string): Promise<void> {
 }
 
 /**
- * Start the OAuth keepalive timer. Runs immediately then every 12 hours.
+ * Start the OAuth keepalive timer. Runs once shortly after startup, then on
+ * KEEPALIVE_INTERVAL_MS thereafter.
  */
 export function startOAuthKeepalive(): void {
   if (keepaliveInterval) {
@@ -64,14 +83,16 @@ export function startOAuthKeepalive(): void {
     return;
   }
 
-  console.log("[OAuth Keepalive] Starting (12h interval)");
+  console.log(
+    `[OAuth Keepalive] Starting (interval ${Math.round(KEEPALIVE_INTERVAL_MS / 60_000)}min, buffer ${Math.round(KEEPALIVE_BUFFER_MS / 60_000)}min)`,
+  );
 
   // Run once after a short delay (let server finish startup)
   setTimeout(() => runKeepalive(), 10_000);
 
   keepaliveInterval = setInterval(() => {
     runKeepalive();
-  }, TWELVE_HOURS_MS);
+  }, KEEPALIVE_INTERVAL_MS);
 }
 
 /**

package/src/tests/ensure-token.test.ts

@@ -233,4 +233,37 @@ describe("ensureTokenOrThrow", () => {
   test("stays silent (no throw) when provider is not configured", async () => {
     await expect(ensureTokenOrThrow("nonexistent-provider")).resolves.toBeUndefined();
   });
+
+  test("forces a refresh when bufferMs is wider than any plausible expiry", async () => {
+    // Pattern used by the POST /api/trackers/{provider}/refresh route to
+    // guarantee a rotation regardless of how far the current token is from
+    // expiry.
+    storeOAuthTokens("test-provider", {
+      accessToken: "old-token",
+      refreshToken: "refresh-token",
+      expiresAt: new Date(Date.now() + 50 * 60 * 1000).toISOString(), // 50 min ahead
+    });
+
+    const fetchSpy = mock(() =>
+      Promise.resolve(
+        new Response(
+          JSON.stringify({
+            access_token: "rotated-token",
+            token_type: "Bearer",
+            expires_in: 3600,
+            refresh_token: "rotated-refresh",
+          }),
+          { status: 200, headers: { "Content-Type": "application/json" } },
+        ),
+      ),
+    );
+    globalThis.fetch = fetchSpy;
+
+    await ensureTokenOrThrow("test-provider", Number.MAX_SAFE_INTEGER);
+
+    expect(fetchSpy).toHaveBeenCalledTimes(1);
+    const tokens = getOAuthTokens("test-provider");
+    expect(tokens?.accessToken).toBe("rotated-token");
+    expect(tokens?.refreshToken).toBe("rotated-refresh");
+  });
 });

package/src/tests/linear-webhook.test.ts

@@ -3,6 +3,14 @@ import { createHmac } from "node:crypto";
 import { unlink } from "node:fs/promises";
 import { closeDb, createTaskExtended, getTaskById, initDb } from "../be/db";
 import { createTrackerSync, getTrackerSyncByExternalId } from "../be/db-queries/tracker";
+import {
+  buildSkipMessage,
+  DEFAULT_ALLOWED_STATE_TYPES,
+  DEFAULT_SWARM_READY_LABEL,
+  getLinearGateConfig,
+  SWARM_READY_LABEL,
+  shouldCreateTaskFromLinearEvent,
+} from "../linear/gate";
 import {
   handleAgentSessionEvent,
   handleIssueDelete,
@@ -505,3 +513,378 @@ describe("handleIssueDelete", () => {
     expect(updated!.status).toBe("completed");
   });
 });
+
+// ─── shouldCreateTaskFromLinearEvent (gate) ──────────────────────────────────
+
+describe("shouldCreateTaskFromLinearEvent (default config)", () => {
+  test("creates task for unstarted (Todo) state", () => {
+    const decision = shouldCreateTaskFromLinearEvent({
+      stateType: "unstarted",
+      labelNames: [],
+    });
+    expect(decision).toEqual({ create: true, reason: "ready" });
+  });
+
+  test("creates task for started (In Progress) state", () => {
+    const decision = shouldCreateTaskFromLinearEvent({
+      stateType: "started",
+      labelNames: ["bug"],
+    });
+    expect(decision.create).toBe(true);
+  });
+
+  test("skips task for backlog state", () => {
+    const decision = shouldCreateTaskFromLinearEvent({
+      stateType: "backlog",
+      labelNames: [],
+    });
+    expect(decision).toEqual({ create: false, reason: "backlog" });
+  });
+
+  test("skips task for triage state", () => {
+    const decision = shouldCreateTaskFromLinearEvent({
+      stateType: "triage",
+      labelNames: ["needs-review"],
+    });
+    expect(decision).toEqual({ create: false, reason: "triage" });
+  });
+
+  test("swarm-ready label overrides backlog gate", () => {
+    const decision = shouldCreateTaskFromLinearEvent({
+      stateType: "backlog",
+      labelNames: [SWARM_READY_LABEL],
+    });
+    expect(decision).toEqual({ create: true, reason: "label-override" });
+  });
+
+  test("swarm-ready label overrides triage gate", () => {
+    const decision = shouldCreateTaskFromLinearEvent({
+      stateType: "triage",
+      labelNames: ["bug", SWARM_READY_LABEL, "p0"],
+    });
+    expect(decision).toEqual({ create: true, reason: "label-override" });
+  });
+
+  test("label match is case-insensitive", () => {
+    const decision = shouldCreateTaskFromLinearEvent({
+      stateType: "backlog",
+      labelNames: ["Swarm-Ready"],
+    });
+    expect(decision.create).toBe(true);
+  });
+
+  test("state matching is case-insensitive (defensive)", () => {
+    // Linear's enum is lowercase but be defensive in case payload casing varies.
+    const decision = shouldCreateTaskFromLinearEvent({
+      stateType: "Backlog",
+      labelNames: [],
+    });
+    expect(decision).toEqual({ create: false, reason: "backlog" });
+  });
+
+  test("allowed state types pass through", () => {
+    // E.g. completed, canceled — included in default allowlist, trigger as today.
+    expect(shouldCreateTaskFromLinearEvent({ stateType: "completed", labelNames: [] }).create).toBe(
+      true,
+    );
+    expect(shouldCreateTaskFromLinearEvent({ stateType: "canceled", labelNames: [] }).create).toBe(
+      true,
+    );
+  });
+
+  test("null state type allows task creation (fail-open)", () => {
+    // If we couldn't resolve the state for any reason, default to today's
+    // behavior rather than silently swallowing assignments.
+    const decision = shouldCreateTaskFromLinearEvent({
+      stateType: null,
+      labelNames: [],
+    });
+    expect(decision.create).toBe(true);
+  });
+
+  test("DEFAULT_SWARM_READY_LABEL matches today's hardcoded value", () => {
+    expect(DEFAULT_SWARM_READY_LABEL).toBe("swarm-ready");
+    expect(SWARM_READY_LABEL).toBe(DEFAULT_SWARM_READY_LABEL);
+  });
+
+  test("DEFAULT_ALLOWED_STATE_TYPES covers Linear enum minus triage/backlog", () => {
+    expect([...DEFAULT_ALLOWED_STATE_TYPES].sort()).toEqual(
+      ["canceled", "completed", "started", "unstarted"].sort(),
+    );
+  });
+});
+
+describe("shouldCreateTaskFromLinearEvent (env-driven overrides)", () => {
+  const envKeys = ["LINEAR_ALLOWED_STATES", "LINEAR_SWARM_READY_LABEL"] as const;
+  const saved: Record<string, string | undefined> = {};
+
+  beforeEach(() => {
+    for (const k of envKeys) {
+      saved[k] = process.env[k];
+      delete process.env[k];
+    }
+  });
+
+  // Re-snapshot only this scope's env state on cleanup.
+  function restore() {
+    for (const k of envKeys) {
+      if (saved[k] === undefined) delete process.env[k];
+      else process.env[k] = saved[k];
+    }
+  }
+
+  test("LINEAR_ALLOWED_STATES expands the allowlist (e.g. include backlog)", () => {
+    process.env.LINEAR_ALLOWED_STATES = "unstarted,started,backlog";
+    const decision = shouldCreateTaskFromLinearEvent({
+      stateType: "backlog",
+      labelNames: [],
+    });
+    expect(decision).toEqual({ create: true, reason: "ready" });
+    restore();
+  });
+
+  test("LINEAR_ALLOWED_STATES restricts the allowlist (drop completed)", () => {
+    process.env.LINEAR_ALLOWED_STATES = "unstarted,started";
+    const decision = shouldCreateTaskFromLinearEvent({
+      stateType: "completed",
+      labelNames: [],
+    });
+    expect(decision).toEqual({ create: false, reason: "completed" });
+    restore();
+  });
+
+  test("LINEAR_ALLOWED_STATES handles whitespace and case", () => {
+    process.env.LINEAR_ALLOWED_STATES = "  Unstarted ,  STARTED  ,backlog";
+    expect(shouldCreateTaskFromLinearEvent({ stateType: "backlog", labelNames: [] }).create).toBe(
+      true,
+    );
+    expect(shouldCreateTaskFromLinearEvent({ stateType: "completed", labelNames: [] }).create).toBe(
+      false,
+    );
+    restore();
+  });
+
+  test("empty LINEAR_ALLOWED_STATES locks down everything but label override", () => {
+    process.env.LINEAR_ALLOWED_STATES = "";
+    expect(shouldCreateTaskFromLinearEvent({ stateType: "started", labelNames: [] })).toEqual({
+      create: false,
+      reason: "started",
+    });
+    expect(
+      shouldCreateTaskFromLinearEvent({
+        stateType: "started",
+        labelNames: [SWARM_READY_LABEL],
+      }).create,
+    ).toBe(true);
+    restore();
+  });
+
+  test("LINEAR_SWARM_READY_LABEL overrides the bypass label", () => {
+    process.env.LINEAR_SWARM_READY_LABEL = "go-now";
+    // The default label no longer triggers.
+    expect(
+      shouldCreateTaskFromLinearEvent({
+        stateType: "backlog",
+        labelNames: [SWARM_READY_LABEL],
+      }),
+    ).toEqual({ create: false, reason: "backlog" });
+    // The configured label does.
+    expect(
+      shouldCreateTaskFromLinearEvent({
+        stateType: "backlog",
+        labelNames: ["go-now"],
+      }),
+    ).toEqual({ create: true, reason: "label-override" });
+    restore();
+  });
+
+  test("LINEAR_SWARM_READY_LABEL match is case-insensitive", () => {
+    process.env.LINEAR_SWARM_READY_LABEL = "GO-NOW";
+    expect(
+      shouldCreateTaskFromLinearEvent({
+        stateType: "backlog",
+        labelNames: ["Go-Now"],
+      }).create,
+    ).toBe(true);
+    restore();
+  });
+
+  test("getLinearGateConfig reflects env at call time", () => {
+    process.env.LINEAR_ALLOWED_STATES = "started";
+    process.env.LINEAR_SWARM_READY_LABEL = "ship-it";
+    const cfg = getLinearGateConfig();
+    expect(cfg.allowedStateTypes).toEqual(new Set(["started"]));
+    expect(cfg.swarmReadyLabel).toBe("ship-it");
+    restore();
+  });
+
+  test("getLinearGateConfig falls back to defaults when env is unset", () => {
+    const cfg = getLinearGateConfig();
+    expect(cfg.allowedStateTypes).toEqual(new Set(DEFAULT_ALLOWED_STATE_TYPES));
+    expect(cfg.swarmReadyLabel).toBe(DEFAULT_SWARM_READY_LABEL);
+  });
+
+  test("buildSkipMessage uses the configured override label", () => {
+    process.env.LINEAR_SWARM_READY_LABEL = "go-now";
+    const msg = buildSkipMessage("backlog", getLinearGateConfig().swarmReadyLabel);
+    expect(msg).toContain("Backlog");
+    expect(msg).toContain("`go-now`");
+    expect(msg).not.toContain("`swarm-ready`");
+    restore();
+  });
+});
+
+// ─── handleAgentSessionEvent — state-gate skip path ──────────────────────────
+
+describe("handleAgentSessionEvent — state gate", () => {
+  test("skips task creation when issue.state.type is backlog", async () => {
+    const event = {
+      type: "AgentSession",
+      action: "create",
+      agentSession: {
+        id: "session-gate-backlog-001",
+        url: "https://linear.app/team/issue/ENG-500/agent",
+        issue: {
+          id: "issue-gate-backlog-001",
+          identifier: "ENG-500",
+          title: "Backlog ticket",
+          url: "https://linear.app/team/issue/ENG-500",
+          // Inline state/labels so the test doesn't need to mock GraphQL.
+          state: { type: "backlog" },
+          labels: [],
+        },
+      },
+    };
+
+    await handleAgentSessionEvent(event);
+
+    // No tracker_sync should have been created.
+    const sync = getTrackerSyncByExternalId("linear", "task", "issue-gate-backlog-001");
+    expect(sync).toBeNull();
+  });
+
+  test("skips task creation when issue.state.type is triage", async () => {
+    const event = {
+      type: "AgentSession",
+      action: "create",
+      agentSession: {
+        id: "session-gate-triage-001",
+        issue: {
+          id: "issue-gate-triage-001",
+          identifier: "ENG-501",
+          title: "Triage ticket",
+          url: "https://linear.app/team/issue/ENG-501",
+          state: { type: "triage" },
+          labels: { nodes: [] },
+        },
+      },
+    };
+
+    await handleAgentSessionEvent(event);
+
+    const sync = getTrackerSyncByExternalId("linear", "task", "issue-gate-triage-001");
+    expect(sync).toBeNull();
+  });
+
+  test("creates task when issue is in backlog but has swarm-ready label", async () => {
+    const event = {
+      type: "AgentSession",
+      action: "create",
+      agentSession: {
+        id: "session-gate-override-001",
+        issue: {
+          id: "issue-gate-override-001",
+          identifier: "ENG-502",
+          title: "Pre-staged backlog ticket",
+          url: "https://linear.app/team/issue/ENG-502",
+          state: { type: "backlog" },
+          labels: { nodes: [{ name: "bug" }, { name: SWARM_READY_LABEL }] },
+        },
+      },
+    };
+
+    await handleAgentSessionEvent(event);
+
+    const sync = getTrackerSyncByExternalId("linear", "task", "issue-gate-override-001");
+    expect(sync).not.toBeNull();
+    expect(sync!.externalIdentifier).toBe("ENG-502");
+    const task = getTaskById(sync!.swarmId);
+    expect(task).not.toBeNull();
+    expect(task!.source).toBe("linear");
+  });
+
+  test("LINEAR_ALLOWED_STATES env override widens the allowlist end-to-end", async () => {
+    process.env.LINEAR_ALLOWED_STATES = "unstarted,started,backlog";
+    try {
+      const event = {
+        type: "AgentSession",
+        action: "create",
+        agentSession: {
+          id: "session-gate-env-allow-001",
+          issue: {
+            id: "issue-gate-env-allow-001",
+            identifier: "ENG-510",
+            title: "Backlog ticket allowed via env",
+            url: "https://linear.app/team/issue/ENG-510",
+            state: { type: "backlog" },
+            labels: [],
+          },
+        },
+      };
+      await handleAgentSessionEvent(event);
+      const sync = getTrackerSyncByExternalId("linear", "task", "issue-gate-env-allow-001");
+      expect(sync).not.toBeNull();
+    } finally {
+      delete process.env.LINEAR_ALLOWED_STATES;
+    }
+  });
+
+  test("LINEAR_SWARM_READY_LABEL env override is honored end-to-end", async () => {
+    process.env.LINEAR_SWARM_READY_LABEL = "go-now";
+    try {
+      const event = {
+        type: "AgentSession",
+        action: "create",
+        agentSession: {
+          id: "session-gate-env-label-001",
+          issue: {
+            id: "issue-gate-env-label-001",
+            identifier: "ENG-511",
+            title: "Backlog ticket with custom override label",
+            url: "https://linear.app/team/issue/ENG-511",
+            state: { type: "backlog" },
+            labels: { nodes: [{ name: "go-now" }] },
+          },
+        },
+      };
+      await handleAgentSessionEvent(event);
+      const sync = getTrackerSyncByExternalId("linear", "task", "issue-gate-env-label-001");
+      expect(sync).not.toBeNull();
+    } finally {
+      delete process.env.LINEAR_SWARM_READY_LABEL;
+    }
+  });
+
+  test("creates task when issue is in unstarted (Todo) state", async () => {
+    const event = {
+      type: "AgentSession",
+      action: "create",
+      agentSession: {
+        id: "session-gate-todo-001",
+        issue: {
+          id: "issue-gate-todo-001",
+          identifier: "ENG-503",
+          title: "Ready ticket",
+          url: "https://linear.app/team/issue/ENG-503",
+          state: { type: "unstarted" },
+          labels: [],
+        },
+      },
+    };
+
+    await handleAgentSessionEvent(event);
+
+    const sync = getTrackerSyncByExternalId("linear", "task", "issue-gate-todo-001");
+    expect(sync).not.toBeNull();
+  });
+});

package/src/tests/workflow-executors.test.ts

@@ -697,7 +697,7 @@ describe("ValidateExecutor", () => {
 // ─── Registry Wiring ─────────────────────────────────────────
 
 describe("createExecutorRegistry", () => {
-  test("registers all 9 executors (7 instant + 2 async)", () => {
+  test("registers all 10 executors (7 instant + 3 async)", () => {
     const registry = createExecutorRegistry(mockDeps);
     const types = registry.types();
 
@@ -710,7 +710,8 @@ describe("createExecutorRegistry", () => {
     expect(types).toContain("validate");
     expect(types).toContain("agent-task");
     expect(types).toContain("human-in-the-loop");
-    expect(types).toHaveLength(9);
+    expect(types).toContain("wait");
+    expect(types).toHaveLength(10);
   });
 
   test("instant executors have mode instant, async executors have mode async", () => {
@@ -729,6 +730,7 @@ describe("createExecutorRegistry", () => {
     }
     expect(registry.get("agent-task").mode).toBe("async");
     expect(registry.get("human-in-the-loop").mode).toBe("async");
+    expect(registry.get("wait").mode).toBe("async");
   });
 
   test("get() retrieves the correct executor by type", () => {