@open-mercato/queue 0.6.1-develop.3167.1.7aedd7b2ba → 0.6.1-develop.3179.1.9ee0441adc

package/.turbo/turbo-build.log

@@ -1,2 +1,2 @@
-[build:queue] found 7 entry points
+[build:queue] found 8 entry points
 [build:queue] built successfully

package/dist/index.js

@@ -2,10 +2,12 @@ export * from "./types.js";
 import { createQueue, createModuleQueue, resolveQueueStrategy } from "./factory.js";
 export * from "./worker/registry.js";
 import { runWorker, createRoutedHandler } from "./worker/runner.js";
+import { getQueuePendingProbe } from "./pending-probe.js";
 export {
   createModuleQueue,
   createQueue,
   createRoutedHandler,
+  getQueuePendingProbe,
   resolveQueueStrategy,
   runWorker
 };

package/dist/index.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../src/index.ts"],
-  "sourcesContent": ["/**\n * @open-mercato/queue\n *\n * Multi-strategy job queue package supporting local (file-based) and async (BullMQ) strategies.\n *\n * @example\n * ```typescript\n * import { createQueue } from '@open-mercato/queue'\n *\n * // Create a local queue\n * const queue = createQueue<{ userId: string }>('my-queue', 'local')\n *\n * // Enqueue a job\n * await queue.enqueue({ userId: '123' })\n *\n * // Process jobs\n * await queue.process(async (job, ctx) => {\n *   console.log(`Processing job ${ctx.jobId}:`, job.payload)\n * })\n * ```\n */\n\nexport * from './types'\nexport { createQueue, createModuleQueue, resolveQueueStrategy } from './factory'\n\n// Worker utilities\nexport * from './worker/registry'\nexport { runWorker, createRoutedHandler } from './worker/runner'\n"],
-  "mappings": "AAsBA,cAAc;AACd,SAAS,aAAa,mBAAmB,4BAA4B;AAGrE,cAAc;AACd,SAAS,WAAW,2BAA2B;",
+  "sourcesContent": ["/**\n * @open-mercato/queue\n *\n * Multi-strategy job queue package supporting local (file-based) and async (BullMQ) strategies.\n *\n * @example\n * ```typescript\n * import { createQueue } from '@open-mercato/queue'\n *\n * // Create a local queue\n * const queue = createQueue<{ userId: string }>('my-queue', 'local')\n *\n * // Enqueue a job\n * await queue.enqueue({ userId: '123' })\n *\n * // Process jobs\n * await queue.process(async (job, ctx) => {\n *   console.log(`Processing job ${ctx.jobId}:`, job.payload)\n * })\n * ```\n */\n\nexport * from './types'\nexport { createQueue, createModuleQueue, resolveQueueStrategy } from './factory'\n\n// Worker utilities\nexport * from './worker/registry'\nexport { runWorker, createRoutedHandler } from './worker/runner'\n\n// Lightweight pending-job probes used by the lazy auto-spawn supervisor.\nexport { getQueuePendingProbe } from './pending-probe'\nexport type { QueuePendingProbeOptions, QueuePendingProbeResult } from './pending-probe'\n"],
+  "mappings": "AAsBA,cAAc;AACd,SAAS,aAAa,mBAAmB,4BAA4B;AAGrE,cAAc;AACd,SAAS,WAAW,2BAA2B;AAG/C,SAAS,4BAA4B;",
   "names": []
 }

package/dist/pending-probe.js

