fix(webapp): stop a zero-limit queue reading as at capacity

A limit of 0 is zero capacity, not saturation: running >= 0 holds for every
queue, so any backlog marked the queue degraded and offered Investigate, while
the agent's own suggested prompt stayed silent. One predicate now decides it
for the queue detail page, the queues list badge and the page mappers.

Author: kathiekiwi

apps/webapp/app/components/dashboard-agent/suggested-prompts/page-mappers.test.ts

@@ -253,6 +253,15 @@ describe("queueAgentPageContext", () => {
     expect(context?.signals).toEqual([]);
   });
 
+  it("emits nothing for a zero-limit queue, which has no capacity to be at", () => {
+    const context = queueAgentPageContext(
+      queueLoaderData({ concurrencyLimit: 0, running: 0, queued: 12 })
+    );
+
+    expect(context?.page).toMatchObject({ health: "warn" });
+    expect(context?.signals).toEqual([]);
+  });
+
   it("returns undefined for data it doesn't recognise", () => {
     expect(queueAgentPageContext(undefined)).toBeUndefined();
     expect(queueAgentPageContext({ queue: { name: "x" } })).toBeUndefined();

apps/webapp/app/components/dashboard-agent/suggested-prompts/page-mappers.ts

@@ -4,6 +4,7 @@
  */
 import type { AgentPageContext, AgentPageSignal } from "@internal/dashboard-agent-contracts";
 import { z } from "zod";
+import { isQueueAtCapacity, OLDEST_WAIT_WARNING_MS } from "~/components/queues/queue-thresholds";
 
 export const FRESH_FAILURE_WINDOW_MS = 30 * 60_000;
 
@@ -149,15 +150,15 @@ export function queuesAgentPageContext(data: unknown): AgentPageContext | undefi
   const limit = concurrencyLimit * (burstFactor && burstFactor > 0 ? burstFactor : 1);
   const signals: AgentPageSignal[] = [];
 
-  if (limit > 0 && running >= limit && queued > 0) {
+  if (isQueueAtCapacity({ running, queued, limit })) {
     signals.push({ kind: "concurrency_saturation", severity: queued >= limit ? "crit" : "warn" });
   }
 
   return { page: { kind: "queues" }, signals };
 }
 
-/** The queue detail route imports this as its `OLDEST_WAIT_WARNING_MS`. */
-export const QUEUE_OLDEST_WAIT_WARNING_MS = 5 * 60_000;
+/** Re-export under the mapper's name; the queue pages own the threshold. */
+export const QUEUE_OLDEST_WAIT_WARNING_MS = OLDEST_WAIT_WARNING_MS;
 
 const queueLoaderDataSchema = z.object({
   queue: z.object({
@@ -202,7 +203,7 @@ export function queueAgentPageContext(data: unknown): AgentPageContext | undefin
   const { name, paused, running, queued, concurrencyLimit } = parsed.data.queue;
   const { environmentConcurrencyLimit, oldestQueuedAt, loadedAt, ckBreakdown } = parsed.data;
   const limit = concurrencyLimit ?? environmentConcurrencyLimit ?? null;
-  const atCapacity = limit !== null && limit > 0 && running >= limit && queued > 0;
+  const atCapacity = isQueueAtCapacity({ running, queued, limit });
 
   const oldestWait = oldestWaitMs(ckBreakdown?.keys ?? [], oldestQueuedAt, loadedAt);
   const waitingTooLong = oldestWait !== null && oldestWait >= QUEUE_OLDEST_WAIT_WARNING_MS;

apps/webapp/app/components/queues/queue-thresholds.test.ts

@@ -0,0 +1,59 @@
+import { describe, expect, it } from "vitest";
+import { isQueueAtCapacity, isQueueDegraded, OLDEST_WAIT_WARNING_MS } from "./queue-thresholds";
+
+describe("isQueueAtCapacity", () => {
+  it("is false for a zero limit with a backlog", () => {
+    expect(isQueueAtCapacity({ running: 0, queued: 12, limit: 0 })).toBe(false);
+    expect(isQueueAtCapacity({ running: 3, queued: 12, limit: 0 })).toBe(false);
+  });
+
+  it("is false when no limit is known", () => {
+    expect(isQueueAtCapacity({ running: 5, queued: 12, limit: null })).toBe(false);
+    expect(isQueueAtCapacity({ running: 5, queued: 12, limit: undefined })).toBe(false);
+  });
+
+  it("is true when a positive limit is full and work is waiting", () => {
+    expect(isQueueAtCapacity({ running: 10, queued: 4, limit: 10 })).toBe(true);
+    expect(isQueueAtCapacity({ running: 11, queued: 1, limit: 10 })).toBe(true);
+  });
+
+  it("is false when the limit is full but nothing is waiting", () => {
+    expect(isQueueAtCapacity({ running: 10, queued: 0, limit: 10 })).toBe(false);
+  });
+});
+
+describe("isQueueDegraded", () => {
+  const base = { paused: false, oldestWaitMs: null };
+
+  it("does not degrade a zero-limit queue with a backlog", () => {
+    expect(isQueueDegraded({ ...base, running: 0, queued: 12, limit: 0 })).toBe(false);
+  });
+
+  it("degrades a saturated queue", () => {
+    expect(isQueueDegraded({ ...base, running: 10, queued: 4, limit: 10 })).toBe(true);
+  });
+
+  it("degrades on head-of-line wait regardless of the limit", () => {
+    expect(
+      isQueueDegraded({
+        paused: false,
+        running: 0,
+        queued: 12,
+        limit: 0,
+        oldestWaitMs: OLDEST_WAIT_WARNING_MS,
+      })
+    ).toBe(true);
+  });
+
+  it("never degrades a paused queue", () => {
+    expect(
+      isQueueDegraded({
+        paused: true,
+        running: 10,
+        queued: 4,
+        limit: 10,
+        oldestWaitMs: OLDEST_WAIT_WARNING_MS * 10,
+      })
+    ).toBe(false);
+  });
+});

apps/webapp/app/components/queues/queue-thresholds.ts

@@ -1,2 +1,35 @@
 /** Head-of-line wait at which a queue reads as stuck. */
 export const OLDEST_WAIT_WARNING_MS = 5 * 60_000;
+
+export type QueueCapacity = {
+  running: number;
+  queued: number;
+  /** Effective limit: the queue's own, else the environment's. Null when neither is set. */
+  limit: number | null | undefined;
+};
+
+/**
+ * Saturation: the queue is running everything it is allowed to and still has a backlog.
+ * A limit of 0 is zero capacity, not saturation — `running >= 0` holds for every queue, so
+ * without the guard any backlog would read as saturated.
+ */
+export function isQueueAtCapacity({ running, queued, limit }: QueueCapacity): boolean {
+  if (limit === null || limit === undefined || limit <= 0) return false;
+  return running >= limit && queued > 0;
+}
+
+/** Whether the queue detail page offers Investigate. Paused is a state, not a fault. */
+export function isQueueDegraded({
+  paused,
+  oldestWaitMs,
+  ...capacity
+}: QueueCapacity & {
+  paused: boolean | null | undefined;
+  oldestWaitMs: number | null | undefined;
+}): boolean {
+  if (paused) return false;
+  if (isQueueAtCapacity(capacity)) return true;
+  return (
+    oldestWaitMs !== null && oldestWaitMs !== undefined && oldestWaitMs >= OLDEST_WAIT_WARNING_MS
+  );
+}

apps/webapp/app/routes/_app.orgs.$organizationSlug.projects.$projectParam.env.$envParam.queues/route.tsx

@@ -114,6 +114,7 @@ import {
   useRememberQueueMetricsPeriod,
 } from "~/components/queues/queueMetricsPeriod";
 import { queueMetricsMaxPeriodDays } from "~/components/queues/queueMetricsPeriod.server";
+import { isQueueAtCapacity } from "~/components/queues/queue-thresholds";
 import { pageMeta } from "~/utils/pageTitle";
 
 const SearchParamsSchema = z.object({
@@ -1607,7 +1608,7 @@ type QueueHealthLabel = "Paused" | "At capacity" | "Backlogged" | "Active" | "Id
 // health-column sort so the sorted order always matches the labels shown.
 function queueHealthLabel({ paused, running, queued, limit }: QueueHealth): QueueHealthLabel {
   if (paused) return "Paused";
-  if (running >= limit && queued > 0) return "At capacity";
+  if (isQueueAtCapacity({ running, queued, limit })) return "At capacity";
   if (queued > 0) return "Backlogged";
   if (running > 0) return "Active";
   return "Idle";

apps/webapp/app/routes/_app.orgs.$organizationSlug.projects.$projectParam.env.$envParam.queues_.$queueParam/route.tsx

@@ -8,7 +8,7 @@ import { MetricsLayout } from "~/components/layout/MetricsLayout";
 import { AnimatedOrgBannerBar } from "~/components/billing/AnimatedOrgBannerBar";
 import { BigNumber } from "~/components/metrics/BigNumber";
 import { Header3 } from "~/components/primitives/Headers";
-import { OLDEST_WAIT_WARNING_MS } from "~/components/queues/queue-thresholds";
+import { isQueueDegraded, OLDEST_WAIT_WARNING_MS } from "~/components/queues/queue-thresholds";
 import { NavBar, PageTitle } from "~/components/primitives/PageHeader";
 import { Spinner } from "~/components/primitives/Spinner";
 import { buildActivityTimeAxis } from "~/components/primitives/charts/activityTimeAxis";
@@ -277,11 +277,13 @@ export default function Page() {
   const selectedKey = value("key");
 
   const oldestWaitMs = wholeQueueOldestWaitMs(ckBreakdown, oldestQueuedAt, loadedAt);
-  const concurrencyLimit = queue.concurrencyLimit ?? environmentConcurrencyLimit;
-  const degraded =
-    !queue.paused &&
-    ((queue.running >= concurrencyLimit && queue.queued > 0) ||
-      (oldestWaitMs !== null && oldestWaitMs >= OLDEST_WAIT_WARNING_MS));
+  const degraded = isQueueDegraded({
+    paused: queue.paused,
+    running: queue.running,
+    queued: queue.queued,
+    limit: queue.concurrencyLimit ?? environmentConcurrencyLimit,
+    oldestWaitMs,
+  });
 
   return (
     <PageContainer>

apps/webapp/vitest.config.ts

@@ -19,6 +19,7 @@ export default defineConfig({
       "app/runEngine/services/**/*.test.ts",
       "app/utils/**/*.test.ts",
       "app/components/dashboard-agent/**/*.test.ts",
+      "app/components/queues/**/*.test.ts",
     ],
     // *.e2e.test.ts: smoke matrix, run via vitest.e2e.config.ts.
     // *.e2e.full.test.ts: full auth suite, runs via vitest.e2e.full.config.ts