@open-mercato/cli 0.6.3 → 0.6.4-canary.3910.1.0ff5e9e9be

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-mercato/cli",
-  "version": "0.6.3",
+  "version": "0.6.4-canary.3910.1.0ff5e9e9be",
   "type": "module",
   "main": "./dist/index.js",
   "exports": {
@@ -59,21 +59,21 @@
     "@mikro-orm/decorators": "^7.1.1",
     "@mikro-orm/migrations": "^7.1.1",
     "@mikro-orm/postgresql": "^7.1.1",
-    "@open-mercato/queue": "0.6.3",
-    "@open-mercato/shared": "0.6.3",
+    "@open-mercato/queue": "0.6.4-canary.3910.1.0ff5e9e9be",
+    "@open-mercato/shared": "0.6.4-canary.3910.1.0ff5e9e9be",
     "cross-spawn": "^7.0.6",
     "pg": "8.21.0",
     "semver": "^7.8.1",
-    "testcontainers": "^12.0.1",
+    "testcontainers": "^12.0.0",
     "ts-morph": "^28.0.0",
     "tsx": "^4.22.3",
     "typescript": "^6.0.3"
   },
   "peerDependencies": {
-    "@open-mercato/shared": "0.6.3"
+    "@open-mercato/shared": "0.6.4-canary.3910.1.0ff5e9e9be"
   },
   "devDependencies": {
-    "@open-mercato/shared": "0.6.3",
+    "@open-mercato/shared": "0.6.4-canary.3910.1.0ff5e9e9be",
     "@types/jest": "^30.0.0",
     "jest": "^30.4.2",
     "ts-jest": "^29.4.11"
@@ -85,5 +85,6 @@
     "type": "git",
     "url": "https://github.com/open-mercato/open-mercato",
     "directory": "packages/cli"
-  }
+  },
+  "stableVersion": "0.6.3"
 }

package/src/__tests__/mercato.test.ts

