@open-mercato/cli 0.6.6-develop.5509.1.006f4d4f24 → 0.6.6-develop.5531.1.ab1959dfae

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-mercato/cli",
-  "version": "0.6.6-develop.5509.1.006f4d4f24",
+  "version": "0.6.6-develop.5531.1.ab1959dfae",
   "type": "module",
   "main": "./dist/index.js",
   "exports": {
@@ -59,8 +59,8 @@
     "@mikro-orm/decorators": "^7.1.4",
     "@mikro-orm/migrations": "^7.1.4",
     "@mikro-orm/postgresql": "^7.1.4",
-    "@open-mercato/queue": "0.6.6-develop.5509.1.006f4d4f24",
-    "@open-mercato/shared": "0.6.6-develop.5509.1.006f4d4f24",
+    "@open-mercato/queue": "0.6.6-develop.5531.1.ab1959dfae",
+    "@open-mercato/shared": "0.6.6-develop.5531.1.ab1959dfae",
     "cross-spawn": "^7.0.6",
     "pg": "8.21.0",
     "semver": "^7.8.3",
@@ -70,10 +70,10 @@
     "typescript": "^6.0.3"
   },
   "peerDependencies": {
-    "@open-mercato/shared": "0.6.6-develop.5509.1.006f4d4f24"
+    "@open-mercato/shared": "0.6.6-develop.5531.1.ab1959dfae"
   },
   "devDependencies": {
-    "@open-mercato/shared": "0.6.6-develop.5509.1.006f4d4f24",
+    "@open-mercato/shared": "0.6.6-develop.5531.1.ab1959dfae",
     "@types/jest": "^30.0.0",
     "jest": "^30.4.2",
     "ts-jest": "^29.4.11"

package/src/lib/__tests__/single-instance-strategy-guard.test.ts

@@ -0,0 +1,138 @@
+import {
+  assertSingleInstanceStrategies,
+  evaluateSingleInstanceGuard,
+  SingleInstanceStrategyError,
+  type InfraStrategySnapshot,
+} from '../single-instance-strategy-guard'
+
+const singleInstanceSnapshot: InfraStrategySnapshot = {
+  cacheStrategy: 'memory',
+  queueStrategy: 'local',
+  rateLimitStrategy: 'memory',
+}
+
+const multiInstanceSafeSnapshot: InfraStrategySnapshot = {
+  cacheStrategy: 'redis',
+  queueStrategy: 'async',
+  rateLimitStrategy: 'redis',
+}
+
+describe('evaluateSingleInstanceGuard', () => {
+  it('is a no-op outside production even with single-instance strategies', () => {
+    const result = evaluateSingleInstanceGuard(singleInstanceSnapshot, {
+      NODE_ENV: 'development',
+      OM_MULTI_INSTANCE: '1',
+    })
+    expect(result.action).toBe('ok')
+    expect(result.offenders).toHaveLength(3)
+  })
+
+  it('is a no-op in production when all strategies are multi-instance safe', () => {
+    const result = evaluateSingleInstanceGuard(multiInstanceSafeSnapshot, {
+      NODE_ENV: 'production',
+      OM_MULTI_INSTANCE: '1',
+    })
+    expect(result.action).toBe('ok')
+    expect(result.offenders).toHaveLength(0)
+  })
+
+  it('fails in production when a multi-instance topology is declared via OM_MULTI_INSTANCE', () => {
+    const result = evaluateSingleInstanceGuard(singleInstanceSnapshot, {
+      NODE_ENV: 'production',
+      OM_MULTI_INSTANCE: '1',
+    })
+    expect(result.action).toBe('fail')
+    expect(result.offenders.map((offender) => offender.envVar)).toEqual([
+      'CACHE_STRATEGY',
+      'QUEUE_STRATEGY',
+      'RATE_LIMIT_STRATEGY',
+    ])
+  })
+
+  it('treats OM_INSTANCE_COUNT > 1 as a multi-instance topology', () => {
+    const result = evaluateSingleInstanceGuard(singleInstanceSnapshot, {
+      NODE_ENV: 'production',
+      OM_INSTANCE_COUNT: '3',
+    })
+    expect(result.action).toBe('fail')
+  })
+
+  it('does not treat OM_INSTANCE_COUNT=1 as multi-instance', () => {
+    const result = evaluateSingleInstanceGuard(singleInstanceSnapshot, {
+      NODE_ENV: 'production',
+      OM_INSTANCE_COUNT: '1',
+    })
+    expect(result.action).toBe('warn')
+  })
+
+  it('only warns in production when no multi-instance topology is declared', () => {
+    const result = evaluateSingleInstanceGuard(singleInstanceSnapshot, {
+      NODE_ENV: 'production',
+    })
+    expect(result.action).toBe('warn')
+    expect(result.multiInstance).toBe(false)
+  })
+
+  it('downgrades a hard failure to a warning when the override is set', () => {
+    const result = evaluateSingleInstanceGuard(singleInstanceSnapshot, {
+      NODE_ENV: 'production',
+      OM_MULTI_INSTANCE: '1',
+      OM_ALLOW_SINGLE_INSTANCE_STRATEGIES: '1',
+    })
+    expect(result.action).toBe('warn')
+    expect(result.overridden).toBe(true)
+  })
+
+  it('flags only the offending strategy when others are safe', () => {
+    const result = evaluateSingleInstanceGuard(
+      { cacheStrategy: 'redis', queueStrategy: 'local', rateLimitStrategy: 'redis' },
+      { NODE_ENV: 'production', OM_MULTI_INSTANCE: '1' },
+    )
+    expect(result.action).toBe('fail')
+    expect(result.offenders).toHaveLength(1)
+    expect(result.offenders[0].component).toBe('queue')
+  })
+})
+
+describe('assertSingleInstanceStrategies', () => {
+  function createLogger() {
+    return {
+      warn: jest.fn(),
+      error: jest.fn(),
+    }
+  }
+
+  it('throws and logs when the guard fails', () => {
+    const logger = createLogger()
+    expect(() =>
+      assertSingleInstanceStrategies(
+        { NODE_ENV: 'production', OM_MULTI_INSTANCE: '1' },
+        { snapshot: singleInstanceSnapshot, logger },
+      ),
+    ).toThrow(SingleInstanceStrategyError)
+    expect(logger.error).toHaveBeenCalled()
+    expect(logger.warn).not.toHaveBeenCalled()
+  })
+
+  it('logs a warning but does not throw when only warning', () => {
+    const logger = createLogger()
+    const result = assertSingleInstanceStrategies(
+      { NODE_ENV: 'production' },
+      { snapshot: singleInstanceSnapshot, logger },
+    )
+    expect(result.action).toBe('warn')
+    expect(logger.warn).toHaveBeenCalled()
+    expect(logger.error).not.toHaveBeenCalled()
+  })
+
+  it('stays silent and does not throw when everything is safe', () => {
+    const logger = createLogger()
+    const result = assertSingleInstanceStrategies(
+      { NODE_ENV: 'production', OM_MULTI_INSTANCE: '1' },
+      { snapshot: multiInstanceSafeSnapshot, logger },
+    )
+    expect(result.action).toBe('ok')
+    expect(logger.warn).not.toHaveBeenCalled()
+    expect(logger.error).not.toHaveBeenCalled()
+  })
+})

package/src/lib/__tests__/worker-job-handler.test.ts

@@ -0,0 +1,135 @@
+import type { ModuleWorker } from '@open-mercato/shared/modules/registry'
+import { createPerJobWorkerHandler, type WorkerJobContainer } from '../worker-job-handler'
+
+type FakeContainer = WorkerJobContainer & {
+  id: number
+  em: { clear: jest.Mock }
+}
+
+function makeContainerFactory() {
+  const containers: FakeContainer[] = []
+  let nextId = 0
+  const factory = jest.fn(async (): Promise<WorkerJobContainer> => {
+    const em = { clear: jest.fn() }
+    const container: FakeContainer = {
+      id: nextId++,
+      em,
+      resolve: <T = unknown>(name: string): T => {
+        if (name === 'em') return em as unknown as T
+        return undefined as unknown as T
+      },
+    }
+    containers.push(container)
+    return container
+  })
+  return { factory, containers }
+}
+
+function makeWorker(id: string, handler: ModuleWorker['handler']): ModuleWorker {
+  return { id, queue: 'test', concurrency: 1, handler }
+}
+
+const baseCtx = { jobId: 'job-1', attemptNumber: 1, queueName: 'test' }
+
+describe('createPerJobWorkerHandler', () => {
+  it('creates a fresh container for every job invocation', async () => {
+    const { factory } = makeContainerFactory()
+    const worker = makeWorker('w', jest.fn())
+    const handler = createPerJobWorkerHandler([worker], factory)
+
+    await handler({ id: 'a' }, { ...baseCtx, jobId: 'a' })
+    await handler({ id: 'b' }, { ...baseCtx, jobId: 'b' })
+
+    expect(factory).toHaveBeenCalledTimes(2)
+  })
+
+  it('passes each worker a resolve bound to that job container', async () => {
+    const { factory, containers } = makeContainerFactory()
+    const seenEms: unknown[] = []
+    const worker = makeWorker('w', (_job, ctx) => {
+      const resolve = (ctx as { resolve: (name: string) => unknown }).resolve
+      seenEms.push(resolve('em'))
+    })
+    const handler = createPerJobWorkerHandler([worker], factory)
+
+    await handler({ id: 'a' }, { ...baseCtx, jobId: 'a' })
+    await handler({ id: 'b' }, { ...baseCtx, jobId: 'b' })
+
+    expect(seenEms).toHaveLength(2)
+    expect(seenEms[0]).toBe(containers[0].em)
+    expect(seenEms[1]).toBe(containers[1].em)
+    expect(seenEms[0]).not.toBe(seenEms[1])
+  })
+
+  it('isolates concurrent jobs in distinct containers (no shared EntityManager)', async () => {
+    const { factory, containers } = makeContainerFactory()
+    let release: (() => void) | null = null
+    const gate = new Promise<void>((resolve) => {
+      release = resolve
+    })
+    const resolvedEms: unknown[] = []
+    let firstEntered = false
+    const worker = makeWorker('w', async (_job, ctx) => {
+      const resolve = (ctx as { resolve: (name: string) => unknown }).resolve
+      resolvedEms.push(resolve('em'))
+      if (!firstEntered) {
+        firstEntered = true
+        // Hold the first job open so the second job starts concurrently.
+        await gate
+      }
+    })
+    const handler = createPerJobWorkerHandler([worker], factory)
+
+    const first = handler({ id: 'a' }, { ...baseCtx, jobId: 'a' })
+    const second = handler({ id: 'b' }, { ...baseCtx, jobId: 'b' })
+    release?.()
+    await Promise.all([first, second])
+
+    expect(factory).toHaveBeenCalledTimes(2)
+    expect(resolvedEms[0]).toBe(containers[0].em)
+    expect(resolvedEms[1]).toBe(containers[1].em)
+    expect(resolvedEms[0]).not.toBe(resolvedEms[1])
+  })
+
+  it('runs every worker for the queue against the same per-job container', async () => {
+    const { factory, containers } = makeContainerFactory()
+    const seen: unknown[] = []
+    const record = (_job: unknown, ctx: unknown) => {
+      seen.push((ctx as { resolve: (name: string) => unknown }).resolve('em'))
+    }
+    const handler = createPerJobWorkerHandler(
+      [makeWorker('w1', record), makeWorker('w2', record)],
+      factory,
+    )
+
+    await handler({ id: 'a' }, baseCtx)
+
+    expect(factory).toHaveBeenCalledTimes(1)
+    expect(seen).toHaveLength(2)
+    expect(seen[0]).toBe(containers[0].em)
+    expect(seen[1]).toBe(containers[0].em)
+  })
+
+  it('clears the job container EntityManager after the job completes', async () => {
+    const { factory, containers } = makeContainerFactory()
+    const handler = createPerJobWorkerHandler([makeWorker('w', jest.fn())], factory)
+
+    await handler({ id: 'a' }, baseCtx)
+
+    expect(containers[0].em.clear).toHaveBeenCalledTimes(1)
+  })
+
+  it('clears the EntityManager and rethrows when a worker fails', async () => {
+    const { factory, containers } = makeContainerFactory()
+    const boom = new Error('worker failed')
+    const handler = createPerJobWorkerHandler(
+      [makeWorker('w', () => {
+        throw boom
+      })],
+      factory,
+    )
+
+    await expect(handler({ id: 'a' }, baseCtx)).rejects.toBe(boom)
+    expect(containers[0].em.clear).toHaveBeenCalledTimes(1)
+  })
+})

package/src/lib/single-instance-strategy-guard.ts

@@ -0,0 +1,172 @@
+import { parseBooleanWithDefault } from '@open-mercato/shared/lib/boolean'
+import { resolveQueueStrategy } from '@open-mercato/queue'
+
+/**
+ * Boot-time guard that refuses to start (or warns) when an infrastructure
+ * strategy that is only safe for a single process/instance is configured under
+ * a declared multi-instance topology.
+ *
+ * Background: `CACHE_STRATEGY`, `RATE_LIMIT_STRATEGY` and `QUEUE_STRATEGY` all
+ * default to single-instance modes (`memory`/`memory`/`local`). Running more
+ * than one app instance against those defaults silently breaks three
+ * correctness invariants at once — stale RBAC caches after a privilege
+ * revocation, rate limits multiplied by the instance count, and duplicate job
+ * processing from the leaderless local file queue. None of them warn.
+ *
+ * Only strategies that coordinate across processes via shared external state
+ * are considered multi-instance safe. Everything else (the in-process memory
+ * strategies, the local file queue, and disk-backed caches that are not shared
+ * across hosts) is treated as single-instance.
+ */
+const MULTI_INSTANCE_SAFE_STRATEGIES = {
+  cache: ['redis'],
+  queue: ['async'],
+  rateLimit: ['redis'],
+} as const
+
+export type SingleInstanceGuardComponent = 'cache' | 'queue' | 'rateLimit'
+
+export type SingleInstanceGuardOffender = {
+  component: SingleInstanceGuardComponent
+  envVar: string
+  configured: string
+  safeValues: readonly string[]
+}
+
+export type SingleInstanceGuardAction = 'ok' | 'warn' | 'fail'
+
+export type SingleInstanceGuardResult = {
+  action: SingleInstanceGuardAction
+  offenders: SingleInstanceGuardOffender[]
+  production: boolean
+  multiInstance: boolean
+  overridden: boolean
+}
+
+export type InfraStrategySnapshot = {
+  cacheStrategy: string
+  queueStrategy: string
+  rateLimitStrategy: string
+}
+
+const COMPONENT_ENV_VARS: Record<SingleInstanceGuardComponent, string> = {
+  cache: 'CACHE_STRATEGY',
+  queue: 'QUEUE_STRATEGY',
+  rateLimit: 'RATE_LIMIT_STRATEGY',
+}
+
+export class SingleInstanceStrategyError extends Error {
+  readonly offenders: SingleInstanceGuardOffender[]
+
+  constructor(result: SingleInstanceGuardResult) {
+    super(
+      `Refusing to start: single-instance infrastructure strategies (${result.offenders
+        .map((offender) => `${offender.envVar}=${offender.configured}`)
+        .join(', ')}) are configured under a declared multi-instance topology. ` +
+        'Switch to a multi-instance-safe strategy or set OM_ALLOW_SINGLE_INSTANCE_STRATEGIES=1 to override.',
+    )
+    this.name = 'SingleInstanceStrategyError'
+    this.offenders = result.offenders
+  }
+}
+
+/**
+ * Read the configured infrastructure strategies. Queue resolution reuses the
+ * canonical `resolveQueueStrategy()` so the default stays single-sourced; cache
+ * and rate-limit values are read directly with their documented defaults
+ * (`packages/cache/src/service.ts`, `packages/shared/src/lib/ratelimit/config.ts`)
+ * because the guard's safe-set policy — not the resolver default — decides what
+ * counts as single-instance.
+ */
+export function readInfraStrategySnapshot(env: NodeJS.ProcessEnv = process.env): InfraStrategySnapshot {
+  return {
+    cacheStrategy: env.CACHE_STRATEGY?.trim() || 'memory',
+    queueStrategy: resolveQueueStrategy(),
+    rateLimitStrategy: env.RATE_LIMIT_STRATEGY?.trim() || 'memory',
+  }
+}
+
+function resolveMultiInstanceHint(env: NodeJS.ProcessEnv): boolean {
+  if (parseBooleanWithDefault(env.OM_MULTI_INSTANCE, false)) return true
+  const instanceCount = Number.parseInt(env.OM_INSTANCE_COUNT ?? '', 10)
+  return Number.isFinite(instanceCount) && instanceCount > 1
+}
+
+export function evaluateSingleInstanceGuard(
+  snapshot: InfraStrategySnapshot,
+  env: NodeJS.ProcessEnv = process.env,
+): SingleInstanceGuardResult {
+  const configured: Record<SingleInstanceGuardComponent, string> = {
+    cache: snapshot.cacheStrategy,
+    queue: snapshot.queueStrategy,
+    rateLimit: snapshot.rateLimitStrategy,
+  }
+
+  const offenders: SingleInstanceGuardOffender[] = []
+  for (const component of Object.keys(configured) as SingleInstanceGuardComponent[]) {
+    const safeValues: readonly string[] = MULTI_INSTANCE_SAFE_STRATEGIES[component]
+    if (!safeValues.includes(configured[component])) {
+      offenders.push({
+        component,
+        envVar: COMPONENT_ENV_VARS[component],
+        configured: configured[component],
+        safeValues,
+      })
+    }
+  }
+
+  const production = (env.NODE_ENV ?? '').trim() === 'production'
+  const multiInstance = resolveMultiInstanceHint(env)
+  const overridden = parseBooleanWithDefault(env.OM_ALLOW_SINGLE_INSTANCE_STRATEGIES, false)
+
+  let action: SingleInstanceGuardAction = 'ok'
+  if (offenders.length > 0 && production) {
+    action = multiInstance && !overridden ? 'fail' : 'warn'
+  }
+
+  return { action, offenders, production, multiInstance, overridden }
+}
+
+export function formatSingleInstanceGuardMessage(result: SingleInstanceGuardResult): string[] {
+  const offenderLines = result.offenders.map(
+    (offender) =>
+      `  - ${offender.envVar}=${offender.configured} (multi-instance-safe: ${offender.safeValues.join(', ')})`,
+  )
+  const header =
+    result.action === 'fail'
+      ? '[server] Refusing to start: single-instance infrastructure strategies under a multi-instance topology.'
+      : '[server] WARNING: single-instance infrastructure strategies detected in production.'
+  const guidance =
+    result.action === 'fail'
+      ? '[server] Switch each strategy above to a multi-instance-safe value, or set OM_ALLOW_SINGLE_INSTANCE_STRATEGIES=1 to override (accepting duplicate jobs, stale ACLs, and weakened rate limits).'
+      : result.multiInstance
+        ? '[server] OM_ALLOW_SINGLE_INSTANCE_STRATEGIES=1 is set — proceeding despite the risks above (duplicate jobs, stale ACLs, weakened rate limits).'
+        : '[server] Running multiple instances against these strategies will cause duplicate jobs, stale ACLs, and weakened rate limits. Set OM_MULTI_INSTANCE=1 to make this a hard failure once you scale out.'
+  return [header, ...offenderLines, guidance]
+}
+
+export type SingleInstanceGuardLogger = Pick<Console, 'warn' | 'error'>
+
+/**
+ * Evaluate the guard and enforce it: throw on `fail`, log prominently on
+ * `warn`, and stay silent on `ok`. Safe to call on every `start`; it never
+ * fires for dev boots or single-instance production deployments.
+ */
+export function assertSingleInstanceStrategies(
+  env: NodeJS.ProcessEnv = process.env,
+  options?: { snapshot?: InfraStrategySnapshot; logger?: SingleInstanceGuardLogger },
+): SingleInstanceGuardResult {
+  const snapshot = options?.snapshot ?? readInfraStrategySnapshot(env)
+  const result = evaluateSingleInstanceGuard(snapshot, env)
+  const logger = options?.logger ?? console
+
+  if (result.action === 'fail') {
+    for (const line of formatSingleInstanceGuardMessage(result)) logger.error(line)
+    throw new SingleInstanceStrategyError(result)
+  }
+  if (result.action === 'warn') {
+    for (const line of formatSingleInstanceGuardMessage(result)) logger.warn(line)
+  }
+
+  return result
+}

package/src/lib/worker-job-handler.ts

@@ -0,0 +1,45 @@
+import type { JobContext, JobHandler } from '@open-mercato/queue'
+import type { ModuleWorker } from '@open-mercato/shared/modules/registry'
+
+export type WorkerJobContainer = {
+  resolve: <T = unknown>(name: string) => T
+}
+
+export type WorkerJobContainerFactory = () => Promise<WorkerJobContainer>
+
+type ClearableEntityManager = {
+  clear?: () => void
+}
+
+/**
+ * Builds a queue job handler that isolates every job in its own request
+ * container, instead of sharing a single process-wide `EntityManager` fork
+ * across all concurrent jobs.
+ *
+ * Under the async (BullMQ) strategy jobs run with real concurrency, so a
+ * shared EM would interleave unit-of-work flushes between unrelated jobs and
+ * never release its identity map. Creating one container per job removes both
+ * the cross-job flush race and the unbounded identity-map growth, while
+ * keeping the `ctx.resolve` contract and DI keys unchanged. See issue #2970.
+ */
+export function createPerJobWorkerHandler(
+  workers: ModuleWorker[],
+  createContainer: WorkerJobContainerFactory,
+): JobHandler {
+  return async (job, ctx: JobContext) => {
+    const container = await createContainer()
+    try {
+      for (const worker of workers) {
+        await worker.handler(job, { ...ctx, resolve: container.resolve.bind(container) })
+      }
+    } finally {
+      try {
+        const em = container.resolve('em') as ClearableEntityManager | null
+        em?.clear?.()
+      } catch {
+        // Best-effort: clearing the identity map is a memory optimization and
+        // must never mask a job's own outcome.
+      }
+    }
+  }
+}

package/src/mercato.ts

@@ -15,6 +15,7 @@ import {
   resolveLazyRestart,
 } from './lib/auto-spawn-workers'
 import { startLazyWorkerSupervisor } from './lib/queue-worker-supervisor'
+import { createPerJobWorkerHandler } from './lib/worker-job-handler'
 import {
   resolveAutoSpawnSchedulerMode,
   resolveLazySchedulerPollMs,
@@ -32,6 +33,7 @@ import {
 import { parseModuleInstallArgs } from './lib/module-install-args'
 import { resolveNextBuildIdCandidate } from './lib/next-build-id'
 import { acquireServerStartLock } from './lib/server-start-lock'
+import { assertSingleInstanceStrategies } from './lib/single-instance-strategy-guard'
 import { createDevEnvReloader, watchDevEnvFiles } from './lib/dev-env-reload'
 // Lazy-imported to avoid pulling in `testcontainers` (devDependency) at startup
 const lazyIntegration = () => import('./lib/testing/integration')
@@ -1518,7 +1520,6 @@ export async function run(argv = process.argv) {
             }
 
             const { createRequestContainer } = await import('@open-mercato/shared/lib/di/container')
-            const container = await createRequestContainer()
             console.log(`[worker] Starting workers for all queues: ${discoveredQueues.join(', ')}`)
 
             // Start all queue workers in background mode
@@ -1534,11 +1535,7 @@ export async function run(argv = process.argv) {
                 connection: queueRedisUrl ? { url: queueRedisUrl } : undefined,
                 concurrency,
                 background: true,
-                handler: async (job, ctx) => {
-                  for (const worker of queueWorkers) {
-                    await worker.handler(job, { ...ctx, resolve: container.resolve.bind(container) })
-                  }
-                },
+                handler: createPerJobWorkerHandler(queueWorkers, createRequestContainer),
               })
             })
 
