From d9220d2556a6403c558ba7bf5dd8f24f1d0e2b1d Mon Sep 17 00:00:00 2001
From: Simplereally <joshmackus@protonmail.com>
Date: Wed, 11 Mar 2026 23:34:12 +1100
Subject: [PATCH 1/4] fix: finalize convex optimization remediations

---
 components/debug/limit-tester.tsx             |   4 +-
 .../studio/batch/batch-action-button.test.tsx |  22 +-
 .../studio/batch/batch-action-button.tsx      |   4 +
 convex-optimization-branch-review.md          | 215 +++++++
 convex-optimiziations.md                      |  45 ++
 convex/_generated/api.d.ts                    |   2 +
 convex/batchGeneration.ts                     | 132 ++--
 convex/batchProcessor.ts                      | 290 ++++++---
 convex/lib/batchGenerationState.test.ts       | 112 ++++
 convex/lib/batchGenerationState.ts            | 121 ++++
 convex/schema.ts                              |   3 +
 convex/singleGeneration.ts                    |  34 +-
 convex/singleGenerationProcessor.ts           | 568 ++++++++++++------
 hooks/queries/use-generate-image.test.tsx     |  16 +-
 hooks/queries/use-generate-image.ts           |   6 +-
 hooks/use-batch-mode.ts                       |   1 +
 16 files changed, 1223 insertions(+), 352 deletions(-)
 create mode 100644 convex-optimization-branch-review.md
 create mode 100644 convex-optimiziations.md
 create mode 100644 convex/lib/batchGenerationState.test.ts
 create mode 100644 convex/lib/batchGenerationState.ts

diff --git a/components/debug/limit-tester.tsx b/components/debug/limit-tester.tsx
index 62abd38..40a2fd6 100644
--- a/components/debug/limit-tester.tsx
+++ b/components/debug/limit-tester.tsx
@@ -44,7 +44,7 @@ export function LimitTester() {
     const [naturalDimensions, setNaturalDimensions] = useState<{ w: number; h: number } | null>(null)
 
     const startGeneration = useMutation(api.singleGeneration.startGeneration)
-    const dispatchGeneration = useAction(api.singleGeneration.dispatchGeneration)
+    const processGeneration = useAction(api.singleGenerationProcessor.processGeneration)
     
     // BYOP context for API key
     const apiKey = usePollenApiKey()
@@ -81,7 +81,7 @@ export function LimitTester() {
                 apiKey,
             })
             setCurrentGenId(id)