@@ -37,18 +37,9 @@ function buildMockChildProcessModule(routeAutoExit: MockChildSpawnRouter) {
     if (autoExit) {
       queueMicrotask(() => {
         if (child.exitCode !== null || child.signalCode !== null) return
-        if (pathIncludes(spawnargs[1] ?? '', 'next/dist/bin/next') && spawnargs.includes('dev')) {
-          child.stdout.emit('data', '✓ Ready in 1ms\n')
-        }
-        queueMicrotask(() => {
-          child.exitCode = autoExit.code
-          child.signalCode = autoExit.signal ?? null
-          child.emit('exit', child.exitCode, child.signalCode)
-        })
-      })
-    } else if (pathIncludes(spawnargs[1] ?? '', 'next/dist/bin/next') && spawnargs.includes('dev')) {
-      queueMicrotask(() => {
-        child.stdout.emit('data', '✓ Ready in 1ms\n')
+        child.exitCode = autoExit.code
+        child.signalCode = autoExit.signal ?? null
+        child.emit('exit', child.exitCode, child.signalCode)
       })
     }
 
@@ -1058,7 +1049,6 @@ describe('server start managed process exits', () => {
         envChangeCallback = onChange
         return jest.fn()
       }),
-      watchDevRuntimeFiles: jest.fn(() => jest.fn()),
     }))
     jest.doMock('../lib/generators', () => ({
       generateModulePackageSources: jest.fn().mockResolvedValue(undefined),

package/src/lib/__tests__/dev-env-reload.test.ts

@@ -1,7 +1,7 @@
 import fs from 'node:fs'
 import os from 'node:os'
 import path from 'node:path'
-import { createDevEnvReloader, resolveDevEnvFilePaths, watchDevRuntimeFiles } from '../dev-env-reload'
+import { createDevEnvReloader, resolveDevEnvFilePaths } from '../dev-env-reload'
 import { normalizeTestPath } from './path-helpers'
 
 describe('dev env reload helpers', () => {
@@ -60,24 +60,4 @@ describe('dev env reload helpers', () => {
     expect(environment.SHELL_VALUE).toBe('shell-value')
     expect(environment.REMOVED_LATER).toBeUndefined()
   })
-
-  it('watches generated runtime files when explicitly requested', async () => {
-    const generatedDir = path.join(appDir, '.mercato', 'generated')
-    fs.mkdirSync(generatedDir, { recursive: true })
-    const generatedFile = path.join(generatedDir, 'backend-routes.generated.ts')
-    fs.writeFileSync(generatedFile, 'export const routes = []\n')
-
-    let stop = () => {}
-    const seen = new Promise<string>((resolve) => {
-      stop = watchDevRuntimeFiles(appDir, (filePath) => {
-        stop()
-        resolve(filePath)
-      }, { debounceMs: 10 })
-    })
-
-    await new Promise((resolve) => setTimeout(resolve, 25))
-    fs.writeFileSync(generatedFile, 'export const routes = [1]\n')
-
-    await expect(seen.finally(stop)).resolves.toBe(generatedFile)
-  })
 })

package/src/lib/dev-env-reload.ts

@@ -2,8 +2,6 @@ import dotenv from 'dotenv'
 import fs from 'node:fs'
 import path from 'node:path'
 
-const RUNTIME_GRAPH_FILE_PATTERN = /\.generated(?:\.[a-z0-9]+)?(?:\.tsx?|\.checksum)$/i
-
 const DEV_ENV_PRIORITY = [
   '.env',
   '.env.development',
@@ -110,48 +108,3 @@ export function watchDevEnvFiles(
     }
   }
 }
-
-export function watchDevRuntimeFiles(
-  appDir: string,
-  onChange: (filePath: string) => void,
-  options: { debounceMs?: number } = {},
-): () => void {
-  const debounceMs = options.debounceMs ?? 250
-  const generatedDir = path.join(appDir, '.mercato', 'generated')
-  const timers = new Map<string, NodeJS.Timeout>()
-
-  if (!fs.existsSync(generatedDir)) {
-    return () => {}
-  }
-
-  let watcher: fs.FSWatcher | null = null
-  try {
-    watcher = fs.watch(generatedDir, (eventType, fileName) => {
-      if (eventType !== 'change' && eventType !== 'rename') return
-      const name = String(fileName ?? '')
-      if (!name) return
-      if (!RUNTIME_GRAPH_FILE_PATTERN.test(name)) return
-
-      const filePath = path.join(generatedDir, name)
-      const existingTimer = timers.get(filePath)
-      if (existingTimer) {
-        clearTimeout(existingTimer)
-      }
-
-      timers.set(filePath, setTimeout(() => {
-        timers.delete(filePath)
-        onChange(filePath)
-      }, debounceMs))
-    })
-  } catch {
-    return () => {}
-  }
-
-  return () => {
-    for (const timer of timers.values()) {
-      clearTimeout(timer)
-    }
-    timers.clear()
-    watcher?.close()
-  }
-}

package/src/lib/testing/integration.ts

@@ -2949,13 +2949,6 @@ export async function startEphemeralEnvironment(options: EphemeralRuntimeOptions
       // on `DEMO_MODE !== 'false'` in the backend layout, so opting out here
       // only affects the integration test runtime — dev + prod stay unchanged.
       DEMO_MODE: 'false',
-      // Disable the feature-toggle resolution cache. Tests flip overrides
-      // (e.g. example_customers_sync enabled/bidirectional) between cases; the
-      // 1-minute resolution cache can serve a stale value across set/clear
-      // under fast churn, which made the example.todo.* persistent subscribers
-      // skip enqueueing inbound sync jobs (TC-CRM-028 inbound trio flake).
-      // Fresh DB reads make flag-gated sync deterministic in tests only.
-      OM_FEATURE_TOGGLES_CACHE_DISABLED: '1',
       OM_CLI_QUIET: '1',
       MERCATO_QUIET: '1',
       QUEUE_BASE_DIR: EPHEMERAL_QUEUE_BASE_DIR,

package/src/mercato.ts

@@ -341,122 +341,6 @@ type DevServerRestartResult = {
 
 type DevServerExitResult = ManagedProcessExitResult | DevServerRestartResult
 
-function resolveDevRuntimeBaseUrl(environment: NodeJS.ProcessEnv = process.env): string {
-  const configured =
-    environment.APP_URL
-    ?? environment.NEXT_PUBLIC_APP_URL
-    ?? environment.NEXTAUTH_URL
-  if (configured?.trim()) {
-    return configured.trim().replace(/\/+$/, '')
-  }
-  return `http://localhost:${environment.PORT?.trim() || '3000'}`
-}
-
-function writeDevSplashChildState(state: Record<string, unknown>): void {
-  if (process.env.OM_DEV_SPLASH_RUNTIME_WRAPPER === '1') return
-  const stateFile = process.env.OM_DEV_SPLASH_CHILD_STATE_FILE
-  if (!stateFile?.trim()) return
-
-  try {
-    fs.mkdirSync(path.dirname(stateFile), { recursive: true })
-    fs.writeFileSync(stateFile, `${JSON.stringify({
-      mode: process.env.OM_DEV_SPLASH_MODE || 'dev',
-      failed: false,
-      failureLines: [],
-      failureCommand: null,
-      ...state,
-    }, null, 2)}\n`)
-  } catch {
-    // Splash state is best-effort; terminal logs remain authoritative.
-  }
-}
-
-function writeDevSplashRuntimeStarting(detail = 'Starting Next.js dev server'): void {
-  writeDevSplashChildState({
-    phase: 'Preparing app runtime',
-    detail,
-    ready: false,
-    readyUrl: null,
-    loginUrl: null,
-    progressLabel: 'Launching app runtime',
-    activity: detail,
-  })
-}
-
-function resolveSplashProgressFallback(): { current: number; total: number } {
-  const current = Number.parseInt(process.env.OM_DEV_SPLASH_STAGE_CURRENT ?? '', 10)
-  const total = Number.parseInt(process.env.OM_DEV_SPLASH_STAGE_TOTAL ?? '', 10)
-  if (Number.isFinite(current) && Number.isFinite(total) && total > 0) {
-    return { current, total }
-  }
-  if (process.env.OM_DEV_SPLASH_MODE === 'greenfield' || process.env.OM_DEV_SPLASH_MODE === 'setup') {
-    return { current: 5, total: 5 }
-  }
-  return { current: 3, total: 3 }
-}
-
-function writeDevSplashRuntimeRestarting(reason: string): void {
-  const progress = resolveSplashProgressFallback()
-  writeDevSplashChildState({
-    phase: 'App runtime is restarting',
-    detail: `Reason: ${reason}`,
-    ready: false,
-    readyUrl: null,
-    loginUrl: null,
-    progressCurrent: progress.current,
-    progressTotal: progress.total,
-    progressLabel: 'Restarting app runtime',
-    activity: `App runtime restart: ${reason}`,
-  })
-}
-
-function writeDevSplashRuntimeReady(reason?: string): void {
-  const readyUrl = resolveDevRuntimeBaseUrl()
-  const progress = resolveSplashProgressFallback()
-  writeDevSplashChildState({
-    phase: 'App is ready',
-    detail: reason ? `Restart completed after ${reason}` : 'Next.js dev server is ready',
-    ready: true,
-    readyUrl,
-    loginUrl: `${readyUrl}/login`,
-    progressCurrent: progress.current,
-    progressTotal: progress.total,
-    progressPercent: 100,
-    progressLabel: 'App is ready',
-    activity: reason ? `Restart completed after ${reason}` : 'App runtime is ready',
-  })
-}
-
-function resolveDevWarmupReadyTimeoutMs(environment: NodeJS.ProcessEnv = process.env): number {
-  const parsed = Number.parseInt(environment.OM_DEV_WARMUP_READY_TIMEOUT_MS ?? '', 10)
-  if (Number.isFinite(parsed) && parsed >= 0) return parsed
-  return 300_000
-}
-
-async function waitForDevWarmupReadyFile(
-  filePath: string | undefined,
-  options: {
-    timeoutMs?: number
-    signal?: AbortSignal
-  } = {},
-): Promise<'ready' | 'timeout' | 'aborted'> {
-  const normalized = filePath?.trim()
-  if (!normalized) return 'ready'
-  const timeoutMs = options.timeoutMs ?? resolveDevWarmupReadyTimeoutMs()
-  const startedAt = Date.now()
-
-  while (true) {
-    if (options.signal?.aborted) return 'aborted'
-    try {
-      if (fs.existsSync(normalized)) return 'ready'
-    } catch {
-      // Keep polling; the runtime wrapper owns this best-effort marker.
-    }
-    if (timeoutMs >= 0 && Date.now() - startedAt >= timeoutMs) return 'timeout'
-    await new Promise((resolve) => setTimeout(resolve, 250))
-  }
-}
-
 type ModuleCommandLookupResult =
   | {
       status: 'ok'
@@ -717,17 +601,18 @@ async function runGeneratorSuite(quiet: boolean): Promise<void> {
 function createGenerateWatchChecksumFn(): () => Promise<string> {
   return async () => {
     const { createResolver } = await import('./lib/resolver')
-    const { calculateGenerateWatchStructureChecksum } = await import('./lib/generate-watch-structure')
+    const { calculateStructureChecksum } = await import('./lib/utils')
     const resolver = createResolver()
-    const moduleRoots = []
+    const tracked = new Set<string>([
+      path.join(resolver.getAppDir(), 'src', 'modules.ts'),
+      path.join(resolver.getAppDir(), 'src', 'modules'),
+    ])
     for (const entry of resolver.loadEnabledModules()) {
       const roots = resolver.getModulePaths(entry)
-      moduleRoots.push({ appBase: roots.appBase, pkgBase: roots.pkgBase })
+      tracked.add(roots.appBase)
+      tracked.add(roots.pkgBase)
     }
-    return calculateGenerateWatchStructureChecksum({
-      modulesFile: path.join(resolver.getAppDir(), 'src', 'modules.ts'),
-      moduleRoots,
-    })
+    return calculateStructureChecksum(Array.from(tracked))
   }
 }
 
@@ -1805,11 +1690,10 @@ export async function run(argv = process.argv) {
           let processes: ChildProcess[] = []
           let didRetryCorruptedTurbopackCache = false
           let stopping = false
-          let devRestartPromiseResolve: ((result: DevServerRestartResult) => void) | null = null
+          let envChangePromiseResolve: ((result: DevServerRestartResult) => void) | null = null
           let activeLazySupervisor: ReturnType<typeof startLazyWorkerSupervisor> | null = null
           let activeLazySchedulerSupervisor: ReturnType<typeof startLazySchedulerSupervisor> | null = null
           let activeGenerateWatcher: GenerateWatcherHandle | null = null
-          let lastRestartReason: string | null = null
           const generateWatcherMode: GenerateWatcherMode = resolveGenerateWatcherMode(process.env)
           const envReloader = createDevEnvReloader(appDir, process.env, initialProcessEnvironmentEntries)
 
@@ -1897,31 +1781,20 @@ export async function run(argv = process.argv) {
           const mercatoBin = resolveInstalledBinary(nodeModulesBases, '@open-mercato/cli/bin/mercato')
 
           const stopEnvWatcher = watchDevEnvFiles(appDir, (filePath) => {
-            devRestartPromiseResolve?.({
+            envChangePromiseResolve?.({
               label: 'Environment file change',
               restart: true,
               filePath,
             })
           })
-          const waitForDevRestart = (): Promise<DevServerRestartResult> =>
+
+          const waitForEnvChange = (): Promise<DevServerRestartResult> =>
             new Promise((resolve) => {
-              devRestartPromiseResolve = resolve
+              envChangePromiseResolve = resolve
             })
 
-          const startNextDev = (runtimeEnv: NodeJS.ProcessEnv): {
-            exitPromise: Promise<ManagedProcessExitResult>
-            readyPromise: Promise<void>
-          } => {
-            let readyResolve: () => void = () => undefined
-            const readyPromise = new Promise<void>((resolve) => {
-              readyResolve = resolve
-            })
-            const exitPromise = new Promise<ManagedProcessExitResult>((resolve) => {
-              writeDevSplashRuntimeStarting(
-                lastRestartReason
-                  ? `Restarting Next.js dev server. Reason: ${lastRestartReason}`
-                  : 'Starting Next.js dev server',
-              )
+          const startNextDev = (runtimeEnv: NodeJS.ProcessEnv): Promise<ManagedProcessExitResult> =>
+            new Promise((resolve) => {
               const nextProcess = spawn('node', [nextBin, 'dev', '--turbopack'], {
                 stdio: ['inherit', 'pipe', 'pipe'],
                 env: runtimeEnv,
@@ -1930,18 +1803,11 @@ export async function run(argv = process.argv) {
               processes.push(nextProcess)
 
               let combinedOutput = ''
-              let reportedReady = false
               const appendOutput = (chunk: string) => {
                 combinedOutput += chunk
                 if (combinedOutput.length > 32_768) {
                   combinedOutput = combinedOutput.slice(-32_768)
                 }
-                if (!reportedReady && /\bready in\b/i.test(chunk)) {
-                  reportedReady = true
-                  writeDevSplashRuntimeReady(lastRestartReason ?? undefined)
-                  lastRestartReason = null
-                  readyResolve()
-                }
               }
 
               nextProcess.stdout?.on('data', (chunk: Buffer | string) => {
@@ -1958,13 +1824,9 @@ export async function run(argv = process.argv) {
               nextProcess.on('exit', async (code, signal) => {
                 if (!didRetryCorruptedTurbopackCache && isTurbopackCacheCorruption(combinedOutput)) {
                   didRetryCorruptedTurbopackCache = true
-                  lastRestartReason = 'corrupted Turbopack dev cache'
-                  writeDevSplashRuntimeRestarting(lastRestartReason)
                   console.log('[server] Detected corrupted Turbopack dev cache. Clearing .mercato/next/dev and restarting Next.js once...')
                   removeTurbopackDevCache(appDir)
-                  const restarted = startNextDev(runtimeEnv)
-                  restarted.readyPromise.then(readyResolve)
-                  return resolve(await restarted.exitPromise)
+                  return resolve(await startNextDev(runtimeEnv))
                 }
                 resolve({
                   label: 'Next.js dev server',
@@ -1973,8 +1835,6 @@ export async function run(argv = process.argv) {
                 })
               })
             })
-            return { exitPromise, readyPromise }
-          }
 
           try {
             while (!stopping) {
@@ -1984,92 +1844,62 @@ export async function run(argv = process.argv) {
               const autoSpawnSchedulerMode = resolveAutoSpawnSchedulerMode(process.env)
               const queueStrategy = process.env.QUEUE_STRATEGY || 'local'
               const schedulerCommand = lookupModuleCommand(getCliModules(), 'scheduler', 'start')
-              const nextRuntime = startNextDev(runtimeEnv)
-              const restartPromise = waitForDevRestart()
-              const backgroundStartAbort = new AbortController()
-              const cancelBackgroundStart = () => backgroundStartAbort.abort()
-              nextRuntime.exitPromise.finally(cancelBackgroundStart)
-              restartPromise.then(cancelBackgroundStart)
-              let backgroundExitResolve: (result: ManagedProcessExitResult) => void = () => undefined
-              const backgroundExitPromise = new Promise<ManagedProcessExitResult>((resolve) => {
-                backgroundExitResolve = resolve
-              })
               const managedExitPromises: Promise<DevServerExitResult>[] = [
-                nextRuntime.exitPromise,
-                restartPromise,
-                backgroundExitPromise,
+                startNextDev(runtimeEnv),
+                waitForEnvChange(),
               ]
 
-              const startBackgroundServices = async () => {
-                if (stopping || backgroundStartAbort.signal.aborted) return
-
-                // Keep first-route compilation responsive: greenfield setup can
-                // leave vector/fulltext jobs ready. When the dev wrapper is
-                // active, wait for its /login + /backend warmup marker before
-                // workers and scheduler begin consuming CPU and database I/O.
-                const warmupReady = await waitForDevWarmupReadyFile(process.env.OM_DEV_WARMUP_READY_FILE, {
-                  timeoutMs: resolveDevWarmupReadyTimeoutMs(process.env),
-                  signal: backgroundStartAbort.signal,
-                })
-                if (warmupReady === 'aborted' || stopping || backgroundStartAbort.signal.aborted) return
-                if (warmupReady === 'timeout') {
-                  console.warn('[server] Timed out waiting for dev warmup marker; starting background services anyway.')
-                }
-
-                if (autoSpawnWorkersMode !== 'off') {
-                  const discoveredWorkers = getRegisteredCliWorkers()
-                  const discoveredWorkerQueues = [...new Set(discoveredWorkers.map((worker) => worker.queue))]
-                  if (discoveredWorkerQueues.length === 0) {
-                    console.error('[server] AUTO_SPAWN_WORKERS is enabled, but no queues were discovered from CLI modules. Run `yarn generate` and verify `.mercato/generated/modules.cli.generated.ts` contains worker entries. Continuing without auto-spawned workers.')
-                  } else if (autoSpawnWorkersMode === 'lazy') {
-                    console.log(`[server] Lazy worker auto-spawn enabled — workers will start on first job (${discoveredWorkerQueues.length} queue(s) watched).`)
-                    activeLazySupervisor = startLazyWorkerSupervisor({
-                      mercatoBin,
-                      appDir,
-                      runtimeEnv,
-                      workers: discoveredWorkers,
-                      pollMs: resolveLazyPollMs(process.env),
-                      restartOnUnexpectedExit: resolveLazyRestart(process.env),
-                    })
-                  } else {
-                    console.log('[server] Eager worker auto-spawn enabled - starting workers for all queues...')
-                    const workerProcess = spawn('node', [mercatoBin, 'queue', 'worker', '--all'], {
-                      stdio: 'inherit',
-                      env: runtimeEnv,
-                      cwd: appDir,
-                    })
-                    processes.push(workerProcess)
-                    waitForManagedProcessExit(workerProcess, formatQueueWorkerLabel(discoveredWorkerQueues)).then(backgroundExitResolve)
-                  }
+              // Start workers if enabled
+              if (autoSpawnWorkersMode !== 'off') {
+                const discoveredWorkers = getRegisteredCliWorkers()
+                const discoveredWorkerQueues = [...new Set(discoveredWorkers.map((worker) => worker.queue))]
+                if (discoveredWorkerQueues.length === 0) {
+                  console.error('[server] AUTO_SPAWN_WORKERS is enabled, but no queues were discovered from CLI modules. Run `yarn generate` and verify `.mercato/generated/modules.cli.generated.ts` contains worker entries. Continuing without auto-spawned workers.')
+                } else if (autoSpawnWorkersMode === 'lazy') {
+                  console.log(`[server] Lazy worker auto-spawn enabled — workers will start on first job (${discoveredWorkerQueues.length} queue(s) watched).`)
+                  activeLazySupervisor = startLazyWorkerSupervisor({
+                    mercatoBin,
+                    appDir,
+                    runtimeEnv,
+                    workers: discoveredWorkers,
+                    pollMs: resolveLazyPollMs(process.env),
+                    restartOnUnexpectedExit: resolveLazyRestart(process.env),
+                  })
+                } else {
+                  console.log('[server] Eager worker auto-spawn enabled - starting workers for all queues...')
+                  const workerProcess = spawn('node', [mercatoBin, 'queue', 'worker', '--all'], {
+                    stdio: 'inherit',
+                    env: runtimeEnv,
+                    cwd: appDir,
+                  })
+                  processes.push(workerProcess)
+                  managedExitPromises.push(waitForManagedProcessExit(workerProcess, formatQueueWorkerLabel(discoveredWorkerQueues)))
                 }
+              }
 
-                if (autoSpawnSchedulerMode !== 'off' && queueStrategy === 'local') {
-                  if (schedulerCommand.status !== 'ok') {
-                    console.log(`[server] Skipping scheduler auto-start — ${describeMissingModuleCommand(schedulerCommand)}`)
-                  } else if (autoSpawnSchedulerMode === 'lazy') {
-                    console.log('[server] Lazy scheduler auto-spawn enabled - scheduler will start when an enabled schedule exists.')
-                    activeLazySchedulerSupervisor = startLazySchedulerSupervisor({
-                      mercatoBin,
-                      appDir,
-                      runtimeEnv,
-                      pollMs: resolveLazySchedulerPollMs(process.env),
-                      restartOnUnexpectedExit: resolveLazySchedulerRestart(process.env),
-                    })
-                  } else {
-                    console.log('[server] Eager scheduler auto-spawn enabled - starting scheduler polling engine...')
-                    const schedulerProcess = spawn('node', [mercatoBin, 'scheduler', 'start'], {
-                      stdio: 'inherit',
-                      env: runtimeEnv,
-                      cwd: appDir,
-                    })
-                    processes.push(schedulerProcess)
-                    waitForManagedProcessExit(schedulerProcess, 'Scheduler polling engine').then(backgroundExitResolve)
-                  }
+              if (autoSpawnSchedulerMode !== 'off' && queueStrategy === 'local') {
+                if (schedulerCommand.status !== 'ok') {
+                  console.log(`[server] Skipping scheduler auto-start — ${describeMissingModuleCommand(schedulerCommand)}`)
+                } else if (autoSpawnSchedulerMode === 'lazy') {
+                  console.log('[server] Lazy scheduler auto-spawn enabled - scheduler will start when an enabled schedule exists.')
+                  activeLazySchedulerSupervisor = startLazySchedulerSupervisor({
+                    mercatoBin,
+                    appDir,
+                    runtimeEnv,
+                    pollMs: resolveLazySchedulerPollMs(process.env),
+                    restartOnUnexpectedExit: resolveLazySchedulerRestart(process.env),
+                  })
+                } else {
+                  console.log('[server] Eager scheduler auto-spawn enabled - starting scheduler polling engine...')
+                  const schedulerProcess = spawn('node', [mercatoBin, 'scheduler', 'start'], {
+                    stdio: 'inherit',
+                    env: runtimeEnv,
+                    cwd: appDir,
+                  })
+                  processes.push(schedulerProcess)
+                  managedExitPromises.push(waitForManagedProcessExit(schedulerProcess, 'Scheduler polling engine'))
                 }
               }
-              nextRuntime.readyPromise.then(() => {
-                void startBackgroundServices()
-              })
 
               if (generateWatcherMode === 'in-process') {
                 // Run the structural regeneration watcher inside this process
@@ -2097,15 +1927,11 @@ export async function run(argv = process.argv) {
               }
 
               const firstExit = await Promise.race(managedExitPromises)
-              if (isDevServerRestartResult(firstExit)) {
-                lastRestartReason = `${firstExit.label.toLowerCase()} (${path.basename(firstExit.filePath)})`
-                writeDevSplashRuntimeRestarting(lastRestartReason)
-              }
               await cleanupAndWait()
-              devRestartPromiseResolve = null
+              envChangePromiseResolve = null
 
               if (isDevServerRestartResult(firstExit)) {
-                console.log(`[server] Detected ${firstExit.label.toLowerCase()} (${path.basename(firstExit.filePath)}). Restarting app runtime...`)
+                console.log(`[server] Detected environment file change (${path.basename(firstExit.filePath)}). Restarting app runtime...`)
                 continue
               }