fix: concurrent cy.prompt() and Studio bundle download issues

cli/CHANGELOG.md

@@ -7,6 +7,10 @@ _Released 12/2/2025 (PENDING)_
 
 - Improved performance when viewing command snapshots in the Command Log. Element highlighting is now significantly faster, especially when highlighting multiple elements or complex pages. This is achieved by reducing redundant style calculations and batching DOM operations to minimize browser reflows. Addressed in [#32951](https://github.com/cypress-io/cypress/pull/32951).
 
+**Bugfixes:**
+
+- Updated the error message shown when the `cy.prompt()` bundle is deleted while in use. Ensured that the Cloud bundles are written atomically to avoid concurrent downloads causing issues. Addressed in [#33034](https://github.com/cypress-io/cypress/pull/33034).
+
 ## 15.7.0
 
 _Released 11/19/2025_

packages/driver/src/cy/commands/prompt/index.ts

@@ -63,23 +63,29 @@ const initializeModule = async (Cypress: Cypress.Cypress): Promise<CyPromptDrive
     })
   }
 
+  let module: CyPromptDriver | null = null
+
   // Once the cy prompt bundle is downloaded and ready,
   // we can initialize it via the module federation runtime
-  init({
-    remotes: [{
-      alias: 'cy-prompt',
-      type: 'module',
-      name: 'cy-prompt',
-      entryGlobalName: 'cy-prompt',
-      entry: '/__cypress-cy-prompt/driver/cy-prompt.js',
-      shareScope: 'default',
-    }],
-    name: 'driver',
-  })
-
-  // This cy-prompt.js file and any subsequent files are
-  // served from the cy prompt bundle.
-  const module = await loadRemote<CyPromptDriver>('cy-prompt')
+  try {
+    init({
+      remotes: [{
+        alias: 'cy-prompt',
+        type: 'module',
+        name: 'cy-prompt',
+        entryGlobalName: 'cy-prompt',
+        entry: '/__cypress-cy-prompt/driver/cy-prompt.js',
+        shareScope: 'default',
+      }],
+      name: 'driver',
+    })
+
+    // This cy-prompt.js file and any subsequent files are
+    // served from the cy prompt bundle.
+    module = await loadRemote<CyPromptDriver>('cy-prompt')
+  } catch (error) {
+    $errUtils.throwErrByPath('prompt.promptBundleNeedsRefresh')
+  }
 
   if (!module?.default) {
     $errUtils.throwErrByPath('prompt.promptDownloadError', {

packages/driver/src/cypress/error_messages.ts

@@ -1354,6 +1354,11 @@ export default {
         docsUrl: 'https://on.cypress.io/prompt-download-error',
       }
     },
+    promptBundleNeedsRefresh: stripIndent`\
+      Your \`cy.prompt\` Cloud code needs to be refreshed.
+
+      Please restart the app to get the latest version.
+    `,
     promptProxyError: {
       message: stripIndent`\
       \`cy.prompt\` requires an internet connection. To continue, you may need to configure Cypress with your proxy settings.

packages/server/lib/cloud/cy-prompt/ensure_cy_prompt_bundle.ts

@@ -1,9 +1,8 @@
-import { remove, ensureDir, readFile, pathExists } from 'fs-extra'
-
-import tar from 'tar'
+import { ensureDir, readFile, pathExists, remove } from 'fs-extra'
 import { getCyPromptBundle } from '../api/cy-prompt/get_cy_prompt_bundle'
 import path from 'path'
 import { verifySignature } from '../encryption'
+import { extractAtomic } from '../extract_atomic'
 
 interface EnsureCyPromptBundleOptions {
   cyPromptPath: string
@@ -21,19 +20,17 @@ interface EnsureCyPromptBundleOptions {
 export const ensureCyPromptBundle = async ({ cyPromptPath, cyPromptUrl, projectId }: EnsureCyPromptBundleOptions): Promise<Record<string, string>> => {
   const bundlePath = path.join(cyPromptPath, 'bundle.tar')
 
-  // First remove cyPromptPath to ensure we have a clean slate
-  await remove(cyPromptPath)
   await ensureDir(cyPromptPath)
 
+  const uniqueBundlePath = `${bundlePath}-${Math.random().toString(36).substring(2, 15)}`
   const responseManifestSignature: string = await getCyPromptBundle({
     cyPromptUrl,
     projectId,
-    bundlePath,
+    bundlePath: uniqueBundlePath,
   })
 
-  await tar.extract({
-    file: bundlePath,
-    cwd: cyPromptPath,
+  await extractAtomic(uniqueBundlePath, cyPromptPath).finally(async () => {
+    await remove(uniqueBundlePath).catch(() => { /* ignore */ })
   })
 
   const manifestPath = path.join(cyPromptPath, 'manifest.json')

packages/server/lib/cloud/extract_atomic.ts

@@ -0,0 +1,56 @@
+import { createReadStream } from 'fs'
+import tar from 'tar'
+import { ensureDir } from 'fs-extra'
+import path from 'path'
+import writeFileAtomic from 'write-file-atomic'
+
+export const extractAtomic = async (archivePath: string, destinationPath: string) => {
+  const entryPromises: Promise<void>[] = []
+
+  const parser = new tar.Parse()
+
+  parser.on('entry', (entry) => {
+    if (entry.type !== 'File') {
+      entry.resume() // skip non-files
+
+      return
+    }
+
+    const targetPath = path.join(destinationPath, entry.path)
+
+    const p = (async () => {
+      await ensureDir(path.dirname(targetPath))
+
+      const chunks: Buffer[] = []
+
+      for await (const chunk of entry) {
+        chunks.push(chunk)
+      }
+
+      const content = Buffer.concat(chunks)
+
+      await writeFileAtomic(targetPath, content, {
+        mode: entry.mode || 0o644,
+      })
+    })()
+
+    entryPromises.push(p)
+  })
+
+  // Pipe archive into parser
+  const stream = createReadStream(archivePath)
+
+  stream.pipe(parser)
+
+  // Wait for parser to finish and all entry writes to complete
+  await new Promise<void>((resolve, reject) => {
+    parser.on('end', resolve)
+    // Parser extends NodeJS.ReadWriteStream (EventEmitter), so it supports 'error' events
+    // even though the types don't explicitly declare it
+
+    ;(parser as NodeJS.ReadWriteStream).on('error', reject)
+    stream.on('error', reject)
+  })
+
+  await Promise.all(entryPromises)
+}

packages/server/lib/cloud/studio/ensure_studio_bundle.ts

@@ -1,9 +1,8 @@
 import { remove, ensureDir, readFile, pathExists } from 'fs-extra'
-
-import tar from 'tar'
 import { getStudioBundle } from '../api/studio/get_studio_bundle'
 import path from 'path'
 import { verifySignature } from '../encryption'
+import { extractAtomic } from '../extract_atomic'
 
 interface EnsureStudioBundleOptions {
   studioUrl: string
@@ -25,18 +24,16 @@ export const ensureStudioBundle = async ({
 }: EnsureStudioBundleOptions): Promise<Record<string, string>> => {
   const bundlePath = path.join(studioPath, 'bundle.tar')
 
-  // First remove studioPath to ensure we have a clean slate
-  await remove(studioPath)
   await ensureDir(studioPath)
 
-  const responseManifestSignature = await getStudioBundle({
+  const uniqueBundlePath = `${bundlePath}-${Math.random().toString(36).substring(2, 15)}`
+  const responseManifestSignature: string = await getStudioBundle({
     studioUrl,
-    bundlePath,
+    bundlePath: uniqueBundlePath,
   })
 
-  await tar.extract({
-    file: bundlePath,
-    cwd: studioPath,
+  await extractAtomic(uniqueBundlePath, studioPath).finally(async () => {
+    await remove(uniqueBundlePath).catch(() => { /* ignore */ })
   })
 
   const manifestPath = path.join(studioPath, 'manifest.json')

packages/server/package.json

@@ -136,7 +136,8 @@
     "wait-port": "1.1.0",
     "webdriver": "9.14.0",
     "webpack-virtual-modules": "0.5.0",
-    "widest-line": "3.1.0"
+    "widest-line": "3.1.0",
+    "write-file-atomic": "7.0.0"
   },
   "devDependencies": {
     "@babel/core": "7.28.0",