feat: add configurable BullMQ worker stall options to prevent duplicate job retries

[Nek-11]

Problem

BullMQ's default stall detection uses a 30-second interval with 1 automatic retry (maxStalledCount: 1). Long-running jobs — such as document store upserts that involve web scraping and LLM summarisation — frequently exceed this threshold and get silently retried.

This causes the entire job to re-run, reinserting all vector embeddings into the database. Even with a record manager in full cleanup mode, the mid-stall inconsistency means duplicates slip through, resulting in a bloated vector store.

Solution

Expose BullMQ's stalledInterval and maxStalledCount Worker options as environment variables so operators can tune them for their workload:

Variable	Default	Description
WORKER_STALLED_INTERVAL	300000 (5 min)	How often BullMQ checks for stalled jobs (ms)
WORKER_MAX_STALLED_COUNT	0	How many times a stalled job is retried before failing

The new defaults are intentionally conservative:

• 5 minute stall interval gives long-running jobs breathing room before being considered stalled
• 0 retries means a stalled job fails cleanly rather than being silently re-executed, preventing duplicate side effects

Operators who prefer the old retry behaviour can set WORKER_MAX_STALLED_COUNT=1 to restore it.

Changes

• packages/server/src/queue/BaseQueue.ts: added WORKER_STALLED_INTERVAL and WORKER_MAX_STALLED_COUNT constants read from env, passed to the BullMQ Worker constructor

[gemini-code-assist]

Code Review

This pull request introduces two new environment variables, WORKER_STALLED_INTERVAL and WORKER_MAX_STALLED_COUNT, to configure the stalled job interval and maximum stalled count for the queue worker in BaseQueue.ts. The reviewer suggested explicitly specifying the radix in parseInt and implementing fail-fast validation to throw an error if the environment variables contain invalid non-numeric values, rather than silently falling back to defaults.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[gemini-code-assist]

When parsing environment variables with parseInt, it is safer to specify the radix (base 10) explicitly to avoid any parsing ambiguity. Additionally, if the environment variable is set to an invalid non-numeric value, parseInt will return NaN. To promote fail-fast behavior, we should throw an error for invalid input types from external sources (like environment variables) rather than silently falling back to a default value.

const WORKER_STALLED_INTERVAL = (() => {
  const val = process.env.WORKER_STALLED_INTERVAL;
  if (!val) return 300000;
  const parsed = parseInt(val, 10);
  if (isNaN(parsed)) throw new Error("Invalid WORKER_STALLED_INTERVAL");
  return parsed;
})();
const WORKER_MAX_STALLED_COUNT = (() => {
  const val = process.env.WORKER_MAX_STALLED_COUNT;
  if (!val) return 0;
  const parsed = parseInt(val, 10);
  if (isNaN(parsed)) throw new Error("Invalid WORKER_MAX_STALLED_COUNT");
  return parsed;
})();

References

1. When handling potentially invalid data from external sources (like an API response), prefer throwing an error for invalid input types rather than silently returning a default or empty value. This promotes fail-fast behavior.

[Nek-11]

/gemini review again please

[gemini-code-assist]

Code Review

This pull request introduces configurable worker stalled interval and max stalled count settings parsed from environment variables, along with validation checks. The review feedback suggests using nullish coalescing (??) instead of ternary operators for more idiomatic TypeScript environment variable fallbacks, and wrapping the if statement bodies in curly braces for better maintainability.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.