@goodandready/dsh-image-gen 0.11.30 → 0.11.31

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/generation-helpers.js

@@ -152,6 +152,7 @@ export async function saveGeneratedImageArtifact({
   slugify,
   estimatedCost,
   totalCount,
+  recordSpend: shouldRecordSpend = true,
 }) {
   const targetFormat = format || (args.output_format || cfg.defaultFormat)
   const formatted = await ensureImageFormat(gen.bytes, targetFormat, { fallbackMime: gen.mediaType })
@@ -262,11 +263,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/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,20 @@ 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
+          try {
+            gen = await executeWithFallback(
+              providers,
+              fallbackChain,
+              seed,
+              sheetPlan.prompt,
+              { logger: ctx.logger },
+            )
+          } catch (err) {
+            reservation.release()
+            throw err
+          }
 
           const usedProvider = gen._fallback?.providerUsed || provider
           const finalBytes = gen.bytes
@@ -196,7 +201,7 @@ 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 },
           })

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,20 @@ 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
+          try {
+            gen = await executeWithFallback(
+              providers,
+              fallbackChain,
+              seed,
+              plan.prompt,
+              { logger: ctx.logger },
+            )
+          } catch (err) {
+            reservation.release()
+            throw err
+          }
 
           const usedProvider = gen._fallback?.providerUsed || provider
           const finalBytes = gen.bytes
@@ -192,7 +197,7 @@ 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 },
           })

package/lib/tools/generation.js

@@ -15,7 +15,7 @@ import {
 } from '../providers.js'
 import { buildDualOutputMarkdown } from '../resolve-image.js'
 import { executeWithQualityGate } from '../quality-gate.js'
-import { calculateGenerationCost, assertBudgetAvailable } from '../cost-meter.js'
+import { calculateGenerationCost, assertBudgetAvailable, reserveSpend } from '../cost-meter.js'
 import { trackAndAssertLoopGuard } from '../loop-guard.js'
 import { getCachedGeneration } from '../generation-cache.js'
 import { resolveFallbackChain, executeWithFallback } from '../fallback-router.js'
