@goodandready/dsh-image-gen 0.11.30 → 0.11.32

package/lib/client.js

@@ -2698,7 +2698,7 @@ window.__ModuleLoader__.load({
 
       'f.geminiModel': 'Gemini Model ID',
       'f.geminiModelHint': 'Google Gemini image generation model identifier.',
-      'p.geminiModel': 'gemini-2.0-flash-exp-image-generation',
+      'p.geminiModel': 'gemini-3.1-flash-image',
       'f.geminiKeyEnv': 'Gemini Key Reference',
       'f.geminiKeyEnvHint': 'Credential reference holding Google Gemini API key.',
       'p.geminiKeyEnv': 'GEMINI_API_KEY',
@@ -2977,7 +2977,7 @@ window.__ModuleLoader__.load({
 
       'f.geminiModel': 'Gemini 模型 ID',
       'f.geminiModelHint': 'Google Gemini 图像生成模型标识符。',
-      'p.geminiModel': 'gemini-2.0-flash-exp-image-generation',
+      'p.geminiModel': 'gemini-3.1-flash-image',
       'f.geminiKeyEnv': 'Gemini 凭证名称',
       'f.geminiKeyEnvHint': '存储 Google Gemini 密钥的凭证名称。',
       'p.geminiKeyEnv': 'GEMINI_API_KEY',

package/lib/config-schema.js

@@ -177,7 +177,7 @@ export const Config = z.object({
   geminiModel: z
     .string()
     .description('Google Gemini image generation model identifier.')
-    .default('gemini-2.0-flash-exp-image-generation')
+    .default('gemini-3.1-flash-image')
     .volatile(),
   geminiKeyEnv: z
     .string()

package/lib/cost-meter.js

@@ -1,9 +1,10 @@
 // lib/cost-meter.js
-// Integration with dsh-cost-meter, rate card, and daily budget enforcer (#167)
+// Integration with dsh-cost-meter, rate card, and daily budget enforcer (#167, #353, #355)
 
 import { homedir } from 'node:os'
 import { join } from 'node:path'
-import { readFileSync, writeFileSync, mkdirSync } from 'node:fs'
+import { readFileSync, writeFileSync, mkdirSync, renameSync, unlinkSync } from 'node:fs'
+import { randomBytes } from 'node:crypto'
 import { enforceSecurePermissions } from './security.js'
 
 /**
@@ -53,6 +54,27 @@ export const RATE_CARD = {
   },
 }
 
+/** Active in-flight budget reservations for serialized concurrency (#355) */
+const activeReservations = new Map()
+
+/**
+ * Returns total currently active in-flight spend reservations in USD.
+ */
+export function getTotalActiveReservations() {
+  let total = 0
+  for (const amount of activeReservations.values()) {
+    total += Number(amount) || 0
+  }
+  return +total.toFixed(4)
+}
+
+/**
+ * Clears all active in-flight reservations (for testing / session resets).
+ */
+export function clearSpendReservations() {
+  activeReservations.clear()
+}
+
 /**
  * Calculates estimated USD cost for a generation request.
  */
@@ -94,6 +116,7 @@ export function loadDailySpend() {
 
 /**
  * Records an image generation expense.
+ * Uses atomic sibling write + rename to guarantee crash-safe persistence (#355).
  */
 export function recordSpend(usdAmount, { ctx, meta = {} } = {}) {
   const amount = Number(usdAmount) || 0
@@ -106,8 +129,11 @@ export function recordSpend(usdAmount, { ctx, meta = {} } = {}) {
   current.lastUpdated = new Date().toISOString()
 
   try {
-    mkdirSync(join(filePath, '..'), { recursive: true })
-    writeFileSync(filePath, JSON.stringify(current, null, 2), 'utf8')
+    const dir = join(filePath, '..')
+    mkdirSync(dir, { recursive: true })
+    const tmpFile = `${filePath}.${randomBytes(6).toString('hex')}.tmp`
+    writeFileSync(tmpFile, JSON.stringify(current, null, 2), { encoding: 'utf8', mode: 0o600 })
+    renameSync(tmpFile, filePath)
     enforceSecurePermissions(filePath)
   } catch (err) {
     // Non-fatal write failure
@@ -130,7 +156,7 @@ export function recordSpend(usdAmount, { ctx, meta = {} } = {}) {
 }
 
 /**
- * Asserts that the generation does not exceed daily budget.
+ * Asserts that the generation does not exceed daily budget, accounting for active in-flight reservations (#353, #355).
  * @throws {Error} If daily budget is exceeded.
  */
 export function assertBudgetAvailable(estimatedCost, dailyBudgetUsd) {
@@ -139,11 +165,52 @@ export function assertBudgetAvailable(estimatedCost, dailyBudgetUsd) {
 
   const cost = Number(estimatedCost) || 0
   const current = loadDailySpend()
-  const projected = +(current.totalSpendUsd + cost).toFixed(4)
+  const reserved = getTotalActiveReservations()
+  const projected = +(current.totalSpendUsd + reserved + cost).toFixed(4)
   if (projected > budget) {
     throw new Error(
-      `Daily image generation budget exceeded: current spend $${current.totalSpendUsd.toFixed(2)} + estimated $${cost.toFixed(2)} exceeds limit $${budget.toFixed(2)} (Settings → Image generation → dailyBudgetUsd)`
+      `Daily image generation budget exceeded: current spend $${current.totalSpendUsd.toFixed(2)} + reserved $${reserved.toFixed(2)} + estimated $${cost.toFixed(2)} exceeds limit $${budget.toFixed(2)} (Settings → Image generation → dailyBudgetUsd)`
     )
   }
   return true
 }
+
+/**
+ * Reserves estimated budget for an in-flight generation attempt (#353, #355).
+ * Returns a settlement handle with .commit(actualCost, opts) and .release().
+ *
+ * @param {number} estimatedCost
+ * @param {number} dailyBudgetUsd
+ * @returns {{ id: string, cost: number, commit: Function, release: Function }}
+ */
+export function reserveSpend(estimatedCost, dailyBudgetUsd) {
+  const budget = Number(dailyBudgetUsd) || 0
+  const cost = Number(estimatedCost) || 0
+
+  if (budget > 0 && cost > 0) {
+    assertBudgetAvailable(cost, budget)
+  }
+
+  const id = `res_${Date.now()}_${randomBytes(4).toString('hex')}`
+  if (budget > 0 && cost > 0) {
+    activeReservations.set(id, cost)
+  }
+
+  let settled = false
+  return {
+    id,
+    cost,
+    commit(actualCost, opts) {
+      if (settled) return
+      settled = true
+      activeReservations.delete(id)
+      const effective = actualCost !== undefined ? Number(actualCost) : cost
+      return recordSpend(effective, opts)
+    },
+    release() {
+      if (settled) return
+      settled = true
+      activeReservations.delete(id)
+    },
+  }
+}

package/lib/frontend-assets.js

@@ -359,6 +359,61 @@ export function decodeHtmlEntities(str) {
     .replace(/&/gi, '&')
 }
 
+/**
+ * Escapes JSX-sensitive characters in SVG markup so text nodes and unquoted
+ * curly braces cannot be interpreted as JavaScript expressions in TSX export (#406).
+ * Replaces unquoted `{` and `}` outside attribute values with `{` and `}`.
+ * @param {string} content
+ * @returns {string}
+ */
+export function escapeJsxText(content) {
+  if (!content || typeof content !== 'string') return ''
+  let result = ''
+  let inTag = false
+  let quote = null
+
+  for (let i = 0; i < content.length; i++) {
+    const ch = content[i]
+
+    if (!inTag) {
+      if (ch === '<') {
+        inTag = true
+        quote = null
+        result += ch
+      } else if (ch === '{') {
+        result += '&#123;'
+      } else if (ch === '}') {
+        result += '&#125;'
+      } else {
+        result += ch
+      }
+    } else {
+      if (quote) {
+        if (ch === quote) {
+          quote = null
+        }
+        result += ch
+      } else {
+        if (ch === '"' || ch === "'") {
+          quote = ch
+          result += ch
+        } else if (ch === '>') {
+          inTag = false
+          result += ch
+        } else if (ch === '{') {
+          result += '&#123;'
+        } else if (ch === '}') {
+          result += '&#125;'
+        } else {
+          result += ch
+        }
+      }
+    }
+  }
+
+  return result
+}
+
 /**
  * Issue #176: optimize_vector_svg
  * Cleans, sanitizes, and minifies SVG content, normalizes viewBox, and exports React TSX component.
@@ -463,6 +518,8 @@ export function optimizeSvgContent(svgString, options = {}) {
     .replace(/stroke-linejoin=/g, 'strokeLinejoin=')
     .replace(/stroke-miterlimit=/g, 'strokeMiterlimit=')
 
+  jsxBody = escapeJsxText(jsxBody)
+
   const reactTsx = `import React from 'react';
 
 export interface ${componentName}Props extends React.SVGProps<SVGSVGElement> {

package/lib/generation-helpers.js

@@ -2,6 +2,7 @@
 // Extracted execution and prompt/caching helpers for generate_image tool (#349).
 
 import path from 'node:path'
+import { createHash } from 'node:crypto'
 import { mkdir, writeFile } from 'node:fs/promises'
 import {
   computeGenerationHash,
@@ -152,6 +153,11 @@ export async function saveGeneratedImageArtifact({
   slugify,
   estimatedCost,
   totalCount,
+  recordSpend: shouldRecordSpend = true,
+  source,
+  mask,
+  resolvedFaceRef,
+  resolvedRefImage,
 }) {
   const targetFormat = format || (args.output_format || cfg.defaultFormat)
   const formatted = await ensureImageFormat(gen.bytes, targetFormat, { fallbackMime: gen.mediaType })
@@ -204,7 +210,11 @@ export async function saveGeneratedImageArtifact({
 
   const effectiveModel = provider === 'custom'
     ? (cfg.customModel || cfg.model || 'dall-e-3')
-    : (cfg.model || cfg.customModel)
+    : (cfg.model || cfg.customModel || 'default')
+
+  const sourceBytes = source && source.bytes ? source.bytes : (args.image || args.source_image)
+  const maskBytes = mask && mask.bytes ? mask.bytes : (args.mask_image || args.mask)
+  const refBytes = (resolvedRefImage && resolvedRefImage.bytes) || (resolvedFaceRef && resolvedFaceRef.bytes) || args.reference_images || args.reference_image
 
   const cacheHash = computeGenerationHash({
     provider,
@@ -221,9 +231,9 @@ export async function saveGeneratedImageArtifact({
     negativePrompt: args.negative_prompt || cfg.negativePrompt,
     quality: args.quality,
     strength: args.strength,
-    sourceImage: args.image || args.source_image,
-    maskImage: args.mask_image || args.mask,
-    reference: args.reference_images || args.reference_image,
+    sourceImage: sourceBytes,
+    maskImage: maskBytes,
+    reference: refBytes,
   })
 
   // #170: Store in content-addressed disk cache
@@ -234,19 +244,32 @@ export async function saveGeneratedImageArtifact({
       width: gen.width || attachment.width,
       height: gen.height || attachment.height,
       seed: gen.seed,
-      meta: { prompt: promptArg, provider, model: cfg.model || cfg.customModel, cost: gen.cost },
+      meta: { prompt: promptArg, provider, model: effectiveModel, cost: gen.cost },
     })
   }
+
+  const sourceHash = (source && source.bytes) ? createHash('sha256').update(source.bytes).digest('hex') : undefined
+  const maskHash = (mask && mask.bytes) ? createHash('sha256').update(mask.bytes).digest('hex') : undefined
+  const refHash = (resolvedRefImage && resolvedRefImage.bytes)
+    ? createHash('sha256').update(resolvedRefImage.bytes).digest('hex')
+    : ((resolvedFaceRef && resolvedFaceRef.bytes) ? createHash('sha256').update(resolvedFaceRef.bytes).digest('hex') : undefined)
+
   const entry = {
     path: filePath,
     prompt: promptArg,
     provider,
-    model: cfg.model,
+    model: effectiveModel,
     size,
     format,
     aspectRatio: args.aspect_ratio || cfg.defaultAspectRatio,
     seed: gen.seed,
     cacheHash,
+    sourceHash,
+    maskHash,
+    refHash,
+    quality: args.quality,
+    style: args.style,
+    strength: args.strength,
     thumbnailUrl: localUrl,
     width: gen.width || attachment.width,
     height: gen.height || attachment.height,
@@ -262,11 +285,13 @@ export async function saveGeneratedImageArtifact({
     await appendHistoryEntry(entry, { pruneDays: cfg.pruneDays, historyLimit })
   }
 
-  // #167: Record spend in cost meter
-  recordSpend(gen.cost || (estimatedCost / totalCount), {
-    ctx,
-    meta: { provider, model: cfg.model || cfg.customModel, prompt: promptArg, seed: gen.seed },
-  })
+  // #167: Record spend in cost meter (unless caller already committed attempt spend)
+  if (shouldRecordSpend !== false) {
+    recordSpend(gen.cost || (estimatedCost / totalCount), {
+      ctx,
+      meta: { provider, model: cfg.model || cfg.customModel, prompt: promptArg, seed: gen.seed },
+    })
+  }
 
   return {
     path: filePath,

package/lib/history.js

@@ -41,6 +41,22 @@ export async function findCachedByPrompt(entries, prompt, criteria = {}) {
   if (!prompt || !Array.isArray(entries)) return undefined
   return entries.find((e) => {
     if (e.prompt !== prompt) return false
+    if (criteria.cacheHash && e.cacheHash && criteria.cacheHash !== e.cacheHash) return false
+    if (criteria.provider && e.provider && criteria.provider.toLowerCase() !== e.provider.toLowerCase()) return false
+    if (criteria.model && e.model && criteria.model.toLowerCase() !== e.model.toLowerCase()) return false
+    if (criteria.sourceHash !== undefined && e.sourceHash !== undefined && criteria.sourceHash !== e.sourceHash) return false
+    if (criteria.sourceHash && !e.sourceHash) return false
+    if (!criteria.sourceHash && e.sourceHash) return false
+    if (criteria.maskHash !== undefined && e.maskHash !== undefined && criteria.maskHash !== e.maskHash) return false
+    if (criteria.maskHash && !e.maskHash) return false
+    if (!criteria.maskHash && e.maskHash) return false
+    if (criteria.refHash !== undefined && e.refHash !== undefined && criteria.refHash !== e.refHash) return false
+    if (criteria.refHash && !e.refHash) return false
+    if (!criteria.refHash && e.refHash) return false
+    if (criteria.quality !== undefined && e.quality !== undefined && criteria.quality !== e.quality) return false
+    if (criteria.style !== undefined && e.style !== undefined && criteria.style !== e.style) return false
+    if (criteria.strength !== undefined && e.strength !== undefined && criteria.strength !== e.strength) return false
+
     if (criteria.format) {
       const entryFmt = (e.format || (e.mediaType || '').replace('image/', '')).toLowerCase().replace('jpeg', 'jpg')
       const targetFmt = String(criteria.format).toLowerCase().replace('jpeg', 'jpg')
@@ -58,6 +74,22 @@ export async function findCached(entries, seed, prompt, criteria = {}) {
   if (seed === undefined || !Array.isArray(entries)) return undefined
   return entries.find((e) => {
     if (e.seed !== seed || e.prompt !== prompt) return false
+    if (criteria.cacheHash && e.cacheHash && criteria.cacheHash !== e.cacheHash) return false
+    if (criteria.provider && e.provider && criteria.provider.toLowerCase() !== e.provider.toLowerCase()) return false
+    if (criteria.model && e.model && criteria.model.toLowerCase() !== e.model.toLowerCase()) return false
+    if (criteria.sourceHash !== undefined && e.sourceHash !== undefined && criteria.sourceHash !== e.sourceHash) return false
+    if (criteria.sourceHash && !e.sourceHash) return false
+    if (!criteria.sourceHash && e.sourceHash) return false
+    if (criteria.maskHash !== undefined && e.maskHash !== undefined && criteria.maskHash !== e.maskHash) return false
+    if (criteria.maskHash && !e.maskHash) return false
+    if (!criteria.maskHash && e.maskHash) return false
+    if (criteria.refHash !== undefined && e.refHash !== undefined && criteria.refHash !== e.refHash) return false
+    if (criteria.refHash && !e.refHash) return false
+    if (!criteria.refHash && e.refHash) return false
+    if (criteria.quality !== undefined && e.quality !== undefined && criteria.quality !== e.quality) return false
+    if (criteria.style !== undefined && e.style !== undefined && criteria.style !== e.style) return false
+    if (criteria.strength !== undefined && e.strength !== undefined && criteria.strength !== e.strength) return false
+
     if (criteria.format) {
       const entryFmt = (e.format || (e.mediaType || '').replace('image/', '')).toLowerCase().replace('jpeg', 'jpg')
       const targetFmt = String(criteria.format).toLowerCase().replace('jpeg', 'jpg')

package/lib/provider-utils.js

@@ -191,10 +191,13 @@ export function computeGenerationHash({
 } = {}) {
   const hashContent = (item) => {
     if (!item) return ''
-    if (Buffer.isBuffer(item)) return createHash('sha256').update(item).digest('hex').slice(0, 16)
+    if (Buffer.isBuffer(item)) return createHash('sha256').update(item).digest('hex')
     if (typeof item === 'object' && item.bytes) {
       const b = Buffer.isBuffer(item.bytes) ? item.bytes : Buffer.from(item.bytes)
-      return createHash('sha256').update(b).digest('hex').slice(0, 16)
+      return createHash('sha256').update(b).digest('hex')
+    }
+    if (Array.isArray(item)) {
+      return item.map(hashContent).filter(Boolean).join(',')
     }
     return String(item).trim()
   }

package/lib/providers/backends/fal.js

@@ -35,6 +35,11 @@ export function createFalGenerator(deps, job) {
         body.strength = strength
       }
     } else if (job.faceReference && (job.faceReference.bytes || job.faceReference.url)) {
+      // #375: Enforce model capability check before dispatching face identity anchors
+      const isFaceCapable = /instant-id|face-to-many|pulid|ip-adapter|face/i.test(targetModel)
+      if (!isFaceCapable) {
+        throw new Error(`Model "${targetModel}" on FAL does not support face identity anchors. Use a face-capable model (e.g. fal-ai/flux-lora/face-to-many, fal-ai/instant-id) or ComfyUI with FaceID workflow.`)
+      }
       const refDataUri = job.faceReference.bytes
         ? `data:${job.faceReference.mediaType || 'image/png'};base64,${Buffer.from(job.faceReference.bytes).toString('base64')}`
         : job.faceReference.url
@@ -45,6 +50,11 @@ export function createFalGenerator(deps, job) {
         body.reference_weight = job.faceStrength
       }
     } else if (job.referenceImage && (job.referenceImage.bytes || job.referenceImage.url)) {
+      // #375: Enforce model capability check before dispatching style reference anchors
+      const isRefCapable = /instant-id|face-to-many|pulid|ip-adapter|reference|redux/i.test(targetModel)
+      if (!isRefCapable) {
+        throw new Error(`Model "${targetModel}" on FAL does not support reference image anchors. Use a reference-capable model (e.g. fal-ai/flux/dev/redux, fal-ai/ip-adapter) or ComfyUI.`)
+      }
       const refDataUri = job.referenceImage.bytes
         ? `data:${job.referenceImage.mediaType || 'image/png'};base64,${Buffer.from(job.referenceImage.bytes).toString('base64')}`
         : job.referenceImage.url

package/lib/providers/backends/gemini.js

@@ -15,10 +15,10 @@ export function createGeminiGenerator(deps, job) {
 
   async function gemini(seedArg = seed, promptArg = prompt) {
     const key = await resolveKey(cfg.geminiKeyEnv)
-    let model = cfg.geminiModel || 'gemini-2.0-flash-exp-image-generation'
-    // #364: Transparently migrate deprecated Imagen 3/4 IDs to Gemini multimodal model
-    if (model.startsWith('imagen-') || model === 'imagen-3.0-generate-002') {
-      model = 'gemini-2.0-flash-exp-image-generation'
+    let model = cfg.geminiModel || 'gemini-3.1-flash-image'
+    // #364: Transparently migrate deprecated Imagen 3/4 IDs and preview 2.0 to current Gemini multimodal model
+    if (model.startsWith('imagen-') || model.startsWith('gemini-2.0-flash-exp')) {
+      model = 'gemini-3.1-flash-image'
     }
 
     const timeoutSignal = typeof AbortSignal !== 'undefined' && AbortSignal.timeout
@@ -53,14 +53,22 @@ export function createGeminiGenerator(deps, job) {
     }
     parts.push({ text: promptArg })
 
-    // Build unified imageConfig without quality/style overwrite collisions (#364)
+    // #364: Google Gemini ImageConfig only accepts aspectRatio and imageSize.
+    // Unofficial/deprecated fields like imageQuality or imageStyle must not be passed.
     const imageConfig = {}
-    if (aspectRatio) imageConfig.aspectRatio = aspectRatio
-    if (quality && quality !== 'auto') imageConfig.imageQuality = quality
-    if (style && style !== 'none') imageConfig.imageStyle = style
+    if (aspectRatio) {
+      const ratioMap = {
+        square: '1:1',
+        portrait_4_3: '3:4',
+        landscape_4_3: '4:3',
+        portrait_16_9: '9:16',
+        landscape_16_9: '16:9',
+      }
+      imageConfig.aspectRatio = ratioMap[aspectRatio] || aspectRatio
+    }
 
     const generationConfig = {
-      responseModalities: ['IMAGE'],
+      responseModalities: ['TEXT', 'IMAGE'],
       ...(Object.keys(imageConfig).length > 0 ? { imageConfig } : {}),
     }
 

package/lib/providers/backends/local.js

@@ -43,6 +43,13 @@ export function createLocalGenerator(deps, job) {
     }
 
     if (kind === 'a1111') {
+      // #375: Local A1111 txt2img/img2img lacks identity adapters
+      if (job.faceReference) {
+        throw new Error('Local A1111 does not support facial identity references (FaceID) — use ComfyUI (IP-Adapter/InstantID) or FAL')
+      }
+      if (job.referenceImage) {
+        throw new Error('Local A1111 does not support visual style reference anchors — use ComfyUI (IP-Adapter) or FAL')
+      }
       if (typeof onProgress === 'function') {
         onProgress({ stage: 'Generating...', progress: undefined })
       }
@@ -88,6 +95,17 @@ export function createLocalGenerator(deps, job) {
     }
 
     // ComfyUI: submit via /prompt, poll /history/{prompt_id} until completed.
+    if (job.faceReference || job.referenceImage) {
+      const wf = cfg.comfyWorkflowJson || ''
+      const hasFace = wf.includes('face_image') || wf.includes('ApplyIPAdapter') || wf.includes('InstantID') || wf.includes('FaceID')
+      const hasRef = wf.includes('reference_image') || wf.includes('ApplyIPAdapter') || wf.includes('StyleModelApply')
+      if (job.faceReference && !hasFace) {
+        throw new Error('ComfyUI requires a custom workflow with FaceID or IP-Adapter nodes to use facial identity anchors.')
+      }
+      if (job.referenceImage && !hasRef) {
+        throw new Error('ComfyUI requires a custom workflow with reference or IP-Adapter nodes to use style reference anchors.')
+      }
+    }
     const promptId = `dsh-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`
     let workflowGraph
     if (cfg.comfyWorkflowJson) {

package/lib/providers.js

@@ -779,7 +779,8 @@ export async function testProviderConnection(deps, providerId) {
     if (p === 'gemini') {
       const key = await resolveKey(cfg?.geminiKeyEnv || 'GEMINI_API_KEY')
       if (!key) return { ok: false, state: 'not_configured', latencyMs: 0, message: 'Google Gemini API key not configured' }
-      const model = cfg?.geminiModel || 'gemini-2.0-flash-exp-image-generation'
+      let model = cfg?.geminiModel || 'gemini-3.1-flash-image'
+      if (model.startsWith('imagen-') || model.startsWith('gemini-2.0-flash-exp')) model = 'gemini-3.1-flash-image'
       let res
       try {
         res = await fetchImpl(`https://generativelanguage.googleapis.com/v1beta/models/${model}?key=${encodeURIComponent(key)}`, {

package/lib/quality-gate.js

@@ -1,5 +1,5 @@
 // lib/quality-gate.js
-// Automatic Quality Gate and Silent Re-roll Engine (#166)
+// Automatic Quality Gate and Silent Re-roll Engine (#166, #353)
 
 import { estimateSharpnessAndVariance } from './providers.js'
 
@@ -97,7 +97,24 @@ export async function executeWithQualityGate(generateFn, {
   const attempts = enabled ? Math.max(1, maxRerolls + 1) : 1
 
   for (let attempt = 0; attempt < attempts; attempt++) {
-    lastGenerated = await generateFn(currentSeed)
+    try {
+      lastGenerated = await generateFn(currentSeed)
+    } catch (err) {
+      // #353: If a subsequent re-roll exceeds budget, abort further retries and preserve the initial output
+      if (lastGenerated && (err.message?.includes('budget exceeded') || err.message?.includes('Daily image generation budget'))) {
+        logger(`Quality gate re-roll halted by budget limit: ${err.message}`)
+        return {
+          generated: lastGenerated,
+          qualityReport: {
+            ...lastReport,
+            rerolls,
+            exhausted: true,
+            budgetExceeded: true,
+          },
+        }
+      }
+      throw err
+    }
 
     if (!enabled) {
       return {

package/lib/tools/character-sheet.js

@@ -15,7 +15,7 @@ import {
   
 } from '../providers.js'
 import { resolveFallbackChain, executeWithFallback } from '../fallback-router.js'
-import { assertBudgetAvailable, calculateGenerationCost, recordSpend } from '../cost-meter.js'
+import { assertBudgetAvailable, calculateGenerationCost, reserveSpend, recordSpend } from '../cost-meter.js'
 import { renderToolOutput } from '../attachment-helper.js'
 import {
   CHARACTER_SHEET_LAYOUTS,
@@ -152,15 +152,17 @@ export function registerCharacterSheetTools(ctx, deps) {
             size: cfg.defaultSize || '1024x1024',
             count: 1,
           })
-          assertBudgetAvailable(estimatedCost, cfg.dailyBudgetUsd)
-
-          const gen = await executeWithFallback(
-            providers,
-            fallbackChain,
-            seed,
-            sheetPlan.prompt,
-            { logger: ctx.logger },
-          )
+          const reservation = reserveSpend(estimatedCost, cfg.dailyBudgetUsd)
+          let gen
+          let committed = false
+          try {
+            gen = await executeWithFallback(
+              providers,
+              fallbackChain,
+              seed,
+              sheetPlan.prompt,
+              { logger: ctx.logger },
+            )
 
           const usedProvider = gen._fallback?.providerUsed || provider
           const finalBytes = gen.bytes
@@ -196,10 +198,11 @@ export function registerCharacterSheetTools(ctx, deps) {
           }
 
           const effectiveCost = Number(gen.cost) || estimatedCost
-          recordSpend(effectiveCost, {
+          reservation.commit(effectiveCost, {
             ctx,
             meta: { provider: usedProvider, model: cfg.model || cfg.customModel, prompt: sheetPlan.prompt, seed },
           })
+          committed = true
 
           const dualOutput = buildDualOutputMarkdown({
             action: 'generated',
@@ -232,6 +235,11 @@ export function registerCharacterSheetTools(ctx, deps) {
           }
 
           return toLosslessJson(response)
+          } finally {
+            if (!committed) {
+              reservation.release()
+            }
+          }
         },
       })
     )

package/lib/tools/diagram.js

@@ -13,7 +13,7 @@ import {
 } from '../providers.js'
 import { buildDualOutputMarkdown } from '../resolve-image.js'
 import { resolveFallbackChain, executeWithFallback } from '../fallback-router.js'
-import { assertBudgetAvailable, calculateGenerationCost, recordSpend } from '../cost-meter.js'
+import { assertBudgetAvailable, calculateGenerationCost, reserveSpend, recordSpend } from '../cost-meter.js'
 import { renderToolOutput } from '../attachment-helper.js'
 import {
   DIAGRAM_3D_STYLES,
@@ -148,15 +148,17 @@ export function registerDiagramTools(ctx, deps) {
             size: cfg.defaultSize || '1024x1024',
             count: 1,
           })
-          assertBudgetAvailable(estimatedCost, cfg.dailyBudgetUsd)
-
-          const gen = await executeWithFallback(
-            providers,
-            fallbackChain,
-            seed,
-            plan.prompt,
-            { logger: ctx.logger },
-          )
+          const reservation = reserveSpend(estimatedCost, cfg.dailyBudgetUsd)
+          let gen
+          let committed = false
+          try {
+            gen = await executeWithFallback(
+              providers,
+              fallbackChain,
+              seed,
+              plan.prompt,
+              { logger: ctx.logger },
+            )
 
           const usedProvider = gen._fallback?.providerUsed || provider
           const finalBytes = gen.bytes
@@ -192,10 +194,11 @@ export function registerDiagramTools(ctx, deps) {
           }
 
           const effectiveCost = Number(gen.cost) || estimatedCost
-          recordSpend(effectiveCost, {
+          reservation.commit(effectiveCost, {
             ctx,
             meta: { provider: usedProvider, model: cfg.model || cfg.customModel, prompt: plan.prompt, seed },
           })
+          committed = true
 
           const dualOutput = buildDualOutputMarkdown({
             action: 'generated',
@@ -227,6 +230,11 @@ export function registerDiagramTools(ctx, deps) {
           }
 
           return toLosslessJson(response)
+          } finally {
+            if (!committed) {
+              reservation.release()
+            }
+          }
         },
       })
     )