-            void Promise.resolve(dispatchGeneration({ generationId: id, apiKey })).catch((dispatchError) => {
+            void Promise.resolve(processGeneration({ generationId: id, apiKey })).catch((dispatchError) => {
                 console.error("Immediate dispatch failed; recovery path will retry:", dispatchError)
             })
         } catch (error) {
diff --git a/components/studio/batch/batch-action-button.test.tsx b/components/studio/batch/batch-action-button.test.tsx
index 031ac3b..9ac8774 100644
--- a/components/studio/batch/batch-action-button.test.tsx
+++ b/components/studio/batch/batch-action-button.test.tsx
@@ -1,5 +1,6 @@
+import "@testing-library/jest-dom/vitest"
 import { render, screen, fireEvent } from "@testing-library/react"
-import { describe, it, expect, vi } from "vitest"
+import { beforeEach, describe, expect, it, vi } from "vitest"
 import { BatchActionButton } from "./batch-action-button"
 
 describe("BatchActionButton", () => {
@@ -53,6 +54,25 @@ describe("BatchActionButton", () => {
         expect(onResume).toHaveBeenCalledTimes(1)
     })
 
+    it("disables resume while paused items are still in flight", () => {
+        const onResume = vi.fn()
+        render(
+            <BatchActionButton
+                {...defaultProps}
+                isPaused={true}
+                inFlightCount={2}
+                onResume={onResume}
+            />
+        )
+
+        const resumeButton = screen.getByRole("button", { name: /resume/i })
+        expect(resumeButton).toBeDisabled()
+
+        fireEvent.click(resumeButton)
+
+        expect(onResume).not.toHaveBeenCalled()
+    })
+
     it("calls onCancel when cancel button is clicked", () => {
         const onCancel = vi.fn()
         render(<BatchActionButton {...defaultProps} onCancel={onCancel} />)
diff --git a/components/studio/batch/batch-action-button.tsx b/components/studio/batch/batch-action-button.tsx
index 854758c..133e484 100644
--- a/components/studio/batch/batch-action-button.tsx
+++ b/components/studio/batch/batch-action-button.tsx
@@ -45,6 +45,7 @@ export const BatchActionButton = React.memo(function BatchActionButton({
     className,
 }: BatchActionButtonProps) {
     const progress = totalCount > 0 ? (completedCount / totalCount) * 100 : 0
+    const isResumeDisabled = isPaused && inFlightCount > 0
     
     // Show in-flight indicator when paused and items are still processing
     const showInFlightIndicator = isPaused && inFlightCount > 0
@@ -94,6 +95,7 @@ export const BatchActionButton = React.memo(function BatchActionButton({
                     {/* The actual button - positioned above progress */}
                     <Button
                         onClick={isPaused ? onResume : onPause}
+                        disabled={isResumeDisabled}
                         variant="ghost"
                         size="lg"
                         className={cn(
@@ -102,11 +104,13 @@ export const BatchActionButton = React.memo(function BatchActionButton({
                             "border border-border/40 hover:border-border/60",
                             "rounded-lg overflow-hidden",
                             "transition-all duration-300",
+                            isResumeDisabled && "cursor-not-allowed opacity-70",
                             // Text color based on state
                             isPaused 
                                 ? "text-amber-600 dark:text-amber-400" 
                                 : "text-emerald-700 dark:text-emerald-300"
                         )}
+                        title={isResumeDisabled ? "Wait for in-flight images to finish before resuming" : undefined}
                     >
                         {/* Icon with subtle animation */}
                         <span className={cn(
diff --git a/convex-optimization-branch-review.md b/convex-optimization-branch-review.md
new file mode 100644
index 0000000..fd1b4b9
--- /dev/null
+++ b/convex-optimization-branch-review.md
@@ -0,0 +1,215 @@
+# Convex Optimization Branch Review
+
+## Scope
+
+I reviewed the branch against `origin/main` with focus on the changes tied to `convex-optimiziations.md`, especially:
+
+- `convex/batchGeneration.ts`
+- `convex/batchProcessor.ts`
+- `convex/singleGeneration.ts`
+- `convex/singleGenerationProcessor.ts`
+- `hooks/queries/use-generate-image.ts`
+- `components/debug/limit-tester.tsx`
+- related tests and UI surfaces
+
+I also cross-checked Convex-specific judgments against current official guidance:
+
+- `https://docs.convex.dev/functions/actions`
+- `https://docs.convex.dev/understanding/best-practices/`
+- `https://docs.convex.dev/scheduling/scheduled-functions`
+- `@convex-dev/workpool` README
+
+I ran the relevant test files as well:
+
+```bash
+bun run test hooks/queries/use-generate-image.test.tsx hooks/queries/use-batch-generation.test.ts hooks/use-batch-mode.test.ts
+```
+
+Those tests all passed, which is important context for the testing-gap finding below.
+
+## High-level take
+
+The overall direction of the branch is good and largely aligned with current Convex guidance:
+
+- moving retry waiting out of long-running actions is directionally correct
+- adding hard fetch timeouts is good
+- removing the extra single-generation action wrapper is directionally correct
+- adaptive throttling is a reasonable next step
+
+The main problem is that the new batch state machine has a correctness bug around `pause` / `resume` under pipelined scheduling.
+
+## Findings
+
+## P1 - Resuming a paused batch can duplicate item processing
+
+- **Severity**: P1
+- **Type**: clear bug, business logic regression, UX regression
+- **Where**:
+  - `convex/batchGeneration.ts:276-335`
+  - `convex/batchGeneration.ts:700-738`
+  - `convex/batchProcessor.ts:192-225`
+  - `components/studio/batch/batch-action-button.tsx:49-50`
+  - `components/studio/batch/batch-action-button.tsx:95-125`
+
+### Why this is a bug
+
+`currentIndex` is advanced when the next item is **scheduled**, not when it is **completed**.
+
+That means a paused batch can legitimately be in this state:
+
+- item `N` already scheduled / still in flight
+- `currentIndex === N`
+- UI shows `"N images finishing..."`
+
+`resumeBatchJob` then immediately schedules `currentIndex` again:
+
+- `convex/batchGeneration.ts:731-735`
+
+So if the user resumes before the already-scheduled item drains, the same item index can be processed twice.
+
+Because each first-attempt batch item also pipelines the next item at the start of processing:
+
+- `convex/batchProcessor.ts:192-204`
+
+this can cascade into:
+
+- duplicate generated images
+- inflated `completedCount` / `failedCount`
+- premature `totalProcessed >= totalCount`
+- early deletion of the batch job record
+
+### Why the UX contributes to it
+
+The UI explicitly surfaces that items are still finishing while paused:
+
+- `showInFlightIndicator = isPaused && inFlightCount > 0`
+
+but the same button still exposes `Resume` immediately. So the UI currently invites the exact unsafe transition that corrupts the batch state.
+
+### Recommendation
+
+Resume should not schedule a new item while any prior scheduled work is still outstanding.
+
+At minimum, resume needs one of these invariants:
+
+- only resume when `inFlightCount === 0`
+- track a separate `nextUnprocessedIndex` instead of reusing `currentIndex`
+- persist scheduled item identities so resume can tell whether the next index is already queued
+
+## P2 - `inFlightCount` becomes wrong after resume
+
+- **Severity**: P2
+- **Type**: clear bug, UI/UX regression
+- **Where**:
+  - `convex/batchGeneration.ts:151-175`
+  - `convex/batchGeneration.ts:303-318`
+  - `convex/batchGeneration.ts:438-450`
+  - `convex/batchGeneration.ts:724-735`
+
+### Why this is a bug
+
+The system treats `inFlightCount` as including already-scheduled outstanding work:
+
+- initial batch starts with `inFlightCount: 1`
+- scheduling the next item increments it
+- recording a result decrements it
+
+But `resumeBatchJob` schedules work without incrementing `inFlightCount`.
+
+That means after a clean paused state with `inFlightCount = 0`, resuming undercounts by one immediately. From there the counter can hit zero even though work is still running or scheduled.
+
+### Impact
+
+- the paused UI can claim everything has drained when one item is still outstanding
+- users can think it is safe to resume / pause again when it is not
+- any future logic that relies on `inFlightCount` as a drain signal will be unreliable
+
+This also makes the P1 duplication bug easier to trigger repeatedly.
+
+### Recommendation
+
+Either:
+
+- increment `inFlightCount` when resume schedules the restart item
+
+or better:
+
+- redesign the batch state model so `inFlightCount` is derived from durable queued/running state instead of manual increments/decrements
+
+## P3 - The new batch lifecycle is not protected by regression tests
+
+- **Severity**: P3
+- **Type**: high-value testing gap
+- **Where**:
+  - `hooks/use-batch-mode.test.ts:306-442`
+  - `hooks/queries/use-batch-generation.test.ts:46-107`
+  - `hooks/queries/use-batch-generation.test.ts:141-171`
+
+### Why this matters
+
+I ran the relevant tests and they all passed, but the current coverage only checks:
+
+- basic hook return shapes
+- simple paused/processing flag mapping
+- simple progress mapping
+
+It does **not** cover the dangerous transitions introduced by the optimization work:
+
+- pause while scheduled items are still outstanding
+- resume before in-flight work drains
+- `currentIndex` / `inFlightCount` invariants under pipelining
+- duplicate scheduling protection
+
+This is why the P1/P2 bug can exist while the branch still looks green.
+
+### Recommendation
+
+Add targeted tests around the batch state machine, not just hook shape tests. The minimum valuable cases are:
+
+- paused batch with `inFlightCount > 0` cannot safely schedule the same `currentIndex` twice
+- resume preserves correct `inFlightCount`
+- total processed count cannot be incremented twice for the same item index
+
+## P4 - Old public single-generation wrapper is now stale API surface
+
+- **Severity**: P4
+- **Type**: maintainability / API hygiene
+- **Where**:
+  - `convex/singleGeneration.ts:106-134`
+  - current consumers now use `api.singleGenerationProcessor.processGeneration`
+
+### Why this matters
+
+This branch correctly moved the hot path to the public `singleGenerationProcessor.processGeneration` action, which removes the extra wrapper layer and is more in line with current Convex guidance about avoiding unnecessary `runAction` overhead.
+
+However, `singleGeneration.dispatchGeneration` is still exported as a public action even though current consumers no longer use it.
+
+That leaves two public entrypoints for the same behavior:
+
+- the new direct path
+- the old wrapper path
+
+Low severity, but it increases confusion and makes it easy for a future caller to accidentally reintroduce the extra wrapper overhead.
+
+### Recommendation
+
+Remove the stale public wrapper or make the public API converge on one entrypoint only.
+
+## Non-findings worth calling out
+
+These branch decisions looked good after doc validation and I would keep them:
+
+- **Retry rescheduling instead of sleeping in actions**
+  - aligned with the cost problem described in the spec
+- **Hard provider fetch timeout**
+  - good protection against long-tail provider stalls
+- **Removing the extra single-generation action wrapper from the hot path**
+  - aligned with current Convex guidance that `runAction` should generally only be used when crossing runtimes
+- **Adaptive throttling as a scheduler-level control**
+  - reasonable, and Workpool is not obviously required yet if the batch lifecycle bugs are fixed first
+
+## Recommended fix order
+
+- **First**: fix P1 and P2 together in the batch state machine
+- **Second**: add the regression tests from P3 before making further scheduler tweaks
+- **Third**: clean up the stale single-generation wrapper from P4
diff --git a/convex-optimiziations.md b/convex-optimiziations.md
new file mode 100644
index 0000000..5ddff50
--- /dev/null
+++ b/convex-optimiziations.md
@@ -0,0 +1,45 @@
+Yes — there’s a clear path to reduce this **a lot** while keeping the same UX.
+
+## What’s likely driving cost
+
+Based on your code + latest Convex docs:
+
+- `singleGenerationProcessor.processGeneration` and `batchProcessor.processBatchItem` are both Node actions (`"use node"`), and Node actions are billed at **512MB** runtime memory ([limits](https://docs.convex.dev/production/state/limits.md)).
+- Both actions spend significant wall-time waiting on external work (Pollinations + retries), and in `fetchWithRetry` you currently **sleep inside the action** between retries (`convex/lib/retry.ts`).
+- `singleGeneration.dispatchGeneration` wraps `processGeneration` via `ctx.runAction(...)` (`convex/singleGeneration.ts`), which Convex docs call out as overhead-heavy unless crossing runtimes ([actions best practices](https://docs.convex.dev/functions/actions)).
+- Batch scheduling is aggressively pipelined (`100ms + jitter`) in `convex/batchGeneration.ts`, which can increase 429/5xx retry pressure and burn more GBh.
+
+## Highest-impact fixes (without UX loss)
+
+1. **Move retry backoff out of running actions**
+   - Instead of `sleep(...)` in `fetchWithRetry`, schedule the next retry attempt via `ctx.scheduler.runAfter(...)` and exit.
+   - Keeps persistence, keeps reactive UX, cuts billed “idle waiting” time.
+
+2. **Add hard fetch timeout + retry by reschedule**
+   - Abort slow provider calls (e.g. 45-90s depending image/video), mark attempt, reschedule.
+   - Prevents long-tail stuck calls from eating GBh.
+
+3. **Adaptive batch throttling**
+   - Dynamically increase inter-item delay when 429/5xx spike, decrease when healthy.
+   - Usually lowers retries and total GBh while keeping throughput stable.
+
+4. **Remove extra action wrapper overhead in single flow**
+   - Current: client -> `dispatchGeneration` action -> `runAction(processGeneration)`.
+   - Better: reduce one layer (or switch back to mutation-scheduled processor if acceptable).
+   - This is a smaller win than #1/#2 but still worthwhile.
+
+5. **Stop burning real generation compute in dev by default**
+   - Your `dev` usage is huge too. Add a dev-only mock/placeholder path unless explicitly enabled.
+
+## Convex-idiomatic guidance (2026 docs)
+
+- Mutation that records intent + schedules background work is still the canonical pattern ([scheduled functions](https://docs.convex.dev/scheduling/scheduled-functions), [actions](https://docs.convex.dev/functions/actions)).
+- Free tier has tight scheduled concurrency; if you need controlled parallelism/retries, `@convex-dev/workpool` is now a strong fit ([workpool README](https://raw.githubusercontent.com/get-convex/workpool/main/README.md)).
+
+## Recommended order for you
+
+- **Phase 1 (fast, biggest ROI):** #1 + #2 + #5  
+- **Phase 2:** #3  
+- **Phase 3:** #4 / workpool migration if needed
+
+If you want, I can implement **Phase 1 now** directly in your codebase (retry rescheduling + timeout + dev guard) and keep your current UX contract intact.
\ No newline at end of file
diff --git a/convex/_generated/api.d.ts b/convex/_generated/api.d.ts
index 2a96fbf..0c283e4 100644
--- a/convex/_generated/api.d.ts
+++ b/convex/_generated/api.d.ts
@@ -18,6 +18,7 @@ import type * as favorites from "../favorites.js";
 import type * as follows from "../follows.js";
 import type * as generatedImages from "../generatedImages.js";
 import type * as http from "../http.js";
+import type * as lib_batchGenerationState from "../lib/batchGenerationState.js";
 import type * as lib_crypto from "../lib/crypto.js";
 import type * as lib_dirtberryCrop from "../lib/dirtberryCrop.js";
 import type * as lib_groq from "../lib/groq.js";
@@ -73,6 +74,7 @@ declare const fullApi: ApiFromModules<{
   follows: typeof follows;
   generatedImages: typeof generatedImages;
   http: typeof http;
+  "lib/batchGenerationState": typeof lib_batchGenerationState;
   "lib/crypto": typeof lib_crypto;
   "lib/dirtberryCrop": typeof lib_dirtberryCrop;
   "lib/groq": typeof lib_groq;
diff --git a/convex/batchGeneration.ts b/convex/batchGeneration.ts
index 3cd6c45..83ee651 100644
--- a/convex/batchGeneration.ts
+++ b/convex/batchGeneration.ts
@@ -23,6 +23,10 @@ import {
     mutation,
     query
 } from "./_generated/server"
+import {
+    buildRecordBatchItemResultTransition,
+    getResumeBatchDecision,
+} from "./lib/batchGenerationState"
 import { analyzePromptForNSFW } from "./lib/nsfwDetection"
 import { canUserGenerate } from "./lib/subscription"
 
@@ -34,6 +38,10 @@ const MIN_BATCH_SIZE = 1
 
 /** Base delay between generations in milliseconds (100ms = 10 req/s) */
 const BASE_RATE_LIMIT_DELAY_MS = 100
+const MAX_ADAPTIVE_DELAY_MS = 2_000
+const THROTTLE_BACKOFF_MULTIPLIER = 1.5
+const TRANSIENT_BACKOFF_MULTIPLIER = 1.25
+const SUCCESS_RECOVERY_MULTIPLIER = 0.9
 
 /** Min jitter to add (20ms) */
 const MIN_JITTER_MS = 20
@@ -54,6 +62,7 @@ type BatchJobSummary = {
     failedCount: number
     currentIndex: number
     inFlightCount?: number
+    adaptiveDelayMs?: number
     createdAt: number
     updatedAt: number
     lastErrorCode?: number
@@ -74,6 +83,7 @@ function toBatchJobSummary(job: Doc<"batchJobs">): BatchJobSummary {
         failedCount: job.failedCount,
         currentIndex: job.currentIndex,
         inFlightCount: job.inFlightCount,
+        adaptiveDelayMs: job.adaptiveDelayMs,
         createdAt: job.createdAt,
         updatedAt: job.updatedAt,
         lastErrorCode: job.lastErrorCode,
@@ -152,9 +162,11 @@ export const startBatchJob = mutation({
             failedCount: 0,
             currentIndex: 0,
             inFlightCount: 1,
+            adaptiveDelayMs: BASE_RATE_LIMIT_DELAY_MS,
             generationParams: args.generationParams,
             apiKey: args.apiKey, // Store the API key for use by processor actions
             imageIds: [],
+            settledItemIndexes: [],
             createdAt: now,
             updatedAt: now,
         })
@@ -310,10 +322,14 @@ export const scheduleNextBatchItem = internalMutation({
             })
         }
 
-        // Calculate delay with jitter
-        // 100ms base + 20-100ms jitter
+        // Calculate delay with jitter.
+        // Delay dynamically adapts based on recent provider pressure.
+        const baseDelay = Math.min(
+            MAX_ADAPTIVE_DELAY_MS,
+            Math.max(BASE_RATE_LIMIT_DELAY_MS, batchJob.adaptiveDelayMs ?? BASE_RATE_LIMIT_DELAY_MS)
+        )
         const jitter = Math.floor(Math.random() * (MAX_JITTER_MS - MIN_JITTER_MS + 1)) + MIN_JITTER_MS
-        const delay = BASE_RATE_LIMIT_DELAY_MS + jitter
+        const delay = baseDelay + jitter
 
         await ctx.scheduler.runAfter(delay, internal.batchProcessor.processBatchItem, {
             batchJobId: args.batchJobId,
@@ -324,6 +340,55 @@ export const scheduleNextBatchItem = internalMutation({
     },
 })
 
+/**
+ * Adaptive throttling signal from the batch processor.
+ * Speeds up slowly after success and backs off quickly on provider pressure.
+ */
+export const adjustAdaptiveDelay = internalMutation({
+    args: {
+        batchJobId: v.id("batchJobs"),
+        outcome: v.union(
+            v.literal("success"),
+            v.literal("throttle"),
+            v.literal("transient_error")
+        ),
+    },
+    handler: async (ctx, args) => {
+        const batchJob = await ctx.db.get(args.batchJobId)
+        if (!batchJob) return
+
+        const currentDelay = Math.min(
+            MAX_ADAPTIVE_DELAY_MS,
+            Math.max(BASE_RATE_LIMIT_DELAY_MS, batchJob.adaptiveDelayMs ?? BASE_RATE_LIMIT_DELAY_MS)
+        )
+
+        let nextDelay = currentDelay
+        if (args.outcome === "throttle") {
+            nextDelay = Math.min(
+                MAX_ADAPTIVE_DELAY_MS,
+                Math.round(currentDelay * THROTTLE_BACKOFF_MULTIPLIER)
+            )
+        } else if (args.outcome === "transient_error") {
+            nextDelay = Math.min(
+                MAX_ADAPTIVE_DELAY_MS,
+                Math.round(currentDelay * TRANSIENT_BACKOFF_MULTIPLIER)
+            )
+        } else {
+            nextDelay = Math.max(
+                BASE_RATE_LIMIT_DELAY_MS,
+                Math.round(currentDelay * SUCCESS_RECOVERY_MULTIPLIER)
+            )
+        }
+
+        if (nextDelay !== (batchJob.adaptiveDelayMs ?? BASE_RATE_LIMIT_DELAY_MS)) {
+            await ctx.db.patch(args.batchJobId, {
+                adaptiveDelayMs: nextDelay,
+                updatedAt: Date.now(),
+            })
+        }
+    },
+})
+
 /**
  * Record the result of a batch item processing.
  * Called at the END of processing an item.
@@ -349,54 +414,29 @@ export const recordBatchItemResult = internalMutation({
 
         const now = Date.now()
 
-        // Prepare updates
+        const transition = buildRecordBatchItemResultTransition(batchJob, {
+            itemIndex: args.itemIndex,
+            success: args.success,
+            imageId: args.imageId,
+            errorCode: args.errorCode,
+            retryCount: args.retryCount,
+        })
+
         const updates: Partial<Doc<"batchJobs">> = {
+            ...transition.updates,
             updatedAt: now,
-            // Reset retry count for the next item logic isn't relevant here anymore
-            // as we track retries per item in memory during action
-        }
-
-        if (args.success) {
-            updates.completedCount = batchJob.completedCount + 1
-            if (args.imageId) {
-                updates.imageIds = [...batchJob.imageIds, args.imageId]
-            }
-        } else {
-            updates.failedCount = batchJob.failedCount + 1
-            // Store the HTTP error code for client-side detection (401=auth, 402=budget, 403=access)
-            if (args.errorCode !== undefined) {
-                updates.lastErrorCode = args.errorCode
-            }
         }
 
-        // Track the retry count for the completed item (for metrics/debugging)
-        // We might want to store this better but for now overwriting is "okay" as a last-seen metric
-        if (args.retryCount !== undefined && args.retryCount > 0) {
-            updates.currentItemRetryCount = args.retryCount
-        }
-
-        // Decrement in-flight count (this item is now done)
-        const currentInFlight = batchJob.inFlightCount ?? 1
-        updates.inFlightCount = Math.max(0, currentInFlight - 1)
-
-        // Check completion status
-        // Note: Since we have parallel processing, we can't just check if `nextIndex >= totalCount`
-        // We should check if `completedCount + failedCount >= totalCount`
-        const totalProcessed = (updates.completedCount ?? batchJob.completedCount) + (updates.failedCount ?? batchJob.failedCount)
-
-        if (totalProcessed >= batchJob.totalCount) {
+        if (transition.shouldDelete) {
             // Job complete - delete the record ("nuke" policy)
             // This removes the API key from the database immediately
             await ctx.db.delete(args.batchJobId)
-            return { success: true }
-        } else if (batchJob.status === "pending") {
-            // If this was the first result, ensure we are "processing"
-            updates.status = "processing"
+            return { success: true, duplicate: transition.isDuplicate }
         }
 
         await ctx.db.patch(args.batchJobId, updates)
 
-        return { success: true }
+        return { success: true, duplicate: transition.isDuplicate }
     },
 })
 
@@ -661,9 +701,21 @@ export const resumeBatchJob = mutation({
             throw new Error("Batch job is not paused")
         }
 
+        const resumeDecision = getResumeBatchDecision(batchJob)
+        if (!resumeDecision.canSchedule) {
+            if (resumeDecision.reason === "in_flight") {
+                throw new ConvexError({
+                    code: "BATCH_STILL_DRAINING",
+                    message: "Wait for in-flight batch items to finish before resuming.",
+                })
+            }
+            return { success: true }
+        }
+
         // Update status to processing
         await ctx.db.patch(args.batchJobId, {
             status: "processing",
+            inFlightCount: resumeDecision.nextInFlightCount,
             updatedAt: Date.now(),
         })
 
diff --git a/convex/batchProcessor.ts b/convex/batchProcessor.ts
index baacfec..85bd5ce 100644
--- a/convex/batchProcessor.ts
+++ b/convex/batchProcessor.ts
@@ -20,13 +20,13 @@ import { internalAction } from "./_generated/server"
 import {
     buildPollinationsUrl,
     classifyApiError,
+    calculateBackoffDelay,
     cropDirtberryImageBuffer,
     getDirtberrySourceDimensions,
     isDirtberryModel,
     generateR2Key,
     generateThumbnailKey,
     uploadMediaWithThumbnail,
-    fetchWithRetry,
     type RetryConfig,
 } from "./lib"
 
@@ -40,6 +40,12 @@ const POLLINATIONS_RETRY_CONFIG: RetryConfig = {
     baseDelayMs: 2000,
     maxDelayMs: 30000,
 }
+const POLLINATIONS_FETCH_TIMEOUT_MS = 45_000
+const MAX_POLLINATIONS_ATTEMPTS = POLLINATIONS_RETRY_CONFIG.maxRetries + 1
+const ENABLE_DEV_GENERATION_MOCK = process.env.CONVEX_ENABLE_DEV_GENERATION_MOCK === "true"
+const MOCK_PNG_BASE64 =
+    "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAwMCAO7k6xwAAAAASUVORK5CYII="
+const MOCK_IMAGE_BUFFER = Buffer.from(MOCK_PNG_BASE64, "base64")
 
 /**
  * Determine if an API error should be retried based on status and response.
@@ -58,6 +64,107 @@ function shouldRetryPollinationsError(status: number, errorText: string): boolea
     return classification.isRetryable
 }
 
+type RetryKind = "throttle" | "transient_error" | "permanent"
+
+type PollinationsAttemptResult =
+    | { success: true; response: Response }
+    | {
+        success: false
+        errorMessage: string
+        statusCode?: number
+        retryable: boolean
+        retryKind: RetryKind
+    }
+
+function formatApiErrorText(rawErrorText: string): string {
+    try {
+        const parseRecursive = (input: unknown): unknown => {
+            if (typeof input !== "string") return input
+            try {
+                const parsed = JSON.parse(input)
+                if (parsed && typeof parsed === "object") {
+                    for (const key in parsed) {
+                        ;(parsed as Record<string, unknown>)[key] = parseRecursive(
+                            (parsed as Record<string, unknown>)[key]
+                        )
+                    }
+                }
+                return parsed
+            } catch {
+                return input
+            }
+        }
+        const parsed = parseRecursive(rawErrorText)
+        return typeof parsed === "string" ? parsed : JSON.stringify(parsed, null, 2)
+    } catch {
+        return rawErrorText
+    }
+}
+
+async function fetchPollinationsWithTimeout(
+    url: string,
+    apiKey: string,
+    timeoutMs: number,
+    logger: string
+): Promise<PollinationsAttemptResult> {
+    const controller = new AbortController()
+    const timeoutId = setTimeout(() => controller.abort(), timeoutMs)
+
+    try {
+        const response = await fetch(url, {
+            method: "GET",
+            headers: {
+                Authorization: `Bearer ${apiKey}`,
+            },
+            signal: controller.signal,
+        })
+
+        if (response.ok) {
+            return { success: true, response }
+        }
+
+        const rawErrorText = await response.text()
+        const displayError = formatApiErrorText(rawErrorText)
+        const errorMessage = `HTTP ${response.status}: ${displayError}`
+        const retryable = shouldRetryPollinationsError(response.status, rawErrorText)
+        const retryKind: RetryKind = !retryable
+            ? "permanent"
+            : response.status === 429
+              ? "throttle"
+              : "transient_error"
+
+        return {
+            success: false,
+            errorMessage,
+            statusCode: response.status,
+            retryable,
+            retryKind,
+        }
+    } catch (error) {
+        const isAbort = error instanceof Error && error.name === "AbortError"
+        const errorMessage = isAbort
+            ? `Pollinations request timed out after ${timeoutMs}ms`
+            : error instanceof Error
+              ? error.message
+              : "Unknown network error"
+        console.error(`${logger} Pollinations fetch failed: ${errorMessage}`)
+        return {
+            success: false,
+            errorMessage,
+            retryable: true,
+            retryKind: "transient_error",
+        }
+    } finally {
+        clearTimeout(timeoutId)
+    }
+}
+
+function shouldUseDevGenerationMock(isVideoRequest: boolean): boolean {
+    const deployment = process.env.CONVEX_DEPLOYMENT ?? ""
+    const isDevDeployment = deployment.startsWith("dev:")
+    return ENABLE_DEV_GENERATION_MOCK && isDevDeployment && !isVideoRequest
+}
+
 // ============================================================
 // Internal Action
 // ============================================================
@@ -76,21 +183,24 @@ export const processBatchItem = internalAction({
     args: {
         batchJobId: v.id("batchJobs"),
         itemIndex: v.number(),
+        attempt: v.optional(v.number()),
     },
     handler: async (ctx, args) => {
         const logger = `[BatchProcessor]`
+        const attempt = args.attempt ?? 1
 
-        // 1. Fire-and-forget scheduling of the NEXT item immediately
-        // This ensures high throughput (10 req/s) by pipelining requests
-        // independent of how long the current generation takes.
-        try {
-            await ctx.runMutation(internal.batchGeneration.scheduleNextBatchItem, {
-                batchJobId: args.batchJobId,
-                currentItemIndex: args.itemIndex,
-            })
-        } catch (error) {
-            console.error(`${logger} Failed to schedule next item:`, error)
-            // Continue processing current item even if scheduling next fails
+        // Fire-and-forget scheduling of the NEXT item immediately, but only
+        // for the first attempt of this item (retries should not fan out).
+        if (attempt === 1) {
+            try {
+                await ctx.runMutation(internal.batchGeneration.scheduleNextBatchItem, {
+                    batchJobId: args.batchJobId,
+                    currentItemIndex: args.itemIndex,
+                })
+            } catch (error) {
+                console.error(`${logger} Failed to schedule next item:`, error)
+                // Continue processing current item even if scheduling next fails
+            }
         }
 
         // Get the batch job to check status and get params
@@ -115,7 +225,9 @@ export const processBatchItem = internalAction({
             return
         }
 
-        console.log(`${logger} Processing item ${args.itemIndex + 1}/${batchJob.totalCount} for batch ${args.batchJobId}`)
+        console.log(
+            `${logger} Processing item ${args.itemIndex + 1}/${batchJob.totalCount} for batch ${args.batchJobId} (attempt ${attempt}/${MAX_POLLINATIONS_ATTEMPTS})`
+        )
 
         // Use the API key stored in the batch job (BYOP flow)
         const pollinationsApiKey = batchJob.apiKey
@@ -128,6 +240,7 @@ export const processBatchItem = internalAction({
                 itemIndex: args.itemIndex,
                 success: false,
                 errorMessage: "No Pollinations API key configured. Please connect to Pollinations first.",
+                retryCount: attempt > 1 ? attempt - 1 : undefined,
             })
             return
         }
@@ -139,63 +252,99 @@ export const processBatchItem = internalAction({
             const INT32_MAX = 2147483647
             const rawSeed = batchJob.generationParams.seed ?? Math.floor(Math.random() * INT32_MAX)
             const seed = Math.min(rawSeed, INT32_MAX)
+            const isVideoRequest =
+                batchJob.generationParams.duration !== undefined ||
+                batchJob.generationParams.audio !== undefined ||
+                batchJob.generationParams.aspectRatio !== undefined ||
+                batchJob.generationParams.lastFrameImage !== undefined
+
+            let imageBuffer: Buffer
+            let contentType: string
+
+            if (shouldUseDevGenerationMock(isVideoRequest)) {
+                imageBuffer = Buffer.from(MOCK_IMAGE_BUFFER)
+                contentType = "image/png"
+                console.log(
+                    `${logger} Dev mock enabled, using placeholder image for batch ${args.batchJobId} item ${args.itemIndex + 1}`
+                )
+            } else {
+                // Build the generation URL
+                const generationUrl = buildPollinationsUrl({
+                    prompt: batchJob.generationParams.prompt,
+                    negativePrompt: batchJob.generationParams.negativePrompt,
+                    model: batchJob.generationParams.model,
+                    width: dirtberrySourceDimensions?.width ?? batchJob.generationParams.width,
+                    height: dirtberrySourceDimensions?.height ?? batchJob.generationParams.height,
+                    seed,
+                    enhance: batchJob.generationParams.enhance,
+                    private: batchJob.generationParams.private,
+                    safe: batchJob.generationParams.safe,
+                    image: batchJob.generationParams.image,
+                    // Video-specific parameters
+                    duration: batchJob.generationParams.duration,
+                    audio: batchJob.generationParams.audio,
+                    aspectRatio: batchJob.generationParams.aspectRatio,
+                    lastFrameImage: batchJob.generationParams.lastFrameImage,
+                })
 
-            // Build the generation URL
-            const generationUrl = buildPollinationsUrl({
-                prompt: batchJob.generationParams.prompt,
-                negativePrompt: batchJob.generationParams.negativePrompt,
-                model: batchJob.generationParams.model,
-                width: dirtberrySourceDimensions?.width ?? batchJob.generationParams.width,
-                height: dirtberrySourceDimensions?.height ?? batchJob.generationParams.height,
-                seed,
-                enhance: batchJob.generationParams.enhance,
-                private: batchJob.generationParams.private,
-                safe: batchJob.generationParams.safe,
-                image: batchJob.generationParams.image,
-                // Video-specific parameters
-                duration: batchJob.generationParams.duration,
-                audio: batchJob.generationParams.audio,
-                aspectRatio: batchJob.generationParams.aspectRatio,
-                lastFrameImage: batchJob.generationParams.lastFrameImage,
-            })
-
-            // Log generation request without prompt (which may contain PII)
-            console.log(`${logger} Generating with model=${batchJob.generationParams.model}, size=${batchJob.generationParams.width}x${batchJob.generationParams.height}, seed=${seed}`)
+                console.log(
+                    `${logger} Generating with model=${batchJob.generationParams.model}, size=${batchJob.generationParams.width}x${batchJob.generationParams.height}, seed=${seed}`
+                )
+
+                const pollinationsAttempt = await fetchPollinationsWithTimeout(
+                    generationUrl,
+                    pollinationsApiKey,
+                    POLLINATIONS_FETCH_TIMEOUT_MS,
+                    `${logger} Item ${args.itemIndex + 1}`
+                )
+
+                if (!pollinationsAttempt.success) {
+                    const canRetry =
+                        pollinationsAttempt.retryable && attempt < MAX_POLLINATIONS_ATTEMPTS
+
+                    if (canRetry) {
+                        await ctx.runMutation(internal.batchGeneration.adjustAdaptiveDelay, {
+                            batchJobId: args.batchJobId,
+                            outcome:
+                                pollinationsAttempt.retryKind === "throttle"
+                                    ? "throttle"
+                                    : "transient_error",
+                        })
+
+                        const delayMs = Math.round(
+                            calculateBackoffDelay(
+                                attempt - 1,
+                                POLLINATIONS_RETRY_CONFIG.baseDelayMs,
+                                POLLINATIONS_RETRY_CONFIG.maxDelayMs
+                            )
+                        )
+                        await ctx.scheduler.runAfter(delayMs, internal.batchProcessor.processBatchItem, {
+                            batchJobId: args.batchJobId,
+                            itemIndex: args.itemIndex,
+                            attempt: attempt + 1,
+                        })
+                        console.error(
+                            `${logger} Item ${args.itemIndex + 1} failed (attempt ${attempt}/${MAX_POLLINATIONS_ATTEMPTS}), retrying in ${delayMs}ms: ${pollinationsAttempt.errorMessage}`
+                        )
+                        return
+                    }
 
-            // Call Pollinations API with retry logic
-            const result = await fetchWithRetry(
-                generationUrl,
-                {
-                    method: "GET",
-                    headers: {
-                        Authorization: `Bearer ${pollinationsApiKey}`,
-                    },
-                },
-                shouldRetryPollinationsError,
-                POLLINATIONS_RETRY_CONFIG,
-                `${logger} Item ${args.itemIndex + 1}`
-            )
+                    await ctx.runMutation(internal.batchGeneration.recordBatchItemResult, {
+                        batchJobId: args.batchJobId,
+                        itemIndex: args.itemIndex,
+                        success: false,
+                        errorMessage: pollinationsAttempt.errorMessage,
+                        errorCode: pollinationsAttempt.statusCode,
+                        retryCount: attempt > 1 ? attempt - 1 : undefined,
+                    })
+                    return
+                }
 
-            if (!result.success || !result.data) {
-                console.error(`${logger} Pollinations API error after ${result.attemptsMade} attempts:`, result.error)
-                await ctx.runMutation(internal.batchGeneration.recordBatchItemResult, {
-                    batchJobId: args.batchJobId,
-                    itemIndex: args.itemIndex,
-                    success: false,
-                    errorMessage: result.error ?? "Generation failed after retries",
-                    // Include HTTP status code for client-side error detection (401=auth, 402=budget, 403=access)
-                    errorCode: result.lastStatus,
-                    retryCount: result.attemptsMade - 1,
-                })
-                return
+                const response = pollinationsAttempt.response
+                imageBuffer = Buffer.from(await response.arrayBuffer())
+                contentType = response.headers.get("content-type") || "image/jpeg"
             }
 
-            const response = result.data
-
-            // Get the image data
-            const imageBuffer = Buffer.from(await response.arrayBuffer())
-            const contentType = response.headers.get("content-type") || "image/jpeg"
-
             let uploadBuffer = imageBuffer
             let outputWidth = batchJob.generationParams.width ?? 1024
             let outputHeight = batchJob.generationParams.height ?? 1024
@@ -272,7 +421,13 @@ export const processBatchItem = internalAction({
                 visibility: batchJob.generationParams.private ? "unlisted" : "public",
             })
 
-            console.log(`${logger} Item ${args.itemIndex + 1} completed successfully${result.attemptsMade > 1 ? ` (after ${result.attemptsMade} attempts)` : ""}`)
+            console.log(
+                `${logger} Item ${args.itemIndex + 1} completed successfully${attempt > 1 ? ` (after ${attempt} attempts)` : ""}`
+            )
+            await ctx.runMutation(internal.batchGeneration.adjustAdaptiveDelay, {
+                batchJobId: args.batchJobId,
+                outcome: "success",
+            })
 
             // Record the result
             await ctx.runMutation(internal.batchGeneration.recordBatchItemResult, {
@@ -280,7 +435,7 @@ export const processBatchItem = internalAction({
                 itemIndex: args.itemIndex,
                 success: true,
                 imageId,
-                retryCount: result.attemptsMade > 1 ? result.attemptsMade - 1 : undefined,
+                retryCount: attempt > 1 ? attempt - 1 : undefined,
             })
 
             // Schedule background secondary asset processing for videos
@@ -302,6 +457,7 @@ export const processBatchItem = internalAction({
                 itemIndex: args.itemIndex,
                 success: false,
                 errorMessage: error instanceof Error ? error.message : "Unknown error",
+                retryCount: attempt > 1 ? attempt - 1 : undefined,
             })
         }
     },
diff --git a/convex/lib/batchGenerationState.test.ts b/convex/lib/batchGenerationState.test.ts
new file mode 100644
index 0000000..17c2d6c
--- /dev/null
+++ b/convex/lib/batchGenerationState.test.ts
@@ -0,0 +1,112 @@
+import "@testing-library/jest-dom/vitest"
+import { describe, expect, it } from "vitest"
+import {
+    buildRecordBatchItemResultTransition,
+    getResumeBatchDecision,
+} from "./batchGenerationState"
+
+describe("getResumeBatchDecision", () => {
+    it("blocks resume while in-flight work is still draining", () => {
+        expect(
+            getResumeBatchDecision({
+                currentIndex: 4,
+                totalCount: 10,
+                inFlightCount: 2,
+            })
+        ).toEqual({
+            canSchedule: false,
+            itemIndex: null,
+            nextInFlightCount: 2,
+            reason: "in_flight",
+        })
+    })
+
+    it("increments inFlightCount when a drained paused batch resumes", () => {
+        expect(
+            getResumeBatchDecision({
+                currentIndex: 4,
+                totalCount: 10,
+                inFlightCount: 0,
+            })
+        ).toEqual({
+            canSchedule: true,
+            itemIndex: 4,
+            nextInFlightCount: 1,
+            reason: null,
+        })
+    })
+
+    it("advances to the next unsettled index when the current index is already settled", () => {
+        expect(
+            getResumeBatchDecision({
+                currentIndex: 4,
+                totalCount: 10,
+                inFlightCount: 0,
+                settledItemIndexes: [0, 1, 2, 3, 4],
+            })
+        ).toEqual({
+            canSchedule: true,
+            itemIndex: 5,
+            nextInFlightCount: 1,
+            reason: null,
+        })
+    })
+})
+
+describe("buildRecordBatchItemResultTransition", () => {
+    it("does not increment totals twice for the same settled item", () => {
+        const transition = buildRecordBatchItemResultTransition(
+            {
+                completedCount: 3,
+                failedCount: 1,
+                imageIds: ["img-1", "img-2", "img-3"],
+                inFlightCount: 2,
+                settledItemIndexes: [0, 1, 2, 3],
+                status: "processing",
+                totalCount: 10,
+            },
+            {
+                itemIndex: 3,
+                success: true,
+                imageId: "img-duplicate",
+            }
+        )
+
+        expect(transition.isDuplicate).toBe(true)
+        expect(transition.shouldDelete).toBe(false)
+        expect(transition.updates).toEqual({
+            inFlightCount: 1,
+        })
+    })
+
+    it("records a first successful result and tracks the settled item index", () => {
+        const transition = buildRecordBatchItemResultTransition(
+            {
+                completedCount: 3,
+                failedCount: 1,
+                imageIds: ["img-1", "img-2", "img-3"],
+                inFlightCount: 2,
+                settledItemIndexes: [0, 1, 2, 3],
+                status: "pending",
+                totalCount: 10,
+            },
+            {
+                itemIndex: 4,
+                success: true,
+                imageId: "img-4",
+                retryCount: 2,
+            }
+        )
+
+        expect(transition.isDuplicate).toBe(false)
+        expect(transition.shouldDelete).toBe(false)
+        expect(transition.updates).toEqual({
+            completedCount: 4,
+            currentItemRetryCount: 2,
+            imageIds: ["img-1", "img-2", "img-3", "img-4"],
+            inFlightCount: 1,
+            settledItemIndexes: [0, 1, 2, 3, 4],
+            status: "processing",
+        })
+    })
+})
diff --git a/convex/lib/batchGenerationState.ts b/convex/lib/batchGenerationState.ts
new file mode 100644
index 0000000..56e510f
--- /dev/null
+++ b/convex/lib/batchGenerationState.ts
@@ -0,0 +1,121 @@
+export type BatchLifecycleStatus = "pending" | "processing" | "paused" | "completed" | "cancelled" | "failed"
+
+export type ResumeBatchDecision = {
+    canSchedule: boolean
+    itemIndex: number | null
+    nextInFlightCount: number
+    reason: "in_flight" | "no_remaining_work" | null
+}
+
+export function getResumeBatchDecision(state: {
+    currentIndex: number
+    totalCount: number
+    inFlightCount?: number
+    settledItemIndexes?: number[]
+}): ResumeBatchDecision {
+    const inFlightCount = state.inFlightCount ?? 0
+    if (inFlightCount > 0) {
+        return {
+            canSchedule: false,
+            itemIndex: null,
+            nextInFlightCount: inFlightCount,
+            reason: "in_flight",
+        }
+    }
+
+    const settledItemIndexes = state.settledItemIndexes ?? []
+    const itemIndex =
+        settledItemIndexes.includes(state.currentIndex)
+            ? state.currentIndex + 1
+            : state.currentIndex
+
+    if (itemIndex >= state.totalCount) {
+        return {
+            canSchedule: false,
+            itemIndex: null,
+            nextInFlightCount: inFlightCount,
+            reason: "no_remaining_work",
+        }
+    }
+
+    return {
+        canSchedule: true,
+        itemIndex,
+        nextInFlightCount: inFlightCount + 1,
+        reason: null,
+    }
+}
+
+export function buildRecordBatchItemResultTransition<ImageId>(state: {
+    completedCount: number
+    failedCount: number
+    imageIds: ImageId[]
+    inFlightCount?: number
+    settledItemIndexes?: number[]
+    status: BatchLifecycleStatus
+    totalCount: number
+}, result: {
+    itemIndex: number
+    success: boolean
+    imageId?: ImageId
+    errorCode?: number
+    retryCount?: number
+}) {
+    const inFlightCount = state.inFlightCount ?? 1
+    const nextInFlightCount = Math.max(0, inFlightCount - 1)
+    const settledItemIndexes = state.settledItemIndexes ?? []
+
+    if (settledItemIndexes.includes(result.itemIndex)) {
+        return {
+            isDuplicate: true,
+            shouldDelete: false,
+            updates: {
+                inFlightCount: nextInFlightCount,
+            },
+        }
+    }
+
+    const updates: {
+        completedCount?: number
+        currentItemRetryCount?: number
+        failedCount?: number
+        imageIds?: ImageId[]
+        inFlightCount: number
+        lastErrorCode?: number
+        settledItemIndexes: number[]
+        status?: Extract<BatchLifecycleStatus, "processing">
+    } = {
+        inFlightCount: nextInFlightCount,
+        settledItemIndexes: [...settledItemIndexes, result.itemIndex],
+    }
+
+    if (result.success) {
+        updates.completedCount = state.completedCount + 1
+        if (result.imageId !== undefined) {
+            updates.imageIds = [...state.imageIds, result.imageId]
+        }
+    } else {
+        updates.failedCount = state.failedCount + 1
+        if (result.errorCode !== undefined) {
+            updates.lastErrorCode = result.errorCode
+        }
+    }
+
+    if (result.retryCount !== undefined && result.retryCount > 0) {
+        updates.currentItemRetryCount = result.retryCount
+    }
+
+    const totalProcessed =
+        (updates.completedCount ?? state.completedCount) +
+        (updates.failedCount ?? state.failedCount)
+
+    if (totalProcessed < state.totalCount && state.status === "pending") {
+        updates.status = "processing"
+    }
+
+    return {
+        isDuplicate: false,
+        shouldDelete: totalProcessed >= state.totalCount,
+        updates,
+    }
+}
diff --git a/convex/schema.ts b/convex/schema.ts
index 4ca01fc..2ccd2ef 100644
--- a/convex/schema.ts
+++ b/convex/schema.ts
@@ -307,12 +307,15 @@ export default defineSchema({
          * This helps track requests that will still complete after pause/cancel.
          */
         inFlightCount: v.optional(v.number()),
+        /** Adaptive inter-item delay (ms) used to reduce provider retry pressure. */
+        adaptiveDelayMs: v.optional(v.number()),
         /** Shared generation parameters for all images */
         generationParams: v.any(),
         /** Pollinations API key for BYOP flow (passed from client, stored for processor actions) */
         apiKey: v.optional(v.string()),
         /** IDs of successfully generated images */
         imageIds: v.array(v.id("generatedImages")),
+        settledItemIndexes: v.optional(v.array(v.number())),
         /** Number of retry attempts for current item (for transient failures) */
         currentItemRetryCount: v.optional(v.number()),
         /** Last HTTP error code from Pollinations API (401=auth, 402=budget, 403=access) */
diff --git a/convex/singleGeneration.ts b/convex/singleGeneration.ts
index 4d9ac67..d69f818 100644
--- a/convex/singleGeneration.ts
+++ b/convex/singleGeneration.ts
@@ -14,7 +14,7 @@
 
 import { ConvexError, v } from "convex/values"
 import { internal } from "./_generated/api"
-import { action, internalAction, internalMutation, internalQuery, mutation, query } from "./_generated/server"
+import { internalAction, internalMutation, internalQuery, mutation, query } from "./_generated/server"
 import { analyzePromptForNSFW } from "./lib/nsfwDetection"
 import { canUserGenerate } from "./lib/subscription"
 
@@ -103,36 +103,6 @@ export const startGeneration = mutation({
     },
 })
 
-/**
- * Dispatch a persisted generation immediately via a normal action.
- * This avoids the scheduled-function concurrency bottleneck on the hot path.
- */
-export const dispatchGeneration = action({
-    args: {
-        generationId: v.id("pendingGenerations"),
-        apiKey: v.string(),
-    },
-    handler: async (ctx, args) => {
-        const identity = await ctx.auth.getUserIdentity()
-        if (!identity) {
-            throw new Error("Not authenticated")
-        }
-
-        const generation = await ctx.runQuery(internal.singleGeneration.getGenerationInternal, {
-            generationId: args.generationId,
-        })
-
-        if (!generation || generation.ownerId !== identity.subject) {
-            throw new Error("Generation not found")
-        }
-
-        await ctx.runAction(internal.singleGenerationProcessor.processGeneration, {
-            generationId: args.generationId,
-            apiKey: args.apiKey,
-        })
-    },
-})
-
 /**
  * Get the status of a pending generation.
  */
@@ -389,7 +359,7 @@ export const recoverPendingGeneration = internalAction({
             return
         }
 
-        await ctx.runAction(internal.singleGenerationProcessor.processGeneration, {
+        await ctx.runAction(internal.singleGenerationProcessor.processGenerationInternal, {
             generationId: args.generationId,
             apiKey: args.apiKey,
         })
diff --git a/convex/singleGenerationProcessor.ts b/convex/singleGenerationProcessor.ts
index 9d5a07a..4c2bd09 100644
--- a/convex/singleGenerationProcessor.ts
+++ b/convex/singleGenerationProcessor.ts
@@ -14,11 +14,13 @@
  */
 
 import { v } from "convex/values"
+import type { Id } from "./_generated/dataModel"
 import { internal } from "./_generated/api"
-import { internalAction } from "./_generated/server"
+import { action, internalAction, type ActionCtx } from "./_generated/server"
 import {
     buildPollinationsUrl,
     classifyApiError,
+    calculateBackoffDelay,
     cropDirtberryImageBuffer,
     getDirtberrySourceDimensions,
     isDirtberryModel,
@@ -26,7 +28,6 @@ import {
     generateThumbnailKey,
     uploadMediaWithThumbnail,
     deleteR2Objects,
-    fetchWithRetry,
     type RetryConfig,
 } from "./lib"
 
@@ -40,6 +41,19 @@ const POLLINATIONS_RETRY_CONFIG: RetryConfig = {
     baseDelayMs: 2000,
     maxDelayMs: 30000,
 }
+const POLLINATIONS_FETCH_TIMEOUT_MS = 45_000
+const MAX_POLLINATIONS_ATTEMPTS = POLLINATIONS_RETRY_CONFIG.maxRetries + 1
+
+/**
+ * Dev-only cost safety valve.
+ * When enabled, image requests complete with a tiny placeholder image
+ * instead of hitting Pollinations. This keeps UX flow intact while
+ * eliminating provider compute/bandwidth during local dev.
+ */
+const ENABLE_DEV_GENERATION_MOCK = process.env.CONVEX_ENABLE_DEV_GENERATION_MOCK === "true"
+const MOCK_PNG_BASE64 =
+    "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAwMCAO7k6xwAAAAASUVORK5CYII="
+const MOCK_IMAGE_BUFFER = Buffer.from(MOCK_PNG_BASE64, "base64")
 
 /**
  * Determine if an API error should be retried based on status and response.
@@ -58,34 +72,127 @@ function shouldRetryPollinationsError(status: number, errorText: string): boolea
     return classification.isRetryable
 }
 
-// ============================================================
-// Internal Action
-// ============================================================
+type ProcessGenerationArgs = {
+    generationId: Id<"pendingGenerations">
+    apiKey: string
+    attempt?: number
+}
 
-/**
- * Internal action to process a single image generation.
- * Receives the API key directly from the mutation (BYOP flow).
- * Includes retry logic with exponential backoff for transient failures.
- */
-export const processGeneration = internalAction({
-    args: {
-        generationId: v.id("pendingGenerations"),
-        /** The Pollinations API key passed from the client (BYOP flow) */
-        apiKey: v.string(),
-    },
-    handler: async (ctx, args) => {
-        const logger = "[SingleGeneration]"
+type PollinationsAttemptResult =
+    | { success: true; response: Response }
+    | {
+        success: false
+        errorMessage: string
+        statusCode?: number
+        retryable: boolean
+    }
+
+function formatApiErrorText(rawErrorText: string): string {
+    try {
+        const parseRecursive = (input: unknown): unknown => {
+            if (typeof input !== "string") return input
+            try {
+                const parsed = JSON.parse(input)
+                if (parsed && typeof parsed === "object") {
+                    for (const key in parsed) {
+                        ;(parsed as Record<string, unknown>)[key] = parseRecursive(
+                            (parsed as Record<string, unknown>)[key]
+                        )
+                    }
+                }
+                return parsed
+            } catch {
+                return input
+            }
+        }
+        const parsed = parseRecursive(rawErrorText)
+        return typeof parsed === "string" ? parsed : JSON.stringify(parsed, null, 2)
+    } catch {
+        return rawErrorText
+    }
+}
 
-        const getGeneration = async () =>
-            ctx.runQuery(internal.singleGeneration.getGenerationInternal, {
-                generationId: args.generationId,
-            })
+async function fetchPollinationsWithTimeout(
+    url: string,
+    apiKey: string,
+    timeoutMs: number,
+    logger: string
+): Promise<PollinationsAttemptResult> {
+    const controller = new AbortController()
+    const timeoutId = setTimeout(() => controller.abort(), timeoutMs)
+
+    try {
+        const response = await fetch(url, {
+            method: "GET",
+            headers: {
+                Authorization: `Bearer ${apiKey}`,
+            },
+            signal: controller.signal,
+        })
 
-        const isCancelled = async () => {
-            const current = await getGeneration()
-            return current?.status === "cancelled"
+        if (response.ok) {
+            return { success: true, response }
         }
 
+        const rawErrorText = await response.text()
+        const displayError = formatApiErrorText(rawErrorText)
+        const errorMessage = `HTTP ${response.status}: ${displayError}`
+        const retryable = shouldRetryPollinationsError(response.status, rawErrorText)
+
+        return {
+            success: false,
+            errorMessage,
+            statusCode: response.status,
+            retryable,
+        }
+    } catch (error) {
+        const isAbort = error instanceof Error && error.name === "AbortError"
+        const errorMessage = isAbort
+            ? `Pollinations request timed out after ${timeoutMs}ms`
+            : error instanceof Error
+              ? error.message
+              : "Unknown network error"
+        console.error(`${logger} Pollinations fetch failed: ${errorMessage}`)
+        return {
+            success: false,
+            errorMessage,
+            retryable: true,
+        }
+    } finally {
+        clearTimeout(timeoutId)
+    }
+}
+
+function shouldUseDevGenerationMock(isVideoRequest: boolean): boolean {
+    const deployment = process.env.CONVEX_DEPLOYMENT ?? ""
+    const isDevDeployment = deployment.startsWith("dev:")
+    return ENABLE_DEV_GENERATION_MOCK && isDevDeployment && !isVideoRequest
+}
+
+async function runGenerationProcessor(
+    ctx: ActionCtx,
+    args: ProcessGenerationArgs,
+    expectedOwnerId?: string
+): Promise<void> {
+    const logger = "[SingleGeneration]"
+    const attempt = args.attempt ?? 1
+
+    const getGeneration = async () =>
+        ctx.runQuery(internal.singleGeneration.getGenerationInternal, {
+            generationId: args.generationId,
+        })
+
+    const isCancelled = async () => {
+        const current = await getGeneration()
+        return current?.status === "cancelled"
+    }
+
+    const initialGeneration = await getGeneration()
+    if (!initialGeneration || (expectedOwnerId && initialGeneration.ownerId !== expectedOwnerId)) {
+        throw new Error("Generation not found")
+    }
+
+    if (attempt === 1) {
         const claimResult = await ctx.runMutation(internal.singleGeneration.claimPendingGeneration, {
             generationId: args.generationId,
         })
@@ -96,45 +203,62 @@ export const processGeneration = internalAction({
             )
             return
         }
-
-        // Get the generation record after the claim succeeds.
-        const generation = await getGeneration()
-        if (!generation) {
-            console.error(`${logger} Generation ${args.generationId} disappeared after claim`)
-            return
-        }
-
-        console.log(`${logger} Processing generation ${args.generationId}`)
-
-        // Use the API key passed from the client (BYOP flow)
-        const pollinationsApiKey = args.apiKey
-
-        // Validate API key
-        if (!pollinationsApiKey || pollinationsApiKey.trim().length === 0) {
-            console.error(`${logger} No Pollinations API key provided`)
-            await ctx.runMutation(internal.singleGeneration.updateGenerationStatus, {
-                generationId: args.generationId,
-                status: "failed",
-                errorMessage: "No Pollinations API key provided. Please connect to Pollinations first.",
-            })
+    } else if (initialGeneration.status !== "processing") {
+        console.log(
+            `${logger} Generation ${args.generationId} status is ${initialGeneration.status}, skipping retry attempt ${attempt}`
+        )
+        return
+    }
+
+    const generation = await getGeneration()
+    if (!generation) {
+        console.error(`${logger} Generation ${args.generationId} disappeared before processing`)
+        return
+    }
+
+    console.log(
+        `${logger} Processing generation ${args.generationId} (attempt ${attempt}/${MAX_POLLINATIONS_ATTEMPTS})`
+    )
+
+    const pollinationsApiKey = args.apiKey
+    if (!pollinationsApiKey || pollinationsApiKey.trim().length === 0) {
+        console.error(`${logger} No Pollinations API key provided`)
+        await ctx.runMutation(internal.singleGeneration.updateGenerationStatus, {
+            generationId: args.generationId,
+            status: "failed",
+            errorMessage: "No Pollinations API key provided. Please connect to Pollinations first.",
+        })
+        return
+    }
+
+    try {
+        const params = generation.generationParams
+        const shouldCropDirtberry = isDirtberryModel(params.model)
+        const dirtberrySourceDimensions = shouldCropDirtberry ? getDirtberrySourceDimensions() : null
+        const INT32_MAX = 2147483647
+        const rawSeed = params.seed ?? Math.floor(Math.random() * INT32_MAX)
+        const seed = Math.min(rawSeed, INT32_MAX)
+        const isVideoRequest =
+            params.duration !== undefined ||
+            params.audio !== undefined ||
+            params.aspectRatio !== undefined ||
+            params.lastFrameImage !== undefined
+
+        if (await isCancelled()) {
+            console.log(`${logger} Generation ${args.generationId} was cancelled before provider request`)
             return
         }
 
-        try {
-            const params = generation.generationParams
-            const shouldCropDirtberry = isDirtberryModel(params.model)
-            const dirtberrySourceDimensions = shouldCropDirtberry ? getDirtberrySourceDimensions() : null
-            // Pollinations API only accepts seeds up to int32 max (2147483647)
-            const INT32_MAX = 2147483647
-            const rawSeed = params.seed ?? Math.floor(Math.random() * INT32_MAX)
-            const seed = Math.min(rawSeed, INT32_MAX)
-
-            if (await isCancelled()) {
-                console.log(`${logger} Generation ${args.generationId} was cancelled before provider request`)
-                return
-            }
+        let imageBuffer: Buffer
+        let contentType: string
 
-            // Build the generation URL
+        if (shouldUseDevGenerationMock(isVideoRequest)) {
+            imageBuffer = Buffer.from(MOCK_IMAGE_BUFFER)
+            contentType = "image/png"
+            console.log(
+                `${logger} Dev mock enabled, using placeholder image for generation ${args.generationId}`
+            )
+        } else {
             const generationUrl = buildPollinationsUrl({
                 prompt: params.prompt,
                 negativePrompt: params.negativePrompt,
@@ -146,184 +270,228 @@ export const processGeneration = internalAction({
                 private: params.private,
                 safe: params.safe,
                 image: params.image,
-                // Video-specific parameters
                 duration: params.duration,
                 audio: params.audio,
                 aspectRatio: params.aspectRatio,
                 lastFrameImage: params.lastFrameImage,
-                quality: params.quality ?? "high"
+                quality: params.quality ?? "high",
             })
 
             console.log(`${logger} Calling Pollinations: ${generationUrl}`)
-
-            // Call Pollinations API with retry logic
-            const result = await fetchWithRetry(
+            const pollinationsAttempt = await fetchPollinationsWithTimeout(
                 generationUrl,
-                {
-                    method: "GET",
-                    headers: {
-                        Authorization: `Bearer ${pollinationsApiKey}`,
-                    },
-                },
-                shouldRetryPollinationsError,
-                POLLINATIONS_RETRY_CONFIG,
+                pollinationsApiKey,
+                POLLINATIONS_FETCH_TIMEOUT_MS,
                 logger
             )
 
-            // Update retry count in the database
-            if (result.attemptsMade > 1) {
-                await ctx.runMutation(internal.singleGeneration.updateGenerationStatus, {
-                    generationId: args.generationId,
-                    status: "processing",
-                    retryCount: result.attemptsMade - 1,
-                })
-            }
+            if (!pollinationsAttempt.success) {
+                const canRetry =
+                    pollinationsAttempt.retryable &&
+                    attempt < MAX_POLLINATIONS_ATTEMPTS &&
+                    !(await isCancelled())
+
+                if (canRetry) {
+                    const delayMs = Math.round(
+                        calculateBackoffDelay(
+                            attempt - 1,
+                            POLLINATIONS_RETRY_CONFIG.baseDelayMs,
+                            POLLINATIONS_RETRY_CONFIG.maxDelayMs
+                        )
+                    )
+
+                    await ctx.runMutation(internal.singleGeneration.updateGenerationStatus, {
+                        generationId: args.generationId,
+                        status: "processing",
+                        retryCount: attempt,
+                    })
+
+                    await ctx.scheduler.runAfter(
+                        delayMs,
+                        internal.singleGenerationProcessor.processGenerationInternal,
+                        {
+                            generationId: args.generationId,
+                            apiKey: pollinationsApiKey,
+                            attempt: attempt + 1,
+                        }
+                    )
+
+                    console.error(
+                        `${logger} Pollinations call failed (attempt ${attempt}/${MAX_POLLINATIONS_ATTEMPTS}), retrying in ${delayMs}ms: ${pollinationsAttempt.errorMessage}`
+                    )
+                    return
+                }
 
-            if (!result.success || !result.data) {
-                console.error(`${logger} Pollinations API error after ${result.attemptsMade} attempts:`, result.error)
                 await ctx.runMutation(internal.singleGeneration.updateGenerationStatus, {
                     generationId: args.generationId,
                     status: "failed",
-                    errorMessage: result.error ?? "Generation failed after retries",
-                    // Include HTTP status code for client-side error detection (401=auth, 402=budget, 403=access)
-                    errorCode: result.lastStatus,
-                    retryCount: result.attemptsMade - 1,
+                    errorMessage: pollinationsAttempt.errorMessage,
+                    errorCode: pollinationsAttempt.statusCode,
+                    retryCount: attempt > 1 ? attempt - 1 : undefined,
                 })
                 return
             }
 
-            const response = result.data
+            const response = pollinationsAttempt.response
+            imageBuffer = Buffer.from(await response.arrayBuffer())
+            contentType = response.headers.get("content-type") || "image/jpeg"
+        }
 
-            if (await isCancelled()) {
-                console.log(`${logger} Generation ${args.generationId} was cancelled after provider response`)
-                return
-            }
+        if (await isCancelled()) {
+            console.log(`${logger} Generation ${args.generationId} was cancelled after provider response`)
+            return
+        }
 
-            // Get the image data
-            const imageBuffer = Buffer.from(await response.arrayBuffer())
-            const contentType = response.headers.get("content-type") || "image/jpeg"
-
-            let uploadBuffer = imageBuffer
-            let outputWidth = params.width ?? 1024
-            let outputHeight = params.height ?? 1024
-
-            // Crop Dirtberry outputs before upload/persistence so every surface
-            // (canvas, gallery, downloads, lightbox) uses the same native asset.
-            if (shouldCropDirtberry) {
-                try {
-                    const cropped = await cropDirtberryImageBuffer(imageBuffer)
-                    uploadBuffer = Buffer.from(cropped.buffer)
-                    outputWidth = cropped.width
-                    outputHeight = cropped.height
-
-                    if (cropped.wasCropped) {
-                        console.log(
-                            `${logger} Applied Dirtberry crop (${cropped.processor}): ${cropped.inputWidth}x${cropped.inputHeight} -> ${cropped.width}x${cropped.height} (trim=${cropped.trimPixels}px)`
-                        )
-                    } else {
-                        console.log(
-                            `${logger} Dirtberry crop skipped: source=${cropped.inputWidth}x${cropped.inputHeight} (image too small to trim safely)`
-                        )
-                    }
-                } catch (cropError) {
-                    console.error(
-                        `${logger} Dirtberry crop failed, falling back to original image:`,
-                        cropError
+        let uploadBuffer = imageBuffer
+        let outputWidth = params.width ?? 1024
+        let outputHeight = params.height ?? 1024
+
+        if (shouldCropDirtberry) {
+            try {
+                const cropped = await cropDirtberryImageBuffer(imageBuffer)
+                uploadBuffer = Buffer.from(cropped.buffer)
+                outputWidth = cropped.width
+                outputHeight = cropped.height
+
+                if (cropped.wasCropped) {
+                    console.log(
+                        `${logger} Applied Dirtberry crop (${cropped.processor}): ${cropped.inputWidth}x${cropped.inputHeight} -> ${cropped.width}x${cropped.height} (trim=${cropped.trimPixels}px)`
+                    )
+                } else {
+                    console.log(
+                        `${logger} Dirtberry crop skipped: source=${cropped.inputWidth}x${cropped.inputHeight} (image too small to trim safely)`
                     )
                 }
+            } catch (cropError) {
+                console.error(
+                    `${logger} Dirtberry crop failed, falling back to original image:`,
+                    cropError
+                )
             }
+        }
 
-            // Upload to R2 (and thumbnail for images — videos defer secondary assets)
-            const r2Key = generateR2Key(generation.ownerId, contentType)
-            console.log(`${logger} Uploading to R2: ${r2Key}`)
+        const r2Key = generateR2Key(generation.ownerId, contentType)
+        console.log(`${logger} Uploading to R2: ${r2Key}`)
 
-            const { media: uploadResult, thumbnail: thumbnailResult } = await uploadMediaWithThumbnail(
-                uploadBuffer,
-                r2Key,
-                contentType
+        const { media: uploadResult, thumbnail: thumbnailResult } = await uploadMediaWithThumbnail(
+            uploadBuffer,
+            r2Key,
+            contentType
+        )
+
+        console.log(`${logger} Upload complete: ${uploadResult.url}`)
+        if (thumbnailResult) {
+            console.log(
+                `${logger} Thumbnail complete: ${thumbnailResult.url} (${thumbnailResult.sizeBytes} bytes)`
             )
+        } else if (!contentType.startsWith("video/")) {
+            console.log(`${logger} Thumbnail generation skipped or failed`)
+        }
 
-            console.log(`${logger} Upload complete: ${uploadResult.url}`)
-            if (thumbnailResult) {
-                console.log(`${logger} Thumbnail complete: ${thumbnailResult.url} (${thumbnailResult.sizeBytes} bytes)`)
-            } else if (!contentType.startsWith("video/")) {
-                console.log(`${logger} Thumbnail generation skipped or failed`)
+        if (await isCancelled()) {
+            console.log(
+                `${logger} Generation ${args.generationId} was cancelled before persistence, cleaning up R2 objects`
+            )
+            const keysToDelete = [r2Key]
+            if (thumbnailResult?.url) keysToDelete.push(generateThumbnailKey(r2Key))
+            try {
+                await deleteR2Objects(keysToDelete)
+                console.log(`${logger} R2 cleanup succeeded for generation ${args.generationId}`)
+            } catch (err) {
+                console.error(`${logger} R2 cleanup failed for generation ${args.generationId}:`, err)
             }
+            return
+        }
 
-            if (await isCancelled()) {
-                console.log(`${logger} Generation ${args.generationId} was cancelled before persistence, cleaning up R2 objects`)
-                // Best-effort R2 cleanup to avoid orphan objects
-                const keysToDelete = [r2Key]
-                if (thumbnailResult?.url) keysToDelete.push(generateThumbnailKey(r2Key))
-                try {
-                    await deleteR2Objects(keysToDelete)
-                    console.log(`${logger} R2 cleanup succeeded for generation ${args.generationId}`)
-                } catch (err) {
-                    console.error(`${logger} R2 cleanup failed for generation ${args.generationId}:`, err)
+        const imageId = await ctx.runMutation(internal.singleGeneration.storeGeneratedImage, {
+            ownerId: generation.ownerId,
+            r2Key,
+            url: uploadResult.url,
+            thumbnailR2Key: thumbnailResult?.url ? generateThumbnailKey(r2Key) : undefined,
+            thumbnailUrl: thumbnailResult?.url,
+            previewR2Key: undefined,
+            previewUrl: undefined,
+            prompt: params.prompt,
+            width: outputWidth,
+            height: outputHeight,
+            model: params.model ?? "flux",
+            seed,
+            contentType,
+            sizeBytes: uploadResult.sizeBytes,
+            generationParams: shouldCropDirtberry
+                ? {
+                    ...params,
+                    seed,
+                    width: outputWidth,
+                    height: outputHeight,
                 }
-                return
-            }
+                : {
+                    ...params,
+                    seed,
+                },
+            visibility: params.private ? "unlisted" : "public",
+        })
 
-            // Store the image in Convex database — immediately, without waiting for secondary assets
-            const imageId = await ctx.runMutation(internal.singleGeneration.storeGeneratedImage, {
-                ownerId: generation.ownerId,
-                r2Key,
-                url: uploadResult.url,
-                thumbnailR2Key: thumbnailResult?.url ? generateThumbnailKey(r2Key) : undefined,
-                thumbnailUrl: thumbnailResult?.url,
-                // Preview is always deferred for videos; not applicable for images
-                previewR2Key: undefined,
-                previewUrl: undefined,
-                prompt: params.prompt,
-                width: outputWidth,
-                height: outputHeight,
-                model: params.model ?? "flux",
-                seed,
-                contentType,
-                sizeBytes: uploadResult.sizeBytes,
-                generationParams: shouldCropDirtberry
-                    ? {
-                        ...params,
-                        seed,
-                        width: outputWidth,
-                        height: outputHeight,
-                    }
-                    : {
-                        ...params,
-                        seed,
-                    },
-                visibility: params.private ? "unlisted" : "public",
-            })
+        console.log(`${logger} Generation ${args.generationId} completed successfully`)
 
-            console.log(`${logger} Generation ${args.generationId} completed successfully`)
+        await ctx.runMutation(internal.singleGeneration.updateGenerationStatus, {
+            generationId: args.generationId,
+            status: "completed",
+            imageId,
+            retryCount: attempt > 1 ? attempt - 1 : undefined,
+        })
 
-            // Update generation status to completed — user sees result NOW
-            await ctx.runMutation(internal.singleGeneration.updateGenerationStatus, {
-                generationId: args.generationId,
-                status: "completed",
+        if (contentType.startsWith("video/")) {
+            await ctx.scheduler.runAfter(0, internal.secondaryAssetsProcessor.processSecondaryAssets, {
                 imageId,
-                retryCount: result.attemptsMade > 1 ? result.attemptsMade - 1 : undefined,
+                videoUrl: uploadResult.url,
+                r2Key,
             })
+            console.log(`${logger} Scheduled background secondary asset processing for ${imageId}`)
+        }
+    } catch (error) {
+        console.error(`${logger} Error processing generation:`, error)
+        await ctx.runMutation(internal.singleGeneration.updateGenerationStatus, {
+            generationId: args.generationId,
+            status: "failed",
+            errorMessage: error instanceof Error ? error.message : "Unknown error",
+            retryCount: attempt > 1 ? attempt - 1 : undefined,
+        })
+    }
+}
 
-            // Schedule background secondary asset processing for videos
-            // (thumbnail extraction + preview transcode). This runs AFTER the
-            // generation is already "completed" — failures here are non-fatal.
-            if (contentType.startsWith("video/")) {
-                await ctx.scheduler.runAfter(0, internal.secondaryAssetsProcessor.processSecondaryAssets, {
-                    imageId,
-                    videoUrl: uploadResult.url,
-                    r2Key,
-                })
-                console.log(`${logger} Scheduled background secondary asset processing for ${imageId}`)
-            }
+// ============================================================
+// Public + Internal Actions
+// ============================================================
 
-        } catch (error) {
-            console.error(`${logger} Error processing generation:`, error)
-            await ctx.runMutation(internal.singleGeneration.updateGenerationStatus, {
-                generationId: args.generationId,
-                status: "failed",
-                errorMessage: error instanceof Error ? error.message : "Unknown error",
-            })
+/**
+ * Public entrypoint used by clients to immediately start processing
+ * a persisted generation without an intermediate wrapper action.
+ */
+export const processGeneration = action({
+    args: {
+        generationId: v.id("pendingGenerations"),
+        apiKey: v.string(),
+    },
+    handler: async (ctx, args) => {
+        const identity = await ctx.auth.getUserIdentity()
+        if (!identity) {
+            throw new Error("Not authenticated")
         }
+        await runGenerationProcessor(ctx, args, identity.subject)
+    },
+})
+
+/**
+ * Internal entrypoint used for scheduled recovery/retries.
+ */
+export const processGenerationInternal = internalAction({
+    args: {
+        generationId: v.id("pendingGenerations"),
+        apiKey: v.string(),
+        attempt: v.optional(v.number()),
+    },
+    handler: async (ctx, args) => {
+        await runGenerationProcessor(ctx, args)
     },
 })
diff --git a/hooks/queries/use-generate-image.test.tsx b/hooks/queries/use-generate-image.test.tsx
index 2cbfa8d..acf2756 100644
--- a/hooks/queries/use-generate-image.test.tsx
+++ b/hooks/queries/use-generate-image.test.tsx
@@ -32,7 +32,7 @@ const mockGeneratedImagesById = new Map<string, {
 // Mock mutation functions
 const mockStartGeneration = vi.fn()
 const mockCancelGeneration = vi.fn()
-const mockDispatchGeneration = vi.fn()
+const mockProcessGeneration = vi.fn()
 
 // Map mutation references to their mock implementations
 const mutationMocks: Record<string, ReturnType<typeof vi.fn>> = {
@@ -74,8 +74,8 @@ vi.mock("convex/react", () => ({
         }),
     }),
     useAction: (actionRef: string) => {
-        if (actionRef === "singleGeneration.dispatchGeneration") {
-            return mockDispatchGeneration
+        if (actionRef === "singleGenerationProcessor.processGeneration") {
+            return mockProcessGeneration
         }
         return vi.fn()
     },
@@ -119,11 +119,13 @@ vi.mock("@/convex/_generated/api", () => ({
     api: {
         singleGeneration: {
             startGeneration: "singleGeneration.startGeneration",
-            dispatchGeneration: "singleGeneration.dispatchGeneration",
             getGenerationStatus: "singleGeneration.getGenerationStatus",
             getGenerationsStatus: "singleGeneration.getGenerationsStatus",
             cancelGeneration: "singleGeneration.cancelGeneration",
         },
+            singleGenerationProcessor: {
+                processGeneration: "singleGenerationProcessor.processGeneration",
+            },
         generatedImages: {
             getById: "generatedImages.getById",
         },
@@ -142,8 +144,8 @@ describe("useGenerateImage", () => {
         mockGeneratedImagesById.clear()
         mockStartGeneration.mockReset()
         mockCancelGeneration.mockReset()
-        mockDispatchGeneration.mockReset()
-        mockDispatchGeneration.mockResolvedValue(undefined)
+        mockProcessGeneration.mockReset()
+        mockProcessGeneration.mockResolvedValue(undefined)
         mockAuthorize.mockReset()
     })
 
@@ -178,7 +180,7 @@ describe("useGenerateImage", () => {
             },
             apiKey: mockApiKey,
         })
-        expect(mockDispatchGeneration).toHaveBeenCalledWith({
+        expect(mockProcessGeneration).toHaveBeenCalledWith({
             generationId,
             apiKey: mockApiKey,
         })
diff --git a/hooks/queries/use-generate-image.ts b/hooks/queries/use-generate-image.ts
index c964d63..09f6e5b 100644
--- a/hooks/queries/use-generate-image.ts
+++ b/hooks/queries/use-generate-image.ts
@@ -158,7 +158,7 @@ export function useGenerateImage(
 ): UseGenerateImageReturn {
     const startGeneration = useMutation(api.singleGeneration.startGeneration)
     const cancelGeneration = useMutation(api.singleGeneration.cancelGeneration)
-    const dispatchGeneration = useAction(api.singleGeneration.dispatchGeneration)
+    const processGeneration = useAction(api.singleGenerationProcessor.processGeneration)
 
     // Get API key from BYOP context
     const apiKey = usePollenApiKey()
@@ -205,7 +205,7 @@ export function useGenerateImage(
             }
 
             void Promise.resolve(
-                dispatchGeneration({
+                processGeneration({
                     generationId: next.generationId,
                     apiKey: next.apiKey,
                 })
@@ -220,7 +220,7 @@ export function useGenerateImage(
         }
 
         flushNext()
-    }, [dispatchGeneration])
+    }, [processGeneration])
 
     const enqueueGenerationDispatch = React.useCallback(
         (entry: PendingDispatchEntry) => {
diff --git a/hooks/use-batch-mode.ts b/hooks/use-batch-mode.ts
index d08d319..73f30ee 100644
--- a/hooks/use-batch-mode.ts
+++ b/hooks/use-batch-mode.ts
@@ -303,6 +303,7 @@ export function useBatchMode({
                 await resumeBatch(effectiveBatchId)
             } catch (error) {
                 console.error("Failed to resume batch:", error)
+                showErrorToast(error as Error)
             }
         }
     }, [effectiveBatchId, resumeBatch])

From 7327a5a6e00e307e7553ff51c16eccc59242ff91 Mon Sep 17 00:00:00 2001
From: Simplereally <joshmackus@protonmail.com>
Date: Wed, 11 Mar 2026 23:40:32 +1100
Subject: [PATCH 2/4] test: update model inventory expectations

---
 lib/config/models.test.ts | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/lib/config/models.test.ts b/lib/config/models.test.ts
index 7a190f0..4320371 100644
--- a/lib/config/models.test.ts
+++ b/lib/config/models.test.ts
@@ -187,17 +187,18 @@ describe("Model Registry", () => {
 
     describe("Model Lists", () => {
         it("should have all model IDs", () => {
-            expect(ALL_MODEL_IDS.length).toBe(20)
+            expect(ALL_MODEL_IDS.length).toBe(IMAGE_MODEL_IDS.length + VIDEO_MODEL_IDS.length)
         })
 
         it("should have correct image model IDs", () => {
-            expect(IMAGE_MODEL_IDS.length).toBe(15)
+            expect(IMAGE_MODEL_IDS.length).toBe(16)
             expect(IMAGE_MODEL_IDS).toContain("zimage")
             expect(IMAGE_MODEL_IDS).toContain("gptimage")
             expect(IMAGE_MODEL_IDS).toContain("flux")
             expect(IMAGE_MODEL_IDS).toContain("klein")
             expect(IMAGE_MODEL_IDS).toContain("imagen-4")
             expect(IMAGE_MODEL_IDS).toContain("grok-imagine")
+            expect(IMAGE_MODEL_IDS).toContain("dirtberry")
             expect(IMAGE_MODEL_IDS).toContain("flux-2-dev")
             expect(IMAGE_MODEL_IDS).not.toContain("veo")
         })

From 4db6f312916f8e43d1f117d31a0cd2736f4ae8df Mon Sep 17 00:00:00 2001
From: Simplereally <joshmackus@protonmail.com>
Date: Wed, 11 Mar 2026 23:56:03 +1100
Subject: [PATCH 3/4] fix: refactor pollinations fetch utilities and improve
 batch resume logic

- Move `fetchPollinationsWithTimeout` and `formatApiErrorText` to pollinations lib
- Add optional `retryKind` parameter to `fetchPollinationsWithTimeout`
- Export `PollinationsAttemptResult` and `RetryKind` types from lib index
- Fix batch resume to skip all settled indexes, not just current
- Update `resumeBatchJob` to use `itemIndex` from resume decision
- Add test coverage for sparse settled indexes in batch generation
---
 convex/batchGeneration.ts                 |   5 +-
 convex/batchProcessor.ts                  | 117 +---------------------
 convex/lib/batchGenerationState.test.ts   |  16 +++
 convex/lib/batchGenerationState.ts        |   9 +-
 convex/lib/index.ts                       |   4 +
 convex/lib/pollinations.ts                |  97 ++++++++++++++++++
 convex/singleGenerationProcessor.ts       | 104 +------------------
 hooks/queries/use-generate-image.test.tsx |   6 +-
 hooks/use-batch-mode.ts                   |  22 +++-
 9 files changed, 151 insertions(+), 229 deletions(-)

diff --git a/convex/batchGeneration.ts b/convex/batchGeneration.ts
index 83ee651..51fc8e9 100644
--- a/convex/batchGeneration.ts
+++ b/convex/batchGeneration.ts
@@ -715,15 +715,16 @@ export const resumeBatchJob = mutation({
         // Update status to processing
         await ctx.db.patch(args.batchJobId, {
             status: "processing",
+            currentIndex: resumeDecision.itemIndex ?? batchJob.currentIndex,
             inFlightCount: resumeDecision.nextInFlightCount,
             updatedAt: Date.now(),
         })
 
         // Schedule the next item for processing
-        if (batchJob.currentIndex < batchJob.totalCount) {
+        if (resumeDecision.itemIndex !== null) {
             await ctx.scheduler.runAfter(0, internal.batchProcessor.processBatchItem, {
                 batchJobId: args.batchJobId,
-                itemIndex: batchJob.currentIndex,
+                itemIndex: resumeDecision.itemIndex,
             })
         }
 
diff --git a/convex/batchProcessor.ts b/convex/batchProcessor.ts
index 85bd5ce..6e6a20d 100644
--- a/convex/batchProcessor.ts
+++ b/convex/batchProcessor.ts
@@ -19,9 +19,9 @@ import { internal } from "./_generated/api"
 import { internalAction } from "./_generated/server"
 import {
     buildPollinationsUrl,
-    classifyApiError,
     calculateBackoffDelay,
     cropDirtberryImageBuffer,
+    fetchPollinationsWithTimeout,
     getDirtberrySourceDimensions,
     isDirtberryModel,
     generateR2Key,
@@ -47,118 +47,6 @@ const MOCK_PNG_BASE64 =
     "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAwMCAO7k6xwAAAAASUVORK5CYII="
 const MOCK_IMAGE_BUFFER = Buffer.from(MOCK_PNG_BASE64, "base64")
 
-/**
- * Determine if an API error should be retried based on status and response.
- * 
- * Retryable:
- * - 429 (Rate limit)
- * - 5xx (Server errors)
- * - Known transient errors (e.g., "No active flux servers available")
- * 
- * Non-retryable:
- * - 400 (Bad request - invalid parameters)
- * - 401, 403 (Auth errors)
- */
-function shouldRetryPollinationsError(status: number, errorText: string): boolean {
-    const classification = classifyApiError(status, errorText)
-    return classification.isRetryable
-}
-
-type RetryKind = "throttle" | "transient_error" | "permanent"
-
-type PollinationsAttemptResult =
-    | { success: true; response: Response }
-    | {
-        success: false
-        errorMessage: string
-        statusCode?: number
-        retryable: boolean
-        retryKind: RetryKind
-    }
-
-function formatApiErrorText(rawErrorText: string): string {
-    try {
-        const parseRecursive = (input: unknown): unknown => {
-            if (typeof input !== "string") return input
-            try {
-                const parsed = JSON.parse(input)
-                if (parsed && typeof parsed === "object") {
-                    for (const key in parsed) {
-                        ;(parsed as Record<string, unknown>)[key] = parseRecursive(
-                            (parsed as Record<string, unknown>)[key]
-                        )
-                    }
-                }
-                return parsed
-            } catch {
-                return input
-            }
-        }
-        const parsed = parseRecursive(rawErrorText)
-        return typeof parsed === "string" ? parsed : JSON.stringify(parsed, null, 2)
-    } catch {
-        return rawErrorText
-    }
-}
-
-async function fetchPollinationsWithTimeout(
-    url: string,
-    apiKey: string,
-    timeoutMs: number,
-    logger: string
-): Promise<PollinationsAttemptResult> {
-    const controller = new AbortController()
-    const timeoutId = setTimeout(() => controller.abort(), timeoutMs)
-
-    try {
-        const response = await fetch(url, {
-            method: "GET",
-            headers: {
-                Authorization: `Bearer ${apiKey}`,
-            },
-            signal: controller.signal,
-        })
-
-        if (response.ok) {
-            return { success: true, response }
-        }
-
-        const rawErrorText = await response.text()
-        const displayError = formatApiErrorText(rawErrorText)
-        const errorMessage = `HTTP ${response.status}: ${displayError}`
-        const retryable = shouldRetryPollinationsError(response.status, rawErrorText)
-        const retryKind: RetryKind = !retryable
-            ? "permanent"
-            : response.status === 429
-              ? "throttle"
-              : "transient_error"
-
-        return {
-            success: false,
-            errorMessage,
-            statusCode: response.status,
-            retryable,
-            retryKind,
-        }
-    } catch (error) {
-        const isAbort = error instanceof Error && error.name === "AbortError"
-        const errorMessage = isAbort
-            ? `Pollinations request timed out after ${timeoutMs}ms`
-            : error instanceof Error
-              ? error.message
-              : "Unknown network error"
-        console.error(`${logger} Pollinations fetch failed: ${errorMessage}`)
-        return {
-            success: false,
-            errorMessage,
-            retryable: true,
-            retryKind: "transient_error",
-        }
-    } finally {
-        clearTimeout(timeoutId)
-    }
-}
-
 function shouldUseDevGenerationMock(isVideoRequest: boolean): boolean {
     const deployment = process.env.CONVEX_DEPLOYMENT ?? ""
     const isDevDeployment = deployment.startsWith("dev:")
@@ -295,7 +183,8 @@ export const processBatchItem = internalAction({
                     generationUrl,
                     pollinationsApiKey,
                     POLLINATIONS_FETCH_TIMEOUT_MS,
-                    `${logger} Item ${args.itemIndex + 1}`
+                    `${logger} Item ${args.itemIndex + 1}`,
+                    true
                 )
 
                 if (!pollinationsAttempt.success) {
diff --git a/convex/lib/batchGenerationState.test.ts b/convex/lib/batchGenerationState.test.ts
index 17c2d6c..109e3e4 100644
--- a/convex/lib/batchGenerationState.test.ts
+++ b/convex/lib/batchGenerationState.test.ts
@@ -51,6 +51,22 @@ describe("getResumeBatchDecision", () => {
             reason: null,
         })
     })
+
+    it("handles sparse settled indexes correctly", () => {
+        expect(
+            getResumeBatchDecision({
+                currentIndex: 0,
+                totalCount: 10,
+                inFlightCount: 0,
+                settledItemIndexes: [0, 2],
+            })
+        ).toEqual({
+            canSchedule: true,
+            itemIndex: 1,
+            nextInFlightCount: 1,
+            reason: null,
+        })
+    })
 })
 
 describe("buildRecordBatchItemResultTransition", () => {
diff --git a/convex/lib/batchGenerationState.ts b/convex/lib/batchGenerationState.ts
index 56e510f..4134306 100644
--- a/convex/lib/batchGenerationState.ts
+++ b/convex/lib/batchGenerationState.ts
@@ -24,10 +24,11 @@ export function getResumeBatchDecision(state: {
     }
 
     const settledItemIndexes = state.settledItemIndexes ?? []
-    const itemIndex =
-        settledItemIndexes.includes(state.currentIndex)
-            ? state.currentIndex + 1
-            : state.currentIndex
+    let itemIndex = state.currentIndex
+
+    while (settledItemIndexes.includes(itemIndex) && itemIndex < state.totalCount) {
+        itemIndex += 1
+    }
 
     if (itemIndex >= state.totalCount) {
         return {
diff --git a/convex/lib/index.ts b/convex/lib/index.ts
index 03eafaa..3d50831 100644
--- a/convex/lib/index.ts
+++ b/convex/lib/index.ts
@@ -15,10 +15,14 @@ export {
     buildPollinationsUrl,
     classifyHttpError,
     classifyApiError,
+    fetchPollinationsWithTimeout,
+    formatApiErrorText,
     isFluxModelUnavailable,
     matchNonRetryablePattern,
     NON_RETRYABLE_ERROR_PATTERNS,
+    type PollinationsAttemptResult,
     type PollinationsUrlParams,
+    type RetryKind,
     type ErrorClassification,
 } from "./pollinations"
 
diff --git a/convex/lib/pollinations.ts b/convex/lib/pollinations.ts
index cea34a4..4ce32b7 100644
--- a/convex/lib/pollinations.ts
+++ b/convex/lib/pollinations.ts
@@ -50,6 +50,18 @@ export interface ErrorClassification {
     reason: string
 }
 
+export type RetryKind = "throttle" | "transient_error" | "permanent"
+
+export type PollinationsAttemptResult =
+    | { success: true; response: Response }
+    | {
+        success: false
+        errorMessage: string
+        statusCode?: number
+        retryable: boolean
+        retryKind?: RetryKind
+    }
+
 // ============================================================
 // URL Building
 // ============================================================
@@ -319,3 +331,88 @@ export function classifyApiError(status: number, errorText: string): ErrorClassi
     // 3. Fall back to HTTP status classification
     return classifyHttpError(status)
 }
+
+export function formatApiErrorText(rawErrorText: string): string {
+    try {
+        const parseRecursive = (input: unknown): unknown => {
+            if (typeof input !== "string") return input
+            try {
+                const parsed = JSON.parse(input)
+                if (parsed && typeof parsed === "object") {
+                    for (const key in parsed) {
+                        ;(parsed as Record<string, unknown>)[key] = parseRecursive(
+                            (parsed as Record<string, unknown>)[key]
+                        )
+                    }
+                }
+                return parsed
+            } catch {
+                return input
+            }
+        }
+
+        const parsed = parseRecursive(rawErrorText)
+        return typeof parsed === "string" ? parsed : JSON.stringify(parsed, null, 2)
+    } catch {
+        return rawErrorText
+    }
+}
+
+export async function fetchPollinationsWithTimeout(
+    url: string,
+    apiKey: string,
+    timeoutMs: number,
+    logger: string,
+    includeRetryKind = false
+): Promise<PollinationsAttemptResult> {
+    const controller = new AbortController()
+    const timeoutId = setTimeout(() => controller.abort(), timeoutMs)
+
+    try {
+        const response = await fetch(url, {
+            method: "GET",
+            headers: {
+                Authorization: `Bearer ${apiKey}`,
+            },
+            signal: controller.signal,
+        })
+
+        if (response.ok) {
+            return { success: true, response }
+        }
+
+        const rawErrorText = await response.text()
+        const displayError = formatApiErrorText(rawErrorText)
+        const errorMessage = `HTTP ${response.status}: ${displayError}`
+        const retryable = classifyApiError(response.status, rawErrorText).isRetryable
+        const retryKind: RetryKind = !retryable
+            ? "permanent"
+            : response.status === 429
+              ? "throttle"
+              : "transient_error"
+
+        return {
+            success: false,
+            errorMessage,
+            statusCode: response.status,
+            retryable,
+            ...(includeRetryKind ? { retryKind } : {}),
+        }
+    } catch (error) {
+        const isAbort = error instanceof Error && error.name === "AbortError"
+        const errorMessage = isAbort
+            ? `Pollinations request timed out after ${timeoutMs}ms`
+            : error instanceof Error
+              ? error.message
+              : "Unknown network error"
+        console.error(`${logger} Pollinations fetch failed: ${errorMessage}`)
+        return {
+            success: false,
+            errorMessage,
+            retryable: true,
+            ...(includeRetryKind ? { retryKind: "transient_error" as const } : {}),
+        }
+    } finally {
+        clearTimeout(timeoutId)
+    }
+}
diff --git a/convex/singleGenerationProcessor.ts b/convex/singleGenerationProcessor.ts
index 4c2bd09..38018a4 100644
--- a/convex/singleGenerationProcessor.ts
+++ b/convex/singleGenerationProcessor.ts
@@ -19,9 +19,9 @@ import { internal } from "./_generated/api"
 import { action, internalAction, type ActionCtx } from "./_generated/server"
 import {
     buildPollinationsUrl,
-    classifyApiError,
     calculateBackoffDelay,
     cropDirtberryImageBuffer,
+    fetchPollinationsWithTimeout,
     getDirtberrySourceDimensions,
     isDirtberryModel,
     generateR2Key,
@@ -55,114 +55,12 @@ const MOCK_PNG_BASE64 =
     "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAwMCAO7k6xwAAAAASUVORK5CYII="
 const MOCK_IMAGE_BUFFER = Buffer.from(MOCK_PNG_BASE64, "base64")
 
-/**
- * Determine if an API error should be retried based on status and response.
- * 
- * Retryable:
- * - 429 (Rate limit)
- * - 5xx (Server errors)
- * - Known transient errors (e.g., "No active flux servers available")
- * 
- * Non-retryable:
- * - 400 (Bad request - invalid parameters)
- * - 401, 403 (Auth errors)
- */
-function shouldRetryPollinationsError(status: number, errorText: string): boolean {
-    const classification = classifyApiError(status, errorText)
-    return classification.isRetryable
-}
-
 type ProcessGenerationArgs = {
     generationId: Id<"pendingGenerations">
     apiKey: string
     attempt?: number
 }
 
-type PollinationsAttemptResult =
-    | { success: true; response: Response }
-    | {
-        success: false
-        errorMessage: string
-        statusCode?: number
-        retryable: boolean
-    }
-
-function formatApiErrorText(rawErrorText: string): string {
-    try {
-        const parseRecursive = (input: unknown): unknown => {
-            if (typeof input !== "string") return input
-            try {
-                const parsed = JSON.parse(input)
-                if (parsed && typeof parsed === "object") {
-                    for (const key in parsed) {
-                        ;(parsed as Record<string, unknown>)[key] = parseRecursive(
-                            (parsed as Record<string, unknown>)[key]
-                        )
-                    }
-                }
-                return parsed
-            } catch {
-                return input
-            }
-        }
-        const parsed = parseRecursive(rawErrorText)
-        return typeof parsed === "string" ? parsed : JSON.stringify(parsed, null, 2)
-    } catch {
-        return rawErrorText
-    }
-}
-
-async function fetchPollinationsWithTimeout(
-    url: string,
-    apiKey: string,
-    timeoutMs: number,
-    logger: string
-): Promise<PollinationsAttemptResult> {
-    const controller = new AbortController()
-    const timeoutId = setTimeout(() => controller.abort(), timeoutMs)
-
-    try {
-        const response = await fetch(url, {
-            method: "GET",
-            headers: {
-                Authorization: `Bearer ${apiKey}`,
-            },
-            signal: controller.signal,
-        })
-
-        if (response.ok) {
-            return { success: true, response }
-        }
-
-        const rawErrorText = await response.text()
-        const displayError = formatApiErrorText(rawErrorText)
-        const errorMessage = `HTTP ${response.status}: ${displayError}`
-        const retryable = shouldRetryPollinationsError(response.status, rawErrorText)
-
-        return {
-            success: false,
-            errorMessage,
-            statusCode: response.status,
-            retryable,
-        }
-    } catch (error) {
-        const isAbort = error instanceof Error && error.name === "AbortError"
-        const errorMessage = isAbort
-            ? `Pollinations request timed out after ${timeoutMs}ms`
-            : error instanceof Error
-              ? error.message
-              : "Unknown network error"
-        console.error(`${logger} Pollinations fetch failed: ${errorMessage}`)
-        return {
-            success: false,
-            errorMessage,
-            retryable: true,
-        }
-    } finally {
-        clearTimeout(timeoutId)
-    }
-}
-
 function shouldUseDevGenerationMock(isVideoRequest: boolean): boolean {
     const deployment = process.env.CONVEX_DEPLOYMENT ?? ""
     const isDevDeployment = deployment.startsWith("dev:")
diff --git a/hooks/queries/use-generate-image.test.tsx b/hooks/queries/use-generate-image.test.tsx
index acf2756..cd1eb83 100644
--- a/hooks/queries/use-generate-image.test.tsx
+++ b/hooks/queries/use-generate-image.test.tsx
@@ -123,9 +123,9 @@ vi.mock("@/convex/_generated/api", () => ({
             getGenerationsStatus: "singleGeneration.getGenerationsStatus",
             cancelGeneration: "singleGeneration.cancelGeneration",
         },
-            singleGenerationProcessor: {
-                processGeneration: "singleGenerationProcessor.processGeneration",
-            },
+        singleGenerationProcessor: {
+            processGeneration: "singleGenerationProcessor.processGeneration",
+        },
         generatedImages: {
             getById: "generatedImages.getById",
         },
diff --git a/hooks/use-batch-mode.ts b/hooks/use-batch-mode.ts
index 73f30ee..25e3607 100644
--- a/hooks/use-batch-mode.ts
+++ b/hooks/use-batch-mode.ts
@@ -50,6 +50,21 @@ function getConvexErrorCode(err: unknown): string | undefined {
     return undefined
 }
 
+function getDisplayErrorMessage(err: unknown): string {
+    if (err instanceof ConvexError) {
+        const data = err.data as { message?: string } | string
+        if (typeof data === "object" && data !== null && "message" in data && typeof data.message === "string") {
+            return data.message
+        }
+    }
+
+    if (err instanceof Error) {
+        return err.message
+    }
+
+    return String(err)
+}
+
 /**
  * Return type for useBatchMode hook
  */
@@ -260,7 +275,7 @@ export function useBatchMode({
             if (errorCode === ClientErrorCodeConst.TRIAL_EXPIRED) {
                 onTrialExpired?.()
             } else {
-                showErrorToast(error as Error)
+                showErrorToast(new Error(getDisplayErrorMessage(error)))
             }
         }
     }, [startBatch, onTrialExpired, apiKey, authorize])
@@ -302,8 +317,9 @@ export function useBatchMode({
             try {
                 await resumeBatch(effectiveBatchId)
             } catch (error) {
-                console.error("Failed to resume batch:", error)
-                showErrorToast(error as Error)
+                const message = getDisplayErrorMessage(error)
+                console.error("Failed to resume batch:", error, { message })
+                showErrorToast(new Error(message))
             }
         }
     }, [effectiveBatchId, resumeBatch])

From 76ea7ddcc2bf4a5f5128dee9c9d5e108c4a74f18 Mon Sep 17 00:00:00 2001
From: Simplereally <joshmackus@protonmail.com>
Date: Thu, 12 Mar 2026 00:06:18 +1100
Subject: [PATCH 4/4] test: update free tier generation limit expectation from
 9 to 10

---
 components/studio/upgrade-modal.test.tsx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/components/studio/upgrade-modal.test.tsx b/components/studio/upgrade-modal.test.tsx
index 77dbbaf..089fdf1 100644
--- a/components/studio/upgrade-modal.test.tsx
+++ b/components/studio/upgrade-modal.test.tsx
@@ -57,7 +57,7 @@ describe("UpgradeModal", () => {
 		expect(
 			screen.getByText("generations / day"),
 		).toBeInTheDocument();
-		expect(screen.getByText("9")).toBeInTheDocument();
+		expect(screen.getByText("10")).toBeInTheDocument();
 		expect(screen.getByText("AI models included")).toBeInTheDocument();
 		expect(screen.getByText("Daily")).toBeInTheDocument();
 	});