@@ -378,14 +378,25 @@ export function registerGenerationTools(ctx, deps, options = {}) {
           async (s, p) => {
             let totalAttempts = 0
             let accumulatedCost = 0
-            // #353: Pipeline evaluates raw gen.bytes first; saves artifact ONCE after acceptance
+            // #353, #355: Pipeline reserves budget per attempt, evaluates raw gen.bytes, and commits spend per attempt
+            const perAttemptCost = Number(estimatedCost / totalCount) || 0.02
             const rawGenerate = async (seedVal) => {
+              const reservation = reserveSpend(perAttemptCost, cfg.dailyBudgetUsd)
               totalAttempts++
-              const gen = await providers[k](seedVal, p)
-              guard(gen)
-              const attemptCost = Number(gen.cost) || estimatedCost
-              accumulatedCost += attemptCost
-              return gen
+              try {
+                const gen = await providers[k](seedVal, p)
+                guard(gen)
+                const attemptCost = Number(gen.cost) || perAttemptCost
+                accumulatedCost += attemptCost
+                reservation.commit(attemptCost, {
+                  ctx,
+                  meta: { provider: k, model: cfg.model || cfg.customModel, prompt: p, seed: seedVal },
+                })
+                return gen
+              } catch (err) {
+                reservation.release()
+                throw err
+              }
             }
 
             const { generated: acceptedGen, qualityReport } = await executeWithQualityGate(
@@ -398,7 +409,7 @@ export function registerGenerationTools(ctx, deps, options = {}) {
               }
             )
 
-            // Save the accepted artifact ONCE
+            // Save the accepted artifact ONCE (spend already committed per attempt)
             const saved = await saveGeneratedImageArtifact({
               ctx,
               exec,
@@ -417,6 +428,7 @@ export function registerGenerationTools(ctx, deps, options = {}) {
               slugify,
               estimatedCost: accumulatedCost || estimatedCost,
               totalCount,
+              recordSpend: false,
             })
 
             return {

package/lib/tools/processing-basic.js

@@ -15,7 +15,7 @@ import {
   saveAttachmentSafe,
 } from '../providers.js'
 import { buildDualOutputMarkdown } from '../resolve-image.js'
-import { assertBudgetAvailable, recordSpend } from '../cost-meter.js'
+import { assertBudgetAvailable, reserveSpend, recordSpend } from '../cost-meter.js'
 import { trackAndAssertLoopGuard } from '../loop-guard.js'
 import { sanitizeErrorAndLogs } from '../security.js'
 
@@ -55,7 +55,7 @@ export function registerProcessingTools(ctx, deps) {
             const source = await resolveSource(ctx, exec, args.image)
             if (!source || !source.bytes) throw new Error('Source image not found: ' + args.image)
           const cfg = live()
-          assertBudgetAvailable(0.02, cfg.dailyBudgetUsd)
+          const resvNobg = reserveSpend(0.02, cfg.dailyBudgetUsd)
           const res = await removeBackgroundFal(
             { fetchImpl: fetch, resolveKey: (ref) => resolveApiKey(ctx, ref), cfg },
             { imageBytes: source.bytes, mediaType: source.mediaType, model: args.model, signal: exec?.signal }
@@ -68,7 +68,7 @@ export function registerProcessingTools(ctx, deps) {
           await mkdir(outDir, { recursive: true })
           const filePath = path.join(outDir, name)
           await writeFile(filePath, res.bytes)
-          recordSpend(0.02, { ctx, meta: { tool: 'remove_background', model: args.model || 'fal-ai/birefnet' } })
+          resvNobg.commit(0.02, { ctx, meta: { tool: 'remove_background', model: args.model || 'fal-ai/birefnet' } })
           const summary = buildDualOutputMarkdown({
             action: 'background removed',
             filePath,
@@ -126,7 +126,7 @@ export function registerProcessingTools(ctx, deps) {
             const source = await resolveSource(ctx, exec, args.image)
             if (!source || !source.bytes) throw new Error('Source image not found: ' + args.image)
           const cfg = live()
-          assertBudgetAvailable(0.025, cfg.dailyBudgetUsd)
+          const resvUpscale = reserveSpend(0.025, cfg.dailyBudgetUsd)
           const res = await upscaleImageFal(
             { fetchImpl: fetch, resolveKey: (ref) => resolveApiKey(ctx, ref), cfg },
             { imageBytes: source.bytes, mediaType: source.mediaType, scale: args.scale, prompt: args.prompt, creativity: args.creativity, signal: exec?.signal }
@@ -139,7 +139,7 @@ export function registerProcessingTools(ctx, deps) {
           await mkdir(outDir, { recursive: true })
           const filePath = path.join(outDir, name)
           await writeFile(filePath, res.bytes)
-          recordSpend(0.025, { ctx, meta: { tool: 'upscale_image', scale: args.scale } })
+          resvUpscale.commit(0.025, { ctx, meta: { tool: 'upscale_image', scale: args.scale } })
           const summary = buildDualOutputMarkdown({
             action: `upscaled (${args.scale || 2}x)`,
             filePath,
@@ -254,7 +254,7 @@ export function registerProcessingTools(ctx, deps) {
             const cfg = live()
             const sessionId = exec?.agent?.session?.id || exec?.agent?.session?.header?.id || 'session'
             trackAndAssertLoopGuard(sessionId, { limit: cfg.loopGuardLimit, prompt: args.prompt || '', exec })
-            assertBudgetAvailable(0.05, cfg.dailyBudgetUsd)
+            const resvBlend = reserveSpend(0.05, cfg.dailyBudgetUsd)
             const refs = Array.isArray(args.images) ? args.images : [args.images].filter(Boolean)
           if (refs.length < 2) {
             throw new Error('At least two images are required for blending')
@@ -279,7 +279,7 @@ export function registerProcessingTools(ctx, deps) {
           await mkdir(outDir, { recursive: true })
           const filePath = path.join(outDir, name)
           await writeFile(filePath, res.bytes)
-          recordSpend(0.05, { ctx, meta: { tool: 'blend_images' } })
+          resvBlend.commit(0.05, { ctx, meta: { tool: 'blend_images' } })
           const summary = buildDualOutputMarkdown({
             action: 'blended composition',
             filePath,

package/lib/tools/style-matrix.js

@@ -14,7 +14,7 @@ import {
   saveAttachmentSafe,
 } 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 {
   normalizeMatrixStyles,
   buildMatrixCellPrompt,
@@ -145,7 +145,7 @@ export function registerStyleMatrixTools(ctx, deps) {
             size: cfg.defaultSize || '1024x1024',
             count: cellCount,
           })
-          assertBudgetAvailable(estimatedCost, cfg.dailyBudgetUsd)
+          const batchReservation = reserveSpend(estimatedCost, cfg.dailyBudgetUsd)
 
           const chain = resolveFallbackChain(provider, cfg.fallbackProviders, PROVIDER_KEYS)
           const quadrantIds = ['A', 'B', 'C', 'D']
@@ -187,7 +187,7 @@ export function registerStyleMatrixTools(ctx, deps) {
             })
 
             const cellCost = Number(gen.cost) || +(estimatedCost / cellCount).toFixed(4)
-            recordSpend(cellCost, {
+            batchReservation.commit(cellCost, {
               ctx,
               meta: { provider, model: cfg.model || cfg.customModel, prompt: cellPrompt, seed: cellSeed },
             })

package/lib/tools/theme-pair.js

@@ -13,7 +13,7 @@ import {
   saveAttachmentSafe,
 } 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 {
   THEME_STYLES,
@@ -153,7 +153,7 @@ export function registerThemePairTools(ctx, deps) {
             size: cfg.defaultSize || '1024x1024',
             count: 2,
           })
-          assertBudgetAvailable(estimatedCost, cfg.dailyBudgetUsd)
+          const batchReservation = reserveSpend(estimatedCost, cfg.dailyBudgetUsd)
 
           const chain = resolveFallbackChain(primaryProvider, cfg.fallbackProviders, PROVIDER_KEYS)
           const baseSeed = typeof args.seed === 'number' ? args.seed : Math.floor(Math.random() * 1000000)
@@ -202,7 +202,7 @@ export function registerThemePairTools(ctx, deps) {
             height: lightGen.height || aspectPixels[1],
           })
           const halfCost = +(estimatedCost / 2).toFixed(4)
-          recordSpend(Number(lightGen.cost) || halfCost, {
+          batchReservation.commit(Number(lightGen.cost) || halfCost, {
             ctx,
             meta: { provider: primaryProvider, model: cfg.model || cfg.customModel, prompt: lightPrompt },
           })
@@ -245,7 +245,7 @@ export function registerThemePairTools(ctx, deps) {
             width: darkGen.width || aspectPixels[0],
             height: darkGen.height || aspectPixels[1],
           })
-          recordSpend(Number(darkGen.cost) || halfCost, {
+          batchReservation.commit(Number(darkGen.cost) || halfCost, {
             ctx,
             meta: { provider: primaryProvider, model: cfg.model || cfg.customModel, prompt: darkPrompt },
           })

package/lib/tools/ui-asset.js

@@ -15,7 +15,7 @@ import {
   saveAttachmentSafe,
 } 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 { buildDualOutputMarkdown } from '../resolve-image.js'
 import {
   UI_ASSET_TYPES,
@@ -168,14 +168,19 @@ export function registerUiAssetTools(ctx, deps) {
             size: cfg.defaultSize || '1024x1024',
             count: 1,
           })
-          assertBudgetAvailable(estimatedCost, cfg.dailyBudgetUsd)
-
+          const reservation = reserveSpend(estimatedCost, cfg.dailyBudgetUsd)
           const chain = resolveFallbackChain(provider, cfg.fallbackProviders, PROVIDER_KEYS)
           const seedVal = args.seed ?? Math.floor(Math.random() * 100000)
 
-          const gen = await executeWithFallback(providers, chain, seedVal, synthesizedPrompt, {
-            logger: ctx.logger,
-          })
+          let gen
+          try {
+            gen = await executeWithFallback(providers, chain, seedVal, synthesizedPrompt, {
+              logger: ctx.logger,
+            })
+          } catch (err) {
+            reservation.release()
+            throw err
+          }
 
           let finalBytes = gen.bytes
           let mediaType = gen.mediaType || 'image/png'
@@ -211,7 +216,7 @@ export function registerUiAssetTools(ctx, deps) {
           })
 
           const effectiveCost = Number(gen.cost) || estimatedCost
-          recordSpend(effectiveCost, {
+          reservation.commit(effectiveCost, {
             ctx,
             meta: { provider, model: cfg.model || cfg.customModel, prompt: synthesizedPrompt, seed: seedVal },
           })

package/lib/tools/vision-ocr.js

@@ -12,7 +12,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 {
   normalizeBbox,
@@ -252,15 +252,20 @@ export function registerVisionOcrTools(ctx, deps) {
             size: `${imgWidth}x${imgHeight}`,
             count: 1,
           })
-          assertBudgetAvailable(estimatedCost, cfg.dailyBudgetUsd)
-
-          const gen = await executeWithFallback(
-            providers,
-            fallbackChain,
-            seed,
-            inpaintPrompt,
-            { logger: ctx.logger },
-          )
+          const reservation = reserveSpend(estimatedCost, cfg.dailyBudgetUsd)
+          let gen
+          try {
+            gen = await executeWithFallback(
+              providers,
+              fallbackChain,
+              seed,
+              inpaintPrompt,
+              { logger: ctx.logger },
+            )
+          } catch (err) {
+            reservation.release()
+            throw err
+          }
 
           const inpaintedBytes = gen.bytes
           if (!inpaintedBytes) {
@@ -323,7 +328,7 @@ export function registerVisionOcrTools(ctx, deps) {
           })
 
           const effectiveCost = Number(gen.cost) || estimatedCost
-          recordSpend(effectiveCost, {
+          reservation.commit(effectiveCost, {
             ctx,
             meta: { provider: usedProvider, model: cfg.model || cfg.customModel, prompt: inpaintPrompt, seed },
           })

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@goodandready/dsh-image-gen",
-  "version": "0.11.30",
+  "version": "0.11.31",
   "description": "Image generation for DeepSeek Harness: a generate_image tool with pluggable providers — the FAL queue, any OpenAI-compatible images API, or a ChatGPT/Grok subscription with no API key at all. The picture is shown inline in the conversation; the model receives either a link (works with any chat model) or the image itself (needs dsh-vision-bridge or a vision-capable model).",
   "keywords": [
     "deepseek-harness",