@@ -0,0 +1,127 @@
+import fs from "node:fs";
+import path from "node:path";
+const DEFAULT_LOCAL_QUEUE_BASE_DIR = ".mercato/queue";
+const fsp = fs.promises;
+function emptyResult(queueName, strategy) {
+  return { queueName, strategy, ready: 0, delayedFuture: 0, active: 0, error: false };
+}
+function errorResult(queueName, strategy, err) {
+  const message = err instanceof Error ? err.message : String(err);
+  return {
+    queueName,
+    strategy,
+    ready: 0,
+    delayedFuture: 0,
+    active: 0,
+    error: true,
+    errorMessage: message
+  };
+}
+async function probeLocalQueue(queueName, options) {
+  const nodeProcess = globalThis.process;
+  const envBaseDir = nodeProcess?.env?.QUEUE_BASE_DIR;
+  const baseDir = options?.baseDir ?? path.resolve(envBaseDir || DEFAULT_LOCAL_QUEUE_BASE_DIR);
+  const queueFile = path.join(baseDir, queueName, "queue.json");
+  let raw;
+  try {
+    raw = await fsp.readFile(queueFile, "utf8");
+  } catch (err) {
+    const fsErr = err;
+    if (fsErr?.code === "ENOENT") {
+      return emptyResult(queueName, "local");
+    }
+    return errorResult(queueName, "local", err);
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    return errorResult(queueName, "local", err);
+  }
+  if (!Array.isArray(parsed)) {
+    return emptyResult(queueName, "local");
+  }
+  const now = Date.now();
+  let ready = 0;
+  let delayedFuture = 0;
+  for (const entry of parsed) {
+    if (!entry || typeof entry !== "object") continue;
+    const availableAt = entry.availableAt;
+    if (typeof availableAt !== "string" || availableAt.length === 0) {
+      ready++;
+      continue;
+    }
+    const ts = Date.parse(availableAt);
+    if (!Number.isFinite(ts) || ts <= now) {
+      ready++;
+    } else {
+      delayedFuture++;
+    }
+  }
+  return { queueName, strategy: "local", ready, delayedFuture, active: 0, error: false };
+}
+let cachedBullMQ;
+async function loadBullMQ() {
+  if (cachedBullMQ !== void 0) return cachedBullMQ;
+  try {
+    cachedBullMQ = await import("bullmq");
+  } catch {
+    cachedBullMQ = null;
+  }
+  return cachedBullMQ;
+}
+async function probeAsyncQueue(queueName, options) {
+  const bullmq = await loadBullMQ();
+  if (!bullmq) {
+    return errorResult(queueName, "async", new Error("bullmq is not installed"));
+  }
+  const { getRedisUrl } = await import("@open-mercato/shared/lib/redis/connection");
+  let connection = options?.connection;
+  if (!connection) {
+    const url = getRedisUrl("QUEUE");
+    if (!url) {
+      return errorResult(queueName, "async", new Error("QUEUE Redis URL is not configured"));
+    }
+    connection = { url };
+  }
+  let queue = null;
+  try {
+    queue = new bullmq.Queue(queueName, { connection });
+    const counts = await queue.getJobCounts("waiting", "delayed", "active");
+    const waiting = counts.waiting ?? 0;
+    const delayed = counts.delayed ?? 0;
+    const active = counts.active ?? 0;
+    return {
+      queueName,
+      strategy: "async",
+      ready: waiting,
+      delayedFuture: delayed,
+      active,
+      error: false
+    };
+  } catch (err) {
+    return errorResult(queueName, "async", err);
+  } finally {
+    if (queue) {
+      try {
+        await queue.close();
+      } catch {
+      }
+    }
+  }
+}
+async function getQueuePendingProbe(queueName, strategy, options) {
+  const resolvedStrategy = strategy ?? (process.env.QUEUE_STRATEGY === "async" ? "async" : "local");
+  if (resolvedStrategy === "async") {
+    return probeAsyncQueue(queueName, options);
+  }
+  return probeLocalQueue(queueName, options);
+}
+function __resetPendingProbeBullMQCache() {
+  cachedBullMQ = void 0;
+}
+export {
+  __resetPendingProbeBullMQCache,
+  getQueuePendingProbe
+};
+//# sourceMappingURL=pending-probe.js.map

