Preserve backup sessions on download failure

.changeset/preserve-backup-restore-session.md

@@ -0,0 +1,5 @@
+---
+'@cloudflare/sandbox': patch
+---
+
+Report failed parallel backup downloads as recoverable restore errors without terminating the backup session shell, so cleanup can complete and callers can retry restore.

packages/sandbox-container/tests/session.test.ts

@@ -169,6 +169,22 @@ describe('Session', () => {
       expect(result.stderr).toBe('');
     });
 
+    it('should preserve parent shell state when a child shell exits', async () => {
+      await session.exec('export BACKUP_SESSION_MARKER=original');
+      const tmpPath = join(testDir, 'parallel-download.tmp');
+      const result = await session.exec(
+        `( touch '${tmpPath}'; (set -o pipefail; false | cat) & J0=$!; wait $J0; E0=$?; FAILED=$(( $E0 )); if [ "$FAILED" -ne 0 ]; then rm -f '${tmpPath}'; exit 1; fi )`
+      );
+
+      expect(result.exitCode).toBe(1);
+
+      const afterFailure = await session.exec(
+        `printf '%s:%s' "$BACKUP_SESSION_MARKER" "$([ ! -e '${tmpPath}' ] && echo clean)"`
+      );
+      expect(afterFailure.exitCode).toBe(0);
+      expect(afterFailure.stdout).toBe('original:clean');
+    });
+
     it('should handle command not found', async () => {
       const result = await session.exec('nonexistentcommand123');
 

packages/sandbox/src/sandbox.ts

@@ -6733,10 +6733,16 @@ export class Sandbox<Env = unknown> extends Container<Env> implements ISandbox {
         `if [ "$FAILED" -ne 0 ]; then rm -f ${shellEscape(tmpPath)}; exit 1; fi`
       ].join('; ');
 
-      const result = await this.execWithSession(script, backupSession, {
-        timeout: 1810_000,
-        origin: 'internal'
-      });
+      // The child shell owns the script's explicit exit; the persistent backup
+      // session observes only the resulting command status.
+      const result = await this.execWithSession(
+        `( ${script} )`,
+        backupSession,
+        {
+          timeout: 1810_000,
+          origin: 'internal'
+        }
+      );
 
       if (result.exitCode !== 0) {
         await this.execWithSession(

packages/sandbox/tests/sandbox.test.ts

@@ -3241,6 +3241,65 @@ describe('Sandbox - Automatic Session Management', () => {
       expect(downloadCommand).not.toContain('.part0.tmp');
     });
 
+    it('should report and clean up a failed parallel download without exiting the session shell', async () => {
+      const { backupSandbox } = await createBackupSandbox();
+      const expectedSize = 16 * 1024 * 1024;
+      const backupSession = 'backup-session';
+      const internals = backupSandbox as unknown as {
+        downloadBackupParallel: (
+          archivePath: string,
+          r2Key: string,
+          expectedSize: number,
+          backupId: string,
+          dir: string,
+          backupSession: string
+        ) => Promise<void>;
+        execWithSession: (
+          command: string,
+          sessionId: string,
+          options: { timeout?: number; origin: 'internal' }
+        ) => Promise<{ stdout: string; stderr: string; exitCode: number }>;
+        generatePresignedGetURL: (r2Key: string) => Promise<string>;
+      };
+
+      vi.spyOn(internals, 'generatePresignedGetURL').mockResolvedValue(
+        'https://example.com/archive'
+      );
+      const execWithSessionSpy = vi
+        .spyOn(internals, 'execWithSession')
+        .mockResolvedValueOnce({ stdout: '', stderr: '', exitCode: 0 })
+        .mockResolvedValueOnce({
+          stdout: '',
+          stderr: 'part failed',
+          exitCode: 1
+        })
+        .mockResolvedValueOnce({ stdout: '', stderr: '', exitCode: 0 });
+
+      await expect(
+        internals.downloadBackupParallel(
+          '/var/backups/test.sqsh',
+          'backups/test/data.sqsh',
+          expectedSize,
+          'test-backup-id',
+          '/app/project',
+          backupSession
+        )
+      ).rejects.toThrow('Parallel download failed (exit code 1): part failed');
+
+      const downloadCommand = execWithSessionSpy.mock.calls[1][0];
+      expect(downloadCommand).toMatch(/^\( .*exit 1; fi \)$/);
+      expect(execWithSessionSpy.mock.calls[1]).toEqual([
+        downloadCommand,
+        backupSession,
+        { timeout: 1810_000, origin: 'internal' }
+      ]);
+      expect(execWithSessionSpy).toHaveBeenLastCalledWith(
+        "rm -f '/var/backups/test.sqsh.tmp'",
+        backupSession,
+        { origin: 'internal' }
+      );
+    });
+
     it('should reject unsupported backup roots before calling the container', async () => {
       const { backupSandbox } = await createBackupSandbox();
       const createArchiveSpy = vi.spyOn(