@@ -1555,7 +1552,6 @@ export async function run(argv = process.argv) {
             if (queueWorkers.length > 0) {
               // Use discovered workers
               const { createRequestContainer } = await import('@open-mercato/shared/lib/di/container')
-              const container = await createRequestContainer()
               const concurrency = concurrencyOverride ?? Math.max(...queueWorkers.map((w) => w.concurrency), 1)
 
               console.log(`[worker] Found ${queueWorkers.length} worker(s) for queue "${queueName}"`)
@@ -1565,11 +1561,7 @@ export async function run(argv = process.argv) {
                 queueName: queueName!,
                 connection: queueRedisUrl ? { url: queueRedisUrl } : undefined,
                 concurrency,
-                handler: async (job, ctx) => {
-                  for (const worker of queueWorkers) {
-                    await worker.handler(job, { ...ctx, resolve: container.resolve.bind(container) })
-                  }
-                },
+                handler: createPerJobWorkerHandler(queueWorkers, createRequestContainer),
               })
             } else {
               console.error(`No workers found for queue "${queueName}"`)
@@ -2154,6 +2146,9 @@ export async function run(argv = process.argv) {
           const autoSpawnSchedulerMode = resolveAutoSpawnSchedulerMode(process.env)
           const queueStrategy = process.env.QUEUE_STRATEGY || 'local'
           const runtimeEnv = buildServerProcessEnvironment(process.env)
+          // Throws on single-instance strategies under a multi-instance topology,
+          // aborting before the start lock is acquired or any process is spawned.
+          assertSingleInstanceStrategies(runtimeEnv)
           const schedulerCommand = lookupModuleCommand(getCliModules(), 'scheduler', 'start')
           const serverStartLock = acquireServerStartLock(appDir, {
             port: runtimeEnv.PORT ?? process.env.PORT ?? null,