package/dist/pending-probe.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/pending-probe.ts"],
+  "sourcesContent": ["/**\n * Lightweight pending-job probe helpers.\n *\n * Used by the lazy worker supervisor to detect whether a queue has a\n * ready-to-process job before spawning a long-lived worker process for it.\n *\n * The probes MUST NOT:\n * - call `queue.process()` or otherwise install handlers\n * - import any module worker handler code\n * - create BullMQ `Worker` instances\n *\n * Probes are best-effort and fail-soft: a probe error returns \"no pending\"\n * so the supervisor can keep polling instead of crashing the runtime.\n */\n\nimport fs from 'node:fs'\nimport path from 'node:path'\nimport type { QueueStrategyType, RedisConnectionOptions } from './types'\n\nexport type QueuePendingProbeOptions = {\n  /** Async strategy: Redis connection override (mirrors `AsyncQueueOptions['connection']`). */\n  connection?: RedisConnectionOptions\n  /** Local strategy: override `QUEUE_BASE_DIR` for test isolation. */\n  baseDir?: string\n}\n\nexport type QueuePendingProbeResult = {\n  queueName: string\n  strategy: QueueStrategyType\n  /** Number of jobs ready to process now (no delay or delay already elapsed). */\n  ready: number\n  /** Number of jobs scheduled for the future (still waiting on `availableAt`). */\n  delayedFuture: number\n  /** Number of jobs currently being processed. May be unavailable for some strategies. */\n  active: number\n  /**\n   * True when the probe could not query the underlying storage at all\n   * (filesystem error, Redis unreachable, optional dependency missing, etc.).\n   * The supervisor treats `error: true` as \"do not start worker yet\".\n   */\n  error: boolean\n  errorMessage?: string\n}\n\nconst DEFAULT_LOCAL_QUEUE_BASE_DIR = '.mercato/queue'\n\nconst fsp = fs.promises\n\nfunction emptyResult(queueName: string, strategy: QueueStrategyType): QueuePendingProbeResult {\n  return { queueName, strategy, ready: 0, delayedFuture: 0, active: 0, error: false }\n}\n\nfunction errorResult(\n  queueName: string,\n  strategy: QueueStrategyType,\n  err: unknown,\n): QueuePendingProbeResult {\n  const message = err instanceof Error ? err.message : String(err)\n  return {\n    queueName,\n    strategy,\n    ready: 0,\n    delayedFuture: 0,\n    active: 0,\n    error: true,\n    errorMessage: message,\n  }\n}\n\nasync function probeLocalQueue(\n  queueName: string,\n  options?: QueuePendingProbeOptions,\n): Promise<QueuePendingProbeResult> {\n  const nodeProcess = (globalThis as typeof globalThis & { process?: NodeJS.Process }).process\n  const envBaseDir = nodeProcess?.env?.QUEUE_BASE_DIR\n  const baseDir = options?.baseDir\n    ?? path.resolve(envBaseDir || DEFAULT_LOCAL_QUEUE_BASE_DIR)\n  const queueFile = path.join(baseDir, queueName, 'queue.json')\n\n  let raw: string\n  try {\n    raw = await fsp.readFile(queueFile, 'utf8')\n  } catch (err) {\n    const fsErr = err as NodeJS.ErrnoException\n    if (fsErr?.code === 'ENOENT') {\n      return emptyResult(queueName, 'local')\n    }\n    return errorResult(queueName, 'local', err)\n  }\n\n  let parsed: unknown\n  try {\n    parsed = JSON.parse(raw)\n  } catch (err) {\n    return errorResult(queueName, 'local', err)\n  }\n\n  if (!Array.isArray(parsed)) {\n    return emptyResult(queueName, 'local')\n  }\n\n  const now = Date.now()\n  let ready = 0\n  let delayedFuture = 0\n\n  for (const entry of parsed) {\n    if (!entry || typeof entry !== 'object') continue\n    const availableAt = (entry as { availableAt?: unknown }).availableAt\n    if (typeof availableAt !== 'string' || availableAt.length === 0) {\n      ready++\n      continue\n    }\n    const ts = Date.parse(availableAt)\n    if (!Number.isFinite(ts) || ts <= now) {\n      ready++\n    } else {\n      delayedFuture++\n    }\n  }\n\n  return { queueName, strategy: 'local', ready, delayedFuture, active: 0, error: false }\n}\n\ntype BullMQModuleShape = {\n  Queue: new <T>(name: string, opts: { connection: RedisConnectionOptions }) => {\n    getJobCounts: (...states: string[]) => Promise<Record<string, number>>\n    close: () => Promise<void>\n  }\n}\n\nlet cachedBullMQ: BullMQModuleShape | null | undefined\n\nasync function loadBullMQ(): Promise<BullMQModuleShape | null> {\n  if (cachedBullMQ !== undefined) return cachedBullMQ\n  try {\n    cachedBullMQ = (await import('bullmq')) as unknown as BullMQModuleShape\n  } catch {\n    cachedBullMQ = null\n  }\n  return cachedBullMQ\n}\n\nasync function probeAsyncQueue(\n  queueName: string,\n  options?: QueuePendingProbeOptions,\n): Promise<QueuePendingProbeResult> {\n  const bullmq = await loadBullMQ()\n  if (!bullmq) {\n    return errorResult(queueName, 'async', new Error('bullmq is not installed'))\n  }\n\n  const { getRedisUrl } = await import('@open-mercato/shared/lib/redis/connection')\n  let connection = options?.connection\n  if (!connection) {\n    const url = getRedisUrl('QUEUE')\n    if (!url) {\n      return errorResult(queueName, 'async', new Error('QUEUE Redis URL is not configured'))\n    }\n    connection = { url }\n  }\n\n  let queue: InstanceType<BullMQModuleShape['Queue']> | null = null\n  try {\n    queue = new bullmq.Queue(queueName, { connection })\n    const counts = await queue.getJobCounts('waiting', 'delayed', 'active')\n    const waiting = counts.waiting ?? 0\n    const delayed = counts.delayed ?? 0\n    const active = counts.active ?? 0\n    return {\n      queueName,\n      strategy: 'async',\n      ready: waiting,\n      delayedFuture: delayed,\n      active,\n      error: false,\n    }\n  } catch (err) {\n    return errorResult(queueName, 'async', err)\n  } finally {\n    if (queue) {\n      try {\n        await queue.close()\n      } catch {\n        /* swallow shutdown errors \u2014 probe must not throw on cleanup */\n      }\n    }\n  }\n}\n\n/**\n * Read-only pending-job probe for a queue.\n *\n * `strategy` defaults to the value of `QUEUE_STRATEGY` (via\n * `resolveQueueStrategy`). The probe never installs handlers and never\n * starts a BullMQ Worker, so it is safe to call from a lightweight\n * supervisor process that watches many queues.\n */\nexport async function getQueuePendingProbe(\n  queueName: string,\n  strategy?: QueueStrategyType,\n  options?: QueuePendingProbeOptions,\n): Promise<QueuePendingProbeResult> {\n  const resolvedStrategy: QueueStrategyType = strategy\n    ?? (process.env.QUEUE_STRATEGY === 'async' ? 'async' : 'local')\n\n  if (resolvedStrategy === 'async') {\n    return probeAsyncQueue(queueName, options)\n  }\n  return probeLocalQueue(queueName, options)\n}\n\n/** Reset the cached bullmq module reference. Test-only. */\nexport function __resetPendingProbeBullMQCache(): void {\n  cachedBullMQ = undefined\n}\n"],
+  "mappings": "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",
+  "names": []
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-mercato/queue",
-  "version": "0.6.1-develop.3167.1.7aedd7b2ba",
+  "version": "0.6.1-develop.3179.1.9ee0441adc",
   "description": "Multi-strategy job queue with local and BullMQ support",
   "type": "module",
   "main": "./dist/index.js",
