@open-mercato/cli 0.6.1-develop.3167.1.7aedd7b2ba → 0.6.1-develop.3174.1.c3822bcdf0

package/jest.config.cjs

@@ -16,6 +16,9 @@ module.exports = {
   },
   moduleNameMapper: {
     '^@open-mercato/shared/(.*)$': '<rootDir>/../shared/src/$1',
+    '^@open-mercato/queue$': '<rootDir>/../queue/src/index.ts',
+    '^@open-mercato/queue/worker$': '<rootDir>/../queue/src/worker/runner.ts',
+    '^@open-mercato/queue/(.*)$': '<rootDir>/../queue/src/$1',
   },
   transformIgnorePatterns: [
     'node_modules/(?!(@mikro-orm)/)',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-mercato/cli",
-  "version": "0.6.1-develop.3167.1.7aedd7b2ba",
+  "version": "0.6.1-develop.3174.1.c3822bcdf0",
   "type": "module",
   "main": "./dist/index.js",
   "exports": {
@@ -59,8 +59,8 @@
     "@mikro-orm/decorators": "^7.0.14",
     "@mikro-orm/migrations": "^7.0.14",
     "@mikro-orm/postgresql": "^7.0.14",
-    "@open-mercato/queue": "0.6.1-develop.3167.1.7aedd7b2ba",
-    "@open-mercato/shared": "0.6.1-develop.3167.1.7aedd7b2ba",
+    "@open-mercato/queue": "0.6.1-develop.3174.1.c3822bcdf0",
+    "@open-mercato/shared": "0.6.1-develop.3174.1.c3822bcdf0",
     "cross-spawn": "^7.0.6",
     "pg": "8.20.0",
     "semver": "^7.7.4",
@@ -70,10 +70,10 @@
     "typescript": "^5.9.3"
   },
   "peerDependencies": {
-    "@open-mercato/shared": "0.6.1-develop.3167.1.7aedd7b2ba"
+    "@open-mercato/shared": "0.6.1-develop.3174.1.c3822bcdf0"
   },
   "devDependencies": {
-    "@open-mercato/shared": "0.6.1-develop.3167.1.7aedd7b2ba",
+    "@open-mercato/shared": "0.6.1-develop.3174.1.c3822bcdf0",
     "@types/jest": "^30.0.0",
     "jest": "^30.3.0",
     "ts-jest": "^29.4.9"

package/src/__tests__/mercato.test.ts

@@ -619,12 +619,14 @@ describe('generate post-step structural cache purge', () => {
 describe('server dev managed process exits', () => {
   const originalAutoSpawnScheduler = process.env.AUTO_SPAWN_SCHEDULER
   const originalAutoSpawnWorkers = process.env.AUTO_SPAWN_WORKERS
+  const originalLazy = process.env.OM_AUTO_SPAWN_WORKERS_LAZY
 
   beforeEach(() => {
     jest.restoreAllMocks()
     jest.resetModules()
     process.env.AUTO_SPAWN_SCHEDULER = 'false'
     process.env.AUTO_SPAWN_WORKERS = 'true'
+    delete process.env.OM_AUTO_SPAWN_WORKERS_LAZY
   })
 
   afterEach(() => {
@@ -633,12 +635,16 @@ describe('server dev managed process exits', () => {
     jest.dontMock('../lib/dev-env-reload')
     jest.dontMock('../lib/generators')
     jest.dontMock('../lib/resolver')
+    jest.dontMock('../lib/queue-worker-supervisor')
     jest.resetModules()
+    delete process.env.OM_AUTO_SPAWN_WORKERS_LAZY
   })
 
   afterAll(() => {
     process.env.AUTO_SPAWN_SCHEDULER = originalAutoSpawnScheduler
     process.env.AUTO_SPAWN_WORKERS = originalAutoSpawnWorkers
+    if (originalLazy === undefined) delete process.env.OM_AUTO_SPAWN_WORKERS_LAZY
+    else process.env.OM_AUTO_SPAWN_WORKERS_LAZY = originalLazy
   })
 
   it('skips scheduler auto-start when the module is not enabled', async () => {
@@ -730,17 +736,84 @@ describe('server dev managed process exits', () => {
     consoleErrorSpy.mockRestore()
     consoleLogSpy.mockRestore()
   })
+
+  it('starts the lazy worker supervisor instead of `queue worker --all` when OM_AUTO_SPAWN_WORKERS_LAZY=true', async () => {
+    const consoleErrorSpy = jest.spyOn(console, 'error').mockImplementation()
+    const consoleLogSpy = jest.spyOn(console, 'log').mockImplementation()
+    process.env.OM_AUTO_SPAWN_WORKERS_LAZY = 'true'
+
+    jest.doMock('node:fs', () => {
+      const actual = jest.requireActual('node:fs')
+      return {
+        ...actual,
+        existsSync: jest.fn((candidate: string) =>
+          candidate.includes('next/dist/bin/next') || candidate.includes('@open-mercato/cli/bin/mercato'),
+        ),
+        unlinkSync: jest.fn(),
+      }
+    })
+    jest.doMock('../lib/generators', () => ({
+      generateModulePackageSources: jest.fn().mockResolvedValue(undefined),
+    }))
+    jest.doMock('../lib/resolver', () => ({
+      resolveEnvironment: () => ({
+        appDir: '/tmp/test-app',
+        rootDir: '/tmp/test-root',
+      }),
+      createResolver: () => ({}),
+    }))
+
+    const supervisorClose = jest.fn().mockResolvedValue(undefined)
+    const startLazyWorkerSupervisor = jest.fn(() => ({
+      startedQueues: new Set<string>(),
+      getActiveChild: () => undefined,
+      close: supervisorClose,
+      done: Promise.resolve(),
+    }))
+    jest.doMock('../lib/queue-worker-supervisor', () => ({
+      startLazyWorkerSupervisor,
+    }))
+
+    jest.doMock('child_process', () =>
+      buildMockChildProcessModule((args) =>
+        args[0]?.includes('next/dist/bin/next') ? { code: null, signal: 'SIGTERM' } : undefined,
+      ),
+    )
+
+    const mercato = await import('../mercato')
+    mercato.registerCliModules([eventsWorkerFixture as Module])
+
+    const exitCode = await mercato.run(['node', 'mercato', 'server', 'dev'])
+
+    expect(exitCode).toBe(0)
+    expect(startLazyWorkerSupervisor).toHaveBeenCalledTimes(1)
+    const supervisorCall = startLazyWorkerSupervisor.mock.calls[0][0]
+    expect(supervisorCall.workers.map((worker) => worker.queue)).toEqual(['events'])
+    expect(supervisorCall.pollMs).toBe(1000)
+    expect(supervisorCall.restartOnUnexpectedExit).toBe(true)
+    expect(supervisorClose).toHaveBeenCalled()
+
+    const { spawn } = await import('child_process')
+    const allSpawnCalls = (spawn as jest.Mock).mock.calls.map((call) => call[1] as string[])
+    const queueWorkerSpawn = allSpawnCalls.find((args) => args.slice(1).join(' ') === 'queue worker --all')
+    expect(queueWorkerSpawn).toBeUndefined()
+
+    consoleErrorSpy.mockRestore()
+    consoleLogSpy.mockRestore()
+  })
 })
 
 describe('server start managed process exits', () => {
   const originalAutoSpawnScheduler = process.env.AUTO_SPAWN_SCHEDULER
   const originalAutoSpawnWorkers = process.env.AUTO_SPAWN_WORKERS
+  const originalLazy = process.env.OM_AUTO_SPAWN_WORKERS_LAZY
 
   beforeEach(() => {
     jest.restoreAllMocks()
     jest.resetModules()
     process.env.AUTO_SPAWN_SCHEDULER = 'false'
     process.env.AUTO_SPAWN_WORKERS = 'true'
+    delete process.env.OM_AUTO_SPAWN_WORKERS_LAZY
   })
 
   afterEach(() => {
@@ -748,12 +821,16 @@ describe('server start managed process exits', () => {
     jest.dontMock('node:fs')
     jest.dontMock('../lib/resolver')
     jest.dontMock('../lib/server-start-lock')
+    jest.dontMock('../lib/queue-worker-supervisor')
     jest.resetModules()
+    delete process.env.OM_AUTO_SPAWN_WORKERS_LAZY
   })
 
   afterAll(() => {
     process.env.AUTO_SPAWN_SCHEDULER = originalAutoSpawnScheduler
     process.env.AUTO_SPAWN_WORKERS = originalAutoSpawnWorkers
+    if (originalLazy === undefined) delete process.env.OM_AUTO_SPAWN_WORKERS_LAZY
+    else process.env.OM_AUTO_SPAWN_WORKERS_LAZY = originalLazy
   })
 
   it('skips scheduler auto-start when the module is not enabled', async () => {
@@ -956,4 +1033,63 @@ describe('server start managed process exits', () => {
     consoleErrorSpy.mockRestore()
     consoleLogSpy.mockRestore()
   })
+
+  it('starts the lazy worker supervisor in production server when OM_AUTO_SPAWN_WORKERS_LAZY=true', async () => {
+    const consoleErrorSpy = jest.spyOn(console, 'error').mockImplementation()
+    const consoleLogSpy = jest.spyOn(console, 'log').mockImplementation()
+    process.env.OM_AUTO_SPAWN_WORKERS_LAZY = 'true'
+
+    jest.doMock('node:fs', () => {
+      const actual = jest.requireActual('node:fs')
+      return {
+        ...actual,
+        existsSync: jest.fn((candidate: string) =>
+          candidate.includes('next/dist/bin/next') || candidate.includes('@open-mercato/cli/bin/mercato'),
+        ),
+      }
+    })
+    jest.doMock('../lib/resolver', () => ({
+      resolveEnvironment: () => ({
+        appDir: '/tmp/test-app',
+        rootDir: '/tmp/test-root',
+      }),
+    }))
+    jest.doMock('../lib/server-start-lock', () => ({
+      acquireServerStartLock: jest.fn(() => ({ release: jest.fn() })),
+    }))
+
+    const supervisorClose = jest.fn().mockResolvedValue(undefined)
+    const startLazyWorkerSupervisor = jest.fn(() => ({
+      startedQueues: new Set<string>(),
+      getActiveChild: () => undefined,
+      close: supervisorClose,
+      done: Promise.resolve(),
+    }))
+    jest.doMock('../lib/queue-worker-supervisor', () => ({
+      startLazyWorkerSupervisor,
+    }))
+
+    jest.doMock('child_process', () =>
+      buildMockChildProcessModule((args) =>
+        args[0]?.includes('next/dist/bin/next') ? { code: null, signal: 'SIGTERM' } : undefined,
+      ),
+    )
+
+    const mercato = await import('../mercato')
+    mercato.registerCliModules([eventsWorkerFixture as Module])
+
+    const exitCode = await mercato.run(['node', 'mercato', 'server', 'start'])
+
+    expect(exitCode).toBe(0)
+    expect(startLazyWorkerSupervisor).toHaveBeenCalledTimes(1)
+    expect(supervisorClose).toHaveBeenCalled()
+
+    const { spawn } = await import('child_process')
+    const allSpawnCalls = (spawn as jest.Mock).mock.calls.map((call) => call[1] as string[])
+    const queueWorkerSpawn = allSpawnCalls.find((args) => args.slice(1).join(' ') === 'queue worker --all')
+    expect(queueWorkerSpawn).toBeUndefined()
+
+    consoleErrorSpy.mockRestore()
+    consoleLogSpy.mockRestore()
+  })
 })

package/src/lib/__tests__/auto-spawn-workers.test.ts

@@ -0,0 +1,101 @@
+import {
+  resolveAutoSpawnWorkersMode,
+  resolveLazyPollMs,
+  resolveLazyRestart,
+} from '../auto-spawn-workers'
+
+describe('resolveAutoSpawnWorkersMode', () => {
+  it('defaults to eager when no env is set', () => {
+    expect(resolveAutoSpawnWorkersMode({})).toBe('eager')
+  })
+
+  it('returns off when AUTO_SPAWN_WORKERS=false', () => {
+    expect(resolveAutoSpawnWorkersMode({ AUTO_SPAWN_WORKERS: 'false' })).toBe('off')
+  })
+
+  it('returns off when OM_AUTO_SPAWN_WORKERS=false and legacy unset', () => {
+    expect(resolveAutoSpawnWorkersMode({ OM_AUTO_SPAWN_WORKERS: 'false' })).toBe('off')
+  })
+
+  it('legacy AUTO_SPAWN_WORKERS=true wins over OM_AUTO_SPAWN_WORKERS=false', () => {
+    expect(
+      resolveAutoSpawnWorkersMode({
+        AUTO_SPAWN_WORKERS: 'true',
+        OM_AUTO_SPAWN_WORKERS: 'false',
+      }),
+    ).toBe('eager')
+  })
+
+  it('returns lazy when workers are enabled and OM_AUTO_SPAWN_WORKERS_LAZY=true', () => {
+    expect(
+      resolveAutoSpawnWorkersMode({
+        AUTO_SPAWN_WORKERS: 'true',
+        OM_AUTO_SPAWN_WORKERS_LAZY: 'true',
+      }),
+    ).toBe('lazy')
+  })
+
+  it('lazy is ignored when AUTO_SPAWN_WORKERS=false', () => {
+    expect(
+      resolveAutoSpawnWorkersMode({
+        AUTO_SPAWN_WORKERS: 'false',
+        OM_AUTO_SPAWN_WORKERS_LAZY: 'true',
+      }),
+    ).toBe('off')
+  })
+
+  it('treats invalid AUTO_SPAWN_WORKERS values as default', () => {
+    expect(resolveAutoSpawnWorkersMode({ AUTO_SPAWN_WORKERS: 'maybe' })).toBe('eager')
+  })
+
+  it('falls through OM alias only when legacy is unset', () => {
+    expect(resolveAutoSpawnWorkersMode({ OM_AUTO_SPAWN_WORKERS: 'true' })).toBe('eager')
+    expect(
+      resolveAutoSpawnWorkersMode({
+        OM_AUTO_SPAWN_WORKERS: 'true',
+        OM_AUTO_SPAWN_WORKERS_LAZY: 'true',
+      }),
+    ).toBe('lazy')
+  })
+})
+
+describe('resolveLazyPollMs', () => {
+  it('returns the default when unset', () => {
+    expect(resolveLazyPollMs({})).toBe(1000)
+  })
+
+  it('parses numeric values', () => {
+    expect(resolveLazyPollMs({ OM_AUTO_SPAWN_WORKERS_LAZY_POLL_MS: '500' })).toBe(500)
+  })
+
+  it('clamps to the minimum', () => {
+    expect(resolveLazyPollMs({ OM_AUTO_SPAWN_WORKERS_LAZY_POLL_MS: '50' })).toBe(250)
+  })
+
+  it('falls back to default for non-numeric', () => {
+    expect(resolveLazyPollMs({ OM_AUTO_SPAWN_WORKERS_LAZY_POLL_MS: 'abc' })).toBe(1000)
+  })
+
+  it('falls back to default for non-positive', () => {
+    expect(resolveLazyPollMs({ OM_AUTO_SPAWN_WORKERS_LAZY_POLL_MS: '0' })).toBe(1000)
+    expect(resolveLazyPollMs({ OM_AUTO_SPAWN_WORKERS_LAZY_POLL_MS: '-100' })).toBe(1000)
+  })
+})
+
+describe('resolveLazyRestart', () => {
+  it('defaults to true when unset', () => {
+    expect(resolveLazyRestart({})).toBe(true)
+  })
+
+  it('returns false when explicitly disabled', () => {
+    expect(resolveLazyRestart({ OM_AUTO_SPAWN_WORKERS_LAZY_RESTART: 'false' })).toBe(false)
+  })
+
+  it('returns true when explicitly enabled', () => {
+    expect(resolveLazyRestart({ OM_AUTO_SPAWN_WORKERS_LAZY_RESTART: 'true' })).toBe(true)
+  })
+
+  it('falls back to default for invalid values', () => {
+    expect(resolveLazyRestart({ OM_AUTO_SPAWN_WORKERS_LAZY_RESTART: 'maybe' })).toBe(true)
+  })
+})

package/src/lib/__tests__/queue-worker-supervisor.test.ts

@@ -0,0 +1,285 @@
+import { EventEmitter } from 'node:events'
+import type { ChildProcess } from 'node:child_process'
+import type { ModuleWorker } from '@open-mercato/shared/modules/registry'
+import {
+  startLazyWorkerSupervisor,
+  type LazySupervisorProbeFn,
+  type LazySupervisorSpawnFn,
+} from '../queue-worker-supervisor'
+import type {
+  QueuePendingProbeResult,
+  QueueStrategyType,
+} from '@open-mercato/queue'
+
+type FakeChild = ChildProcess & {
+  triggerExit: (code: number | null, signal?: NodeJS.Signals | null) => void
+}
+
+function createFakeChild(): FakeChild {
+  const child = new EventEmitter() as unknown as FakeChild
+  ;(child as any).stdout = null
+  ;(child as any).stderr = null
+  ;(child as any).pid = Math.floor(Math.random() * 100000) + 1
+  ;(child as any).killed = false
+  ;(child as any).exitCode = null
+  ;(child as any).signalCode = null
+  ;(child as any).kill = jest.fn((signal: NodeJS.Signals = 'SIGTERM') => {
+    if ((child as any).killed) return true
+    ;(child as any).killed = true
+    ;(child as any).signalCode = signal
+    process.nextTick(() => child.emit('exit', null, signal))
+    return true
+  })
+  child.triggerExit = (code, signal = null) => {
+    ;(child as any).exitCode = code
+    ;(child as any).signalCode = signal
+    child.emit('exit', code, signal)
+  }
+  return child
+}
+
+const silentLogger = { log: jest.fn(), warn: jest.fn(), error: jest.fn() }
+
+function makeWorker(queue: string, id?: string, concurrency = 1): ModuleWorker {
+  return {
+    id: id ?? `${queue}-worker`,
+    queue,
+    concurrency,
+    handler: jest.fn() as unknown as ModuleWorker['handler'],
+  }
+}
+
+function emptyProbe(queueName: string, strategy: QueueStrategyType): QueuePendingProbeResult {
+  return { queueName, strategy, ready: 0, delayedFuture: 0, active: 0, error: false }
+}
+
+function readyProbe(queueName: string, strategy: QueueStrategyType, ready = 1): QueuePendingProbeResult {
+  return { queueName, strategy, ready, delayedFuture: 0, active: 0, error: false }
+}
+
+async function flushAsync(times = 5): Promise<void> {
+  for (let i = 0; i < times; i++) {
+    // eslint-disable-next-line no-await-in-loop
+    await Promise.resolve()
+  }
+}
+
+describe('startLazyWorkerSupervisor', () => {
+  it('does not spawn any worker while every queue is idle', async () => {
+    const spawnFn = jest.fn() as unknown as jest.MockedFunction<LazySupervisorSpawnFn>
+    const probeFn = jest.fn(async (queueName, strategy) =>
+      emptyProbe(queueName, strategy),
+    ) as jest.MockedFunction<LazySupervisorProbeFn>
+
+    const handle = startLazyWorkerSupervisor({
+      mercatoBin: '/tmp/mercato',
+      appDir: '/tmp/app',
+      runtimeEnv: { ...process.env },
+      workers: [makeWorker('events'), makeWorker('emails')],
+      pollMs: 250,
+      restartOnUnexpectedExit: true,
+      strategy: 'local',
+      spawnFn,
+      probeFn,
+      logger: silentLogger,
+    })
+
+    await flushAsync(20)
+    expect(probeFn).toHaveBeenCalled()
+    expect(spawnFn).not.toHaveBeenCalled()
+    expect(handle.startedQueues.size).toBe(0)
+
+    await handle.close()
+  })
+
+  it('spawns only the queue with ready jobs and never duplicates the spawn', async () => {
+    const child = createFakeChild()
+    const spawnFn = jest.fn(() => child) as unknown as jest.MockedFunction<LazySupervisorSpawnFn>
+    const probeFn = jest.fn(async (queueName, strategy) => {
+      if (queueName === 'events') return readyProbe(queueName, strategy)
+      return emptyProbe(queueName, strategy)
+    }) as jest.MockedFunction<LazySupervisorProbeFn>
+
+    const handle = startLazyWorkerSupervisor({
+      mercatoBin: '/tmp/mercato',
+      appDir: '/tmp/app',
+      runtimeEnv: { ...process.env },
+      workers: [makeWorker('events'), makeWorker('emails')],
+      pollMs: 250,
+      restartOnUnexpectedExit: false,
+      strategy: 'local',
+      spawnFn,
+      probeFn,
+      logger: silentLogger,
+    })
+
+    await flushAsync(20)
+
+    expect(spawnFn).toHaveBeenCalledTimes(1)
+    const [command, args] = spawnFn.mock.calls[0]
+    expect(command).toBe('node')
+    expect(args).toEqual(['/tmp/mercato', 'queue', 'worker', 'events'])
+    expect(handle.startedQueues.has('events')).toBe(true)
+    expect(handle.startedQueues.has('emails')).toBe(false)
+
+    await flushAsync(20)
+    expect(spawnFn).toHaveBeenCalledTimes(1)
+
+    await handle.close()
+  })
+
+  it('does not spawn when probe reports an error', async () => {
+    const spawnFn = jest.fn() as unknown as jest.MockedFunction<LazySupervisorSpawnFn>
+    const probeFn = jest.fn(async (queueName, strategy) => ({
+      queueName,
+      strategy,
+      ready: 0,
+      delayedFuture: 0,
+      active: 0,
+      error: true,
+      errorMessage: 'redis-unreachable',
+    })) as jest.MockedFunction<LazySupervisorProbeFn>
+
+    const handle = startLazyWorkerSupervisor({
+      mercatoBin: '/tmp/mercato',
+      appDir: '/tmp/app',
+      runtimeEnv: { ...process.env },
+      workers: [makeWorker('events')],
+      pollMs: 250,
+      restartOnUnexpectedExit: false,
+      strategy: 'async',
+      spawnFn,
+      probeFn,
+      logger: silentLogger,
+    })
+
+    await flushAsync(20)
+    expect(spawnFn).not.toHaveBeenCalled()
+
+    await handle.close()
+  })
+
+  it('terminates active children on close()', async () => {
+    const child = createFakeChild()
+    const spawnFn = jest.fn(() => child) as unknown as jest.MockedFunction<LazySupervisorSpawnFn>
+    const probeFn = jest.fn(async (queueName, strategy) =>
+      readyProbe(queueName, strategy),
+    ) as jest.MockedFunction<LazySupervisorProbeFn>
+
+    const handle = startLazyWorkerSupervisor({
+      mercatoBin: '/tmp/mercato',
+      appDir: '/tmp/app',
+      runtimeEnv: { ...process.env },
+      workers: [makeWorker('events')],
+      pollMs: 250,
+      restartOnUnexpectedExit: false,
+      strategy: 'local',
+      spawnFn,
+      probeFn,
+      logger: silentLogger,
+    })
+
+    await flushAsync(20)
+    expect(spawnFn).toHaveBeenCalledTimes(1)
+
+    await handle.close()
+    expect((child as any).kill).toHaveBeenCalledWith('SIGTERM')
+  })
+
+  it('restarts an unexpectedly exited worker only when jobs remain pending', async () => {
+    const firstChild = createFakeChild()
+    const secondChild = createFakeChild()
+    const spawnFn = jest
+      .fn()
+      .mockImplementationOnce(() => firstChild)
+      .mockImplementationOnce(() => secondChild) as unknown as jest.MockedFunction<LazySupervisorSpawnFn>
+
+    let pendingReady = 1
+    const probeFn = jest.fn(async (queueName, strategy) => {
+      if (queueName !== 'events') return emptyProbe(queueName, strategy)
+      return readyProbe(queueName, strategy, pendingReady)
+    }) as jest.MockedFunction<LazySupervisorProbeFn>
+
+    const handle = startLazyWorkerSupervisor({
+      mercatoBin: '/tmp/mercato',
+      appDir: '/tmp/app',
+      runtimeEnv: { ...process.env },
+      workers: [makeWorker('events')],
+      pollMs: 250,
+      restartOnUnexpectedExit: true,
+      strategy: 'local',
+      spawnFn,
+      probeFn,
+      logger: silentLogger,
+    })
+
+    await flushAsync(20)
+    expect(spawnFn).toHaveBeenCalledTimes(1)
+
+    // Worker dies unexpectedly with jobs still pending — supervisor must restart.
+    firstChild.triggerExit(1, null)
+    await flushAsync(40)
+    expect(spawnFn).toHaveBeenCalledTimes(2)
+
+    // Worker dies again, but this time no jobs remain — supervisor must NOT restart.
+    pendingReady = 0
+    secondChild.triggerExit(1, null)
+    await flushAsync(40)
+    expect(spawnFn).toHaveBeenCalledTimes(2)
+
+    await handle.close()
+  })
+
+  it('does not restart on an expected SIGTERM exit', async () => {
+    const child = createFakeChild()
+    const spawnFn = jest.fn(() => child) as unknown as jest.MockedFunction<LazySupervisorSpawnFn>
+    const probeFn = jest.fn(async (queueName, strategy) =>
+      readyProbe(queueName, strategy),
+    ) as jest.MockedFunction<LazySupervisorProbeFn>
+
+    const handle = startLazyWorkerSupervisor({
+      mercatoBin: '/tmp/mercato',
+      appDir: '/tmp/app',
+      runtimeEnv: { ...process.env },
+      workers: [makeWorker('events')],
+      pollMs: 250,
+      restartOnUnexpectedExit: true,
+      strategy: 'local',
+      spawnFn,
+      probeFn,
+      logger: silentLogger,
+    })
+
+    await flushAsync(20)
+    expect(spawnFn).toHaveBeenCalledTimes(1)
+
+    child.triggerExit(null, 'SIGTERM')
+    await flushAsync(40)
+
+    expect(spawnFn).toHaveBeenCalledTimes(1)
+
+    await handle.close()
+  })
+
+  it('handles an empty worker list without crashing', async () => {
+    const spawnFn = jest.fn() as unknown as jest.MockedFunction<LazySupervisorSpawnFn>
+    const probeFn = jest.fn() as unknown as jest.MockedFunction<LazySupervisorProbeFn>
+    const handle = startLazyWorkerSupervisor({
+      mercatoBin: '/tmp/mercato',
+      appDir: '/tmp/app',
+      runtimeEnv: { ...process.env },
+      workers: [],
+      pollMs: 250,
+      restartOnUnexpectedExit: true,
+      strategy: 'local',
+      spawnFn,
+      probeFn,
+      logger: silentLogger,
+    })
+
+    await flushAsync(20)
+    expect(probeFn).not.toHaveBeenCalled()
+    expect(spawnFn).not.toHaveBeenCalled()
+    await handle.close()
+  })
+})

package/src/lib/auto-spawn-workers.ts

@@ -0,0 +1,39 @@
+import { parseBooleanToken } from '@open-mercato/shared/lib/boolean'
+
+export type AutoSpawnWorkersMode = 'off' | 'eager' | 'lazy'
+
+export type AutoSpawnEnvSource = Pick<NodeJS.ProcessEnv, string> | Record<string, string | undefined>
+
+const DEFAULT_LAZY_POLL_MS = 1000
+const MIN_LAZY_POLL_MS = 250
+
+export function resolveAutoSpawnWorkersEnabled(env: AutoSpawnEnvSource = process.env): boolean {
+  const legacy = parseBooleanToken(env.AUTO_SPAWN_WORKERS)
+  if (legacy !== null) return legacy
+  const aliased = parseBooleanToken(env.OM_AUTO_SPAWN_WORKERS)
+  if (aliased !== null) return aliased
+  return true
+}
+
+export function resolveAutoSpawnWorkersLazy(env: AutoSpawnEnvSource = process.env): boolean {
+  return parseBooleanToken(env.OM_AUTO_SPAWN_WORKERS_LAZY) === true
+}
+
+export function resolveAutoSpawnWorkersMode(env: AutoSpawnEnvSource = process.env): AutoSpawnWorkersMode {
+  if (!resolveAutoSpawnWorkersEnabled(env)) return 'off'
+  if (resolveAutoSpawnWorkersLazy(env)) return 'lazy'
+  return 'eager'
+}
+
+export function resolveLazyPollMs(env: AutoSpawnEnvSource = process.env): number {
+  const raw = env.OM_AUTO_SPAWN_WORKERS_LAZY_POLL_MS
+  if (typeof raw !== 'string' || raw.trim() === '') return DEFAULT_LAZY_POLL_MS
+  const parsed = Number(raw)
+  if (!Number.isFinite(parsed) || parsed <= 0) return DEFAULT_LAZY_POLL_MS
+  return Math.max(MIN_LAZY_POLL_MS, Math.floor(parsed))
+}
+
+export function resolveLazyRestart(env: AutoSpawnEnvSource = process.env): boolean {
+  const parsed = parseBooleanToken(env.OM_AUTO_SPAWN_WORKERS_LAZY_RESTART)
+  return parsed === null ? true : parsed
+}