@@ -50,7 +50,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@open-mercato/shared": "0.6.1-develop.3167.1.7aedd7b2ba"
+    "@open-mercato/shared": "0.6.1-develop.3179.1.9ee0441adc"
   },
   "repository": {
     "type": "git",

package/src/__tests__/pending-probe.test.ts

@@ -0,0 +1,112 @@
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { createQueue } from '../factory'
+import { getQueuePendingProbe } from '../pending-probe'
+
+describe('getQueuePendingProbe — local strategy', () => {
+  const origCwd = process.cwd()
+  let tmp: string
+
+  beforeEach(() => {
+    tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'queue-probe-test-'))
+    process.chdir(tmp)
+  })
+
+  afterEach(() => {
+    process.chdir(origCwd)
+    try {
+      fs.rmSync(tmp, { recursive: true, force: true })
+    } catch {
+      /* ignore cleanup errors */
+    }
+  })
+
+  it('returns zero when the queue does not exist yet', async () => {
+    const probe = await getQueuePendingProbe('does-not-exist', 'local', { baseDir: tmp })
+    expect(probe.error).toBe(false)
+    expect(probe.ready).toBe(0)
+    expect(probe.delayedFuture).toBe(0)
+  })
+
+  it('counts ready jobs without invoking handlers', async () => {
+    const queue = createQueue<{ value: number }>('probe-queue', 'local', { baseDir: tmp })
+    await queue.enqueue({ value: 1 })
+    await queue.enqueue({ value: 2 })
+    await queue.close()
+
+    const probe = await getQueuePendingProbe('probe-queue', 'local', { baseDir: tmp })
+    expect(probe.error).toBe(false)
+    expect(probe.ready).toBe(2)
+    expect(probe.delayedFuture).toBe(0)
+  })
+
+  it('treats future-delayed jobs as not ready', async () => {
+    const queue = createQueue<{ value: number }>('probe-queue', 'local', { baseDir: tmp })
+    await queue.enqueue({ value: 1 }, { delayMs: 60_000 })
+    await queue.close()
+
+    const probe = await getQueuePendingProbe('probe-queue', 'local', { baseDir: tmp })
+    expect(probe.ready).toBe(0)
+    expect(probe.delayedFuture).toBe(1)
+  })
+
+  it('treats already-elapsed delayed jobs as ready', async () => {
+    const queueDir = path.join(tmp, 'probe-queue')
+    fs.mkdirSync(queueDir, { recursive: true })
+    const past = new Date(Date.now() - 1000).toISOString()
+    fs.writeFileSync(
+      path.join(queueDir, 'queue.json'),
+      JSON.stringify([
+        {
+          id: 'past-job',
+          payload: { value: 1 },
+          createdAt: new Date().toISOString(),
+          availableAt: past,
+        },
+      ]),
+      'utf8',
+    )
+
+    const probe = await getQueuePendingProbe('probe-queue', 'local', { baseDir: tmp })
+    expect(probe.ready).toBe(1)
+    expect(probe.delayedFuture).toBe(0)
+  })
+
+  it('returns a soft error when queue.json is corrupt', async () => {
+    const queueDir = path.join(tmp, 'corrupt-queue')
+    fs.mkdirSync(queueDir, { recursive: true })
+    fs.writeFileSync(path.join(queueDir, 'queue.json'), '{ not valid json', 'utf8')
+
+    const probe = await getQueuePendingProbe('corrupt-queue', 'local', { baseDir: tmp })
+    expect(probe.error).toBe(true)
+    expect(probe.ready).toBe(0)
+  })
+
+  it('does not run the worker handler', async () => {
+    const queue = createQueue<{ value: number }>('handler-check', 'local', { baseDir: tmp })
+    const handler = jest.fn()
+    await queue.enqueue({ value: 1 })
+    await queue.close()
+
+    await getQueuePendingProbe('handler-check', 'local', { baseDir: tmp })
+    expect(handler).not.toHaveBeenCalled()
+  })
+})
+
+describe('getQueuePendingProbe — async strategy', () => {
+  it('reports an error when QUEUE Redis URL is unset and no connection override is provided', async () => {
+    const original = process.env.QUEUE_REDIS_URL
+    const fallback = process.env.REDIS_URL
+    delete process.env.QUEUE_REDIS_URL
+    delete process.env.REDIS_URL
+    try {
+      const probe = await getQueuePendingProbe('no-redis-queue', 'async')
+      // Either bullmq is missing (cached load failed) or Redis URL missing — both surface as error
+      expect(probe.error).toBe(true)
+    } finally {
+      if (original !== undefined) process.env.QUEUE_REDIS_URL = original
+      if (fallback !== undefined) process.env.REDIS_URL = fallback
+    }
+  })
+})

package/src/index.ts

@@ -26,3 +26,7 @@ export { createQueue, createModuleQueue, resolveQueueStrategy } from './factory'
 // Worker utilities
 export * from './worker/registry'
 export { runWorker, createRoutedHandler } from './worker/runner'
+
+// Lightweight pending-job probes used by the lazy auto-spawn supervisor.
+export { getQueuePendingProbe } from './pending-probe'
+export type { QueuePendingProbeOptions, QueuePendingProbeResult } from './pending-probe'

package/src/pending-probe.ts

@@ -0,0 +1,215 @@
+/**
+ * Lightweight pending-job probe helpers.
+ *
+ * Used by the lazy worker supervisor to detect whether a queue has a
+ * ready-to-process job before spawning a long-lived worker process for it.
+ *
+ * The probes MUST NOT:
+ * - call `queue.process()` or otherwise install handlers
+ * - import any module worker handler code
+ * - create BullMQ `Worker` instances
+ *
+ * Probes are best-effort and fail-soft: a probe error returns "no pending"
+ * so the supervisor can keep polling instead of crashing the runtime.
+ */
+
+import fs from 'node:fs'
+import path from 'node:path'
+import type { QueueStrategyType, RedisConnectionOptions } from './types'
+
+export type QueuePendingProbeOptions = {
+  /** Async strategy: Redis connection override (mirrors `AsyncQueueOptions['connection']`). */
+  connection?: RedisConnectionOptions
+  /** Local strategy: override `QUEUE_BASE_DIR` for test isolation. */
+  baseDir?: string
+}
+
+export type QueuePendingProbeResult = {
+  queueName: string
+  strategy: QueueStrategyType
+  /** Number of jobs ready to process now (no delay or delay already elapsed). */
+  ready: number
+  /** Number of jobs scheduled for the future (still waiting on `availableAt`). */
+  delayedFuture: number
+  /** Number of jobs currently being processed. May be unavailable for some strategies. */
+  active: number
+  /**
+   * True when the probe could not query the underlying storage at all
+   * (filesystem error, Redis unreachable, optional dependency missing, etc.).
+   * The supervisor treats `error: true` as "do not start worker yet".
+   */
+  error: boolean
+  errorMessage?: string
+}
+
+const DEFAULT_LOCAL_QUEUE_BASE_DIR = '.mercato/queue'
+
+const fsp = fs.promises
+
+function emptyResult(queueName: string, strategy: QueueStrategyType): QueuePendingProbeResult {
+  return { queueName, strategy, ready: 0, delayedFuture: 0, active: 0, error: false }
+}
+
+function errorResult(
+  queueName: string,
+  strategy: QueueStrategyType,
+  err: unknown,
+): QueuePendingProbeResult {
+  const message = err instanceof Error ? err.message : String(err)
+  return {
+    queueName,
+    strategy,
+    ready: 0,
+    delayedFuture: 0,
+    active: 0,
+    error: true,
+    errorMessage: message,
+  }
+}
+
+async function probeLocalQueue(
+  queueName: string,
+  options?: QueuePendingProbeOptions,
+): Promise<QueuePendingProbeResult> {
+  const nodeProcess = (globalThis as typeof globalThis & { process?: NodeJS.Process }).process
+  const envBaseDir = nodeProcess?.env?.QUEUE_BASE_DIR
+  const baseDir = options?.baseDir
+    ?? path.resolve(envBaseDir || DEFAULT_LOCAL_QUEUE_BASE_DIR)
+  const queueFile = path.join(baseDir, queueName, 'queue.json')
+
+  let raw: string
+  try {
+    raw = await fsp.readFile(queueFile, 'utf8')
+  } catch (err) {
+    const fsErr = err as NodeJS.ErrnoException
+    if (fsErr?.code === 'ENOENT') {
+      return emptyResult(queueName, 'local')
+    }
+    return errorResult(queueName, 'local', err)
+  }
+
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(raw)
+  } catch (err) {
+    return errorResult(queueName, 'local', err)
+  }
+
+  if (!Array.isArray(parsed)) {
+    return emptyResult(queueName, 'local')
+  }
+
+  const now = Date.now()
+  let ready = 0
+  let delayedFuture = 0
+
+  for (const entry of parsed) {
+    if (!entry || typeof entry !== 'object') continue
+    const availableAt = (entry as { availableAt?: unknown }).availableAt
+    if (typeof availableAt !== 'string' || availableAt.length === 0) {
+      ready++
+      continue
+    }
+    const ts = Date.parse(availableAt)
+    if (!Number.isFinite(ts) || ts <= now) {
+      ready++
+    } else {
+      delayedFuture++
+    }
+  }
+
+  return { queueName, strategy: 'local', ready, delayedFuture, active: 0, error: false }
+}
+
+type BullMQModuleShape = {
+  Queue: new <T>(name: string, opts: { connection: RedisConnectionOptions }) => {
+    getJobCounts: (...states: string[]) => Promise<Record<string, number>>
+    close: () => Promise<void>
+  }
+}
+
+let cachedBullMQ: BullMQModuleShape | null | undefined
+
+async function loadBullMQ(): Promise<BullMQModuleShape | null> {
+  if (cachedBullMQ !== undefined) return cachedBullMQ
+  try {
+    cachedBullMQ = (await import('bullmq')) as unknown as BullMQModuleShape
+  } catch {
+    cachedBullMQ = null
+  }
+  return cachedBullMQ
+}
+
+async function probeAsyncQueue(
+  queueName: string,
+  options?: QueuePendingProbeOptions,
+): Promise<QueuePendingProbeResult> {
+  const bullmq = await loadBullMQ()
+  if (!bullmq) {
+    return errorResult(queueName, 'async', new Error('bullmq is not installed'))
+  }
+
+  const { getRedisUrl } = await import('@open-mercato/shared/lib/redis/connection')
+  let connection = options?.connection
+  if (!connection) {
+    const url = getRedisUrl('QUEUE')
+    if (!url) {
+      return errorResult(queueName, 'async', new Error('QUEUE Redis URL is not configured'))
+    }
+    connection = { url }
+  }
+
+  let queue: InstanceType<BullMQModuleShape['Queue']> | null = null
+  try {
+    queue = new bullmq.Queue(queueName, { connection })
+    const counts = await queue.getJobCounts('waiting', 'delayed', 'active')
+    const waiting = counts.waiting ?? 0
+    const delayed = counts.delayed ?? 0
+    const active = counts.active ?? 0
+    return {
+      queueName,
+      strategy: 'async',
+      ready: waiting,
+      delayedFuture: delayed,
+      active,
+      error: false,
+    }
+  } catch (err) {
+    return errorResult(queueName, 'async', err)
+  } finally {
+    if (queue) {
+      try {
+        await queue.close()
+      } catch {
+        /* swallow shutdown errors — probe must not throw on cleanup */
+      }
+    }
+  }
+}
+
+/**
+ * Read-only pending-job probe for a queue.
+ *
+ * `strategy` defaults to the value of `QUEUE_STRATEGY` (via
+ * `resolveQueueStrategy`). The probe never installs handlers and never
+ * starts a BullMQ Worker, so it is safe to call from a lightweight
+ * supervisor process that watches many queues.
+ */
+export async function getQueuePendingProbe(
+  queueName: string,
+  strategy?: QueueStrategyType,
+  options?: QueuePendingProbeOptions,
+): Promise<QueuePendingProbeResult> {
+  const resolvedStrategy: QueueStrategyType = strategy
+    ?? (process.env.QUEUE_STRATEGY === 'async' ? 'async' : 'local')
+
+  if (resolvedStrategy === 'async') {
+    return probeAsyncQueue(queueName, options)
+  }
+  return probeLocalQueue(queueName, options)
+}
+
+/** Reset the cached bullmq module reference. Test-only. */
+export function __resetPendingProbeBullMQCache(): void {
+  cachedBullMQ = undefined
+}