Skip to content

Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS

98.1 KB
Raw Blame
vi.mock('../services/catalogDB/identityAccess.js', () => ({ assertCatalogIdentityWritable: vi.fn(async id => id) }));
import { describe, it, expect, vi, beforeEach, afterEach, afterAll } from 'vitest';
import express from 'express';
import { resolveImageCleaners } from '../lib/imageCleanDefaults.js';
import { request as httpRequest } from 'node:http';
import { pinPlatform, request, startLoopbackServer, closeLoopbackServer } from '../lib/testHelper.js';
import { errorMiddleware } from '../lib/errorHandler.js';
import { cleanupTempDataRoots, lazyTempDataRoot, makePathsProxy } from '../lib/mockPathsDataRoot.js';

// The annotated-regen path stages its init-image snapshot under PATHS.imageRefs
// (imageGen.js's `ensureDir(PATHS.imageRefs)` + init-<uuid>.png write). Without
// this redirect the suite wrote that snapshot into the developer's live data/
// tree on every run of the "stages the flattened annotation" case (#6176).
vi.mock('../lib/fileUtils.js', async (importOriginal) =>
  makePathsProxy(await importOriginal(), { dataRoot: () => lazyTempDataRoot('portos-imagegen-') }));
// `fileUtils.js` re-exports pathSafety.js's resolvers (resolveGalleryImage,
// resolveImageInputPath, …), but those read PATHS from `paths.js` directly —
// the fileUtils.js mock above never touches that binding. Mirror the same
// temp root here too, so the runner's own re-validation of the staged init
// path (`fileUtils.resolveImageInputPath`) agrees with where the write above
// actually landed.
vi.mock('../lib/paths.js', async (importOriginal) =>
  makePathsProxy(await importOriginal(), { dataRoot: () => lazyTempDataRoot('portos-imagegen-') }));
afterAll(cleanupTempDataRoots);

const disconnectLifecycle = vi.hoisted(() => ({ onDisconnect: vi.fn() }));
vi.mock('../lib/sseDownload.js', async (importOriginal) => {
  const actual = await importOriginal();
  return {
    ...actual,
    onClientDisconnect: (req, res, handler) => actual.onClientDisconnect(req, res, () => {
      disconnectLifecycle.onDisconnect();
      handler();
    }),
  };
});

import imageGenRoutes from './imageGen.js';
import * as fileUtils from '../lib/fileUtils.js';
import * as regen from '../services/imageGen/regen.js';
import * as mediaSketches from '../services/mediaSketches.js';
import { writeFile, rm } from 'fs/promises';
import { tmpdir } from 'os';
import { join as pathJoin } from 'path';

const attachNodeImage = vi.hoisted(() => vi.fn(async () => ({})));
const getLoom = vi.hoisted(() => vi.fn(async () => null));
vi.mock('../services/fableLoom/records.js', () => ({ attachNodeImage, getLoom }));

const compiledVisual = vi.hoisted(() => ({
  version: 1, compilerVersion: '1.0.0', status: 'locked', assets: [], adapters: [], omitted: [], warnings: [],
}));
const compileFableLoomVisualRequest = vi.hoisted(() => vi.fn(async ({ authoredPrompt, authoredNegativePrompt }) => ({
  prompt: authoredPrompt,
  negativePrompt: authoredNegativePrompt || '',
  referenceImagePaths: [],
  referenceImageStrengths: [],
  loraFilenames: [],
  loraScales: [],
  visualConditioning: compiledVisual,
})));
const fableLoomImageCapabilities = vi.hoisted(() => vi.fn(() => ({ version: 1, kind: 'image' })));
vi.mock('../services/fableLoom/visualConditioning.js', () => ({
  compileFableLoomVisualRequest,
  fableLoomImageCapabilities,
}));

vi.mock('../services/imageGen/index.js', () => ({
  checkConnection: vi.fn(),
  generateImage: vi.fn(),
  generateAvatar: vi.fn(),
  attachSseClient: vi.fn(() => false),
  cancel: vi.fn(() => false),
  cancelJob: vi.fn(() => false),
  IMAGE_GEN_MODE: { EXTERNAL: 'external', LOCAL: 'local', CODEX: 'codex', GROK: 'grok', AGY: 'agy' },
  IMAGE_GEN_MODES: ['external', 'local', 'codex', 'grok', 'agy'],
  CLOUD_IMAGE_GEN_MODES: ['codex', 'grok', 'agy'],
  resolveImageCleaners,
  local: {
    listImageModels: vi.fn(() => []),
    listLoraFilenames: vi.fn(async () => []),
    listGallery: vi.fn(async () => []),
    assertGalleryFilename: vi.fn(),
    readImageSidecar: vi.fn(async () => ({ path: '', metadata: {} })),
    saveUploadedGalleryImage: vi.fn(async () => ({ filename: 'upload-abcd1234.png', path: '/data/images/upload-abcd1234.png' })),
  },
}));

// Default to external mode in tests so /generate goes through the dispatcher.
// Local-mode tests below override the settings mock to flip into queue mode.
// Spread the real module (rather than replacing it outright) so `settingsEvents`
// stays a real EventEmitter — `authGate.js` (reached via imageGenSetup.js's
// `resolveSetupInterpreter`, #9015) subscribes to it at import time.
vi.mock('../services/settings.js', async (importOriginal) => ({
  ...(await importOriginal()),
  getSettings: vi.fn(async () => ({ imageGen: { mode: 'external' } })),
}));

// Route tests assert the historical local default (`dev`) and python setup
// errors, not host admission. Use a stable capable host so those assertions
// behave the same on macOS, Linux, and Windows runners.
vi.mock('../lib/systemCapabilities.js', async () => {
  const actual = await vi.importActual('../lib/systemCapabilities.js');
  return {
    ...actual,
    captureSystemCapabilities: vi.fn(() => ({
      version: actual.SYSTEM_CAPABILITIES_VERSION,
      platform: 'darwin',
      arch: 'arm64',
      appleSilicon: true,
      cpuCount: 8,
      totalMemoryGb: 128,
      cuda: {
        status: 'absent',
        gpus: [],
        maxVramGb: null,
        primaryComputeCap: null,
        error: null,
      },
    })),
  };
});

vi.mock('../services/mediaJobQueue/index.js', () => ({
  assertMediaQueueRoom: vi.fn(),
  enqueueJob: vi.fn(({ kind }) => ({ jobId: `mock-${kind}-job`, position: 1, status: 'queued' })),
  attachSseClient: vi.fn(() => false),
  cancelJob: vi.fn(async () => ({ ok: true, status: 'canceling' })),
  listJobs: vi.fn(() => []),
}));

const recordUserAction = vi.hoisted(() => vi.fn(async () => ({ id: 'evt' })));
vi.mock('../services/userActions.js', () => ({ recordUserAction }));

// The /generate route resolves an optional universeRun collection target via
// findOrCreateUniverseCollection. Mock it so the universeRun test asserts the
// tag-resolution wiring without touching real collection storage.
// The federated branch resolves the peer + capacity preflight through this
// helper; mock it so the route test asserts its own validation and enqueue
// wiring without standing up a peer registry.
const federatedPeerId = '00000000-0000-4000-8000-0000000000f1';
vi.mock('../services/federatedMedia/remoteSubmission.js', () => ({
  prepareRemoteMediaJob: vi.fn(async ({ peerId, kind, request }) => ({
    peer: { id: peerId },
    capability: { kind, engine: request.engine, modelId: request.modelId },
    remoteMedia: { wireVersion: 1, peerId, reconcile: false, cancelRequested: false, request },
  })),
}));

vi.mock('../services/mediaCollections.js', () => ({
  findOrCreateUniverseCollection: vi.fn(async ({ universeId }) => ({ id: `col-${universeId}` })),
}));

// POST /avatar folds character-avatar persistence in when persistToCharacter is
// set. Mock the service so the test asserts the wiring without touching the
// real singleton character store.
vi.mock('../services/character.js', () => ({
  setAvatar: vi.fn(async (avatarPath) => ({ name: 'Gandalf', avatarPath })),
}));

// HOST_ARCH is read at request time inside `buildSetupCheck`, so backing it
// with a hoisted mutable holder + getter lets tests flip between arm64 and
// x86_64 hosts without re-mocking. Default arm64 keeps every existing test
// behaving as before.
const hostArchHolder = vi.hoisted(() => ({ value: 'arm64' }));

vi.mock('../lib/pythonSetup.js', () => ({
  REQUIRED_PACKAGES: ['mflux', 'mlx'],
  get HOST_ARCH() { return hostArchHolder.value; },
  isAllowedPython: vi.fn(() => true),
  probePythonHealth: vi.fn(async () => ({
    installed: ['mflux', 'mlx'], missing: [], missingPip: [],
    externallyManaged: false, interpreterArch: 'arm64',
  })),
  detectPython: vi.fn(async () => '/usr/bin/python3'),
  detectArm64Python: vi.fn(async () => null),
  installPackages: vi.fn(() => ({ promise: Promise.resolve(), kill: vi.fn() })),
  createVenv: vi.fn(async () => '/fake/venv/python'),
  pipNameFor: (n) => n,
  resolveFlux2Python: vi.fn(() => null),
  FLUX2_VENV_DEFAULT: '/fake/flux2-venv',
  installFlux2Venv: vi.fn(),
  isFlux2VenvHealthy: vi.fn(async () => true),
  isFlux2InstallSatisfied: vi.fn(async () => true),
}));

// Stat the python binary to key the cache. Override per-test for mtime
// changes; default to a stable mtime so the cache HIT path works.
const mockStat = vi.fn(async () => ({ mtimeMs: 1_700_000_000_000, isFile: () => false }));
vi.mock('fs/promises', async (importOriginal) => {
  const actual = await importOriginal();
  return { ...actual, stat: (path) => mockStat(path) };
});

import * as imageGen from '../services/imageGen/index.js';
import * as characterService from '../services/character.js';
import * as mediaJobQueue from '../services/mediaJobQueue/index.js';
import { getSettings } from '../services/settings.js';
// Asserted against the CONSTANT, never a literal copy of it: the shipped agy
// pin has to be re-pointed whenever Google retires an id, and a hard-coded
// expectation here turns that routine bump into a false failure.
import { AGY_IMAGEGEN_DEFAULT_MODEL } from '../lib/imageGenCapabilities.js';
import { findOrCreateUniverseCollection } from '../services/mediaCollections.js';
import { prepareRemoteMediaJob } from '../services/federatedMedia/remoteSubmission.js';

describe('Image Gen Routes', () => {
  let app;

  beforeEach(() => {
    app = express();
    app.use(express.json());
    // These requests run over a real loopback socket (`lib/testHelper.js`'s
    // fetch-based harness), so on a real password-free install they'd carry
    // host control via `requestHasHostControl` — this stands in for the
    // `authGate` middleware server/index.js mounts ahead of every route,
    // without dragging its settings/instance-identity dependencies into this
    // suite. `imageGenSetup.js`'s `/setup/*` routes need it (#9015) to reach
    // an interpreter path outside the caller's own allowlisted categories.
    app.use((req, _res, next) => {
      req.portosAuthContext = { enabled: false, authenticated: false, method: null };
      next();
    });
    app.use('/api/image-gen', imageGenRoutes);
    app.use(errorMiddleware);
    vi.clearAllMocks();
  });

  describe('GET /api/image-gen/gallery', () => {
    it('preserves legacy arrays and pages/searches the test disk fallback', async () => {
      const items = [
        { filename: 'a.png', prompt: 'red fox', path: '/data/images/a.png', seed: 42 },
        { filename: 'b.png', prompt: 'red fox', path: '/data/images/b.png' },
        { filename: 'c.png', prompt: 'blue fox', hidden: true },
      ];
      imageGen.local.listGallery.mockResolvedValue(items);
      expect((await request(app).get('/api/image-gen/gallery')).body).toEqual(items);
      const page = await request(app).get('/api/image-gen/gallery?limit=1&offset=1&q=red&hidden=false');
      expect(page.status).toBe(200);
      expect(page.body).toEqual({ items: [items[1]], total: 2, limit: 1, offset: 1 });
      const summary = await request(app).get('/api/image-gen/gallery?limit=5&hidden=false&summary=true');
      expect(summary.body).toEqual({ items: items.slice(0, 2), total: 2, hiddenTotal: 1, limit: 5, offset: 0 });
      const preview = await request(app).get('/api/image-gen/gallery?limit=1&filename=c.png');
      expect(preview.body).toEqual({ items: [items[2]], total: 1, limit: 1, offset: 0 });
      const empty = await request(app).get('/api/image-gen/gallery?q=missing');
      expect(empty.body).toEqual({ items: [], total: 0, limit: 60, offset: 0 });
    });

    // #8292: migrated consumers opt into compact card rows; search and visible
    // counts still read the full stored metadata, and older callers keep full records.
    it('projects compact visible rows on request while searching the full prompt', async () => {
      const longPrompt = 'harbor at dawn '.repeat(60) + 'lighthouse';
      const items = [
        { filename: 'a.png', prompt: longPrompt, negativePrompt: 'blur '.repeat(200), path: '/data/images/a.png', seed: 3, width: 64, height: 64, cfgScale: 4, cleanedFrom: 'root.png' },
        { filename: 'b.png', prompt: 'short', hidden: true },
      ];
      imageGen.local.listGallery.mockResolvedValue(items);
      const compact = await request(app).get('/api/image-gen/gallery?limit=5&hidden=false&summary=true&compact=true&q=lighthouse');
      expect(compact.status).toBe(200);
      expect(compact.body).toMatchObject({ total: 1, hiddenTotal: 0 });
      const [row] = compact.body.items;
      expect(row).toMatchObject({ compact: true, filename: 'a.png', path: '/data/images/a.png', seed: 3, width: 64, cleanedFrom: 'root.png' });
      expect(row.prompt.length).toBeLessThanOrEqual(241);
      expect(longPrompt.startsWith(row.prompt.slice(0, -1))).toBe(true);
      expect(row).not.toHaveProperty('negativePrompt');
      expect(row).not.toHaveProperty('cfgScale');
      const visible = await request(app).get('/api/image-gen/gallery?limit=5&hidden=false&summary=true&compact=true');
      expect(visible.body).toMatchObject({ total: 1, hiddenTotal: 1 });
      const full = await request(app).get('/api/image-gen/gallery?limit=5&hidden=false');
      expect(full.body.items).toEqual([items[0]]);
      expect((await request(app).get('/api/image-gen/gallery?compact=yes')).status).toBe(400);
    });

    it('hydrates only requested filenames and rejects an oversized reference batch', async () => {
      const items = [{ filename: 'a.png', prompt: 'first' }, { filename: 'b.png', prompt: 'second' }];
      imageGen.local.listGallery.mockResolvedValue(items);
      const response = await request(app).post('/api/image-gen/gallery/lookup').send({ filenames: ['b.png'] });
      expect(response.status).toBe(200);
      expect(response.body).toEqual([items[1]]);
      const oversized = await request(app).post('/api/image-gen/gallery/lookup').send({ filenames: Array.from({ length: 201 }, (_, n) => `${n}.png`) });
      expect(oversized.status).toBe(400);
    });

    it.each(['limit=0', 'limit=201', 'offset=-1', 'limit=1.5', 'q=a&q=b', 'starred=1', 'summary=yes', 'filename='])('rejects invalid paging: %s', async query => {
      const response = await request(app).get('/api/image-gen/gallery?' + query);
      expect(response.status).toBe(400);
      expect(imageGen.local.listGallery).not.toHaveBeenCalled();
    });
  });

  describe('GET /api/image-gen/status', () => {
    it('should return connection status', async () => {
      imageGen.checkConnection.mockResolvedValue({ connected: true, model: 'flux-v1' });

      const response = await request(app).get('/api/image-gen/status');

      expect(response.status).toBe(200);
      expect(response.body.connected).toBe(true);
      expect(response.body.model).toBe('flux-v1');
    });

    it('should return disconnected status', async () => {
      imageGen.checkConnection.mockResolvedValue({ connected: false, reason: 'No SD API URL configured' });

      const response = await request(app).get('/api/image-gen/status');

      expect(response.status).toBe(200);
      expect(response.body.connected).toBe(false);
    });

    it('forwards a valid ?mode= query into checkConnection', async () => {
      imageGen.checkConnection.mockResolvedValue({ connected: true, mode: 'codex' });
      const response = await request(app).get('/api/image-gen/status?mode=codex');
      expect(response.status).toBe(200);
      expect(imageGen.checkConnection).toHaveBeenCalledWith({ mode: 'codex' });
    });

    it('forwards a bounded local model selection into checkConnection', async () => {
      imageGen.checkConnection.mockResolvedValue({ connected: true, mode: 'local', modelId: 'flux2-klein-4b' });
      const response = await request(app).get('/api/image-gen/status?mode=local&modelId=flux2-klein-4b');
      expect(response.status).toBe(200);
      expect(imageGen.checkConnection).toHaveBeenCalledWith({ mode: 'local', modelId: 'flux2-klein-4b' });
    });

    it('ignores an invalid ?mode= query and uses the saved default', async () => {
      imageGen.checkConnection.mockResolvedValue({ connected: true, mode: 'external' });
      const response = await request(app).get('/api/image-gen/status?mode=bogus');
      expect(response.status).toBe(200);
      expect(imageGen.checkConnection).toHaveBeenCalledWith({ mode: undefined });
    });

    // Express turns ?mode=a&mode=b into an array — without the
    // typeof === 'string' guard, that array would either match
    // IMAGE_GEN_MODES.includes() falsely or propagate as a non-string
    // mode to the dispatcher.
    it('ignores a duplicated-key ?mode= array', async () => {
      imageGen.checkConnection.mockResolvedValue({ connected: true, mode: 'external' });
      const response = await request(app).get('/api/image-gen/status?mode=local&mode=codex');
      expect(response.status).toBe(200);
      expect(imageGen.checkConnection).toHaveBeenCalledWith({ mode: undefined });
    });
  });

  describe('POST /api/image-gen/generate', () => {
    it('should generate an image', async () => {
      imageGen.generateImage.mockResolvedValue({
        generationId: 'gen-001',
        filename: 'test.png',
        path: '/data/images/test.png'
      });

      const response = await request(app)
        .post('/api/image-gen/generate')
        .send({ prompt: 'a fantasy landscape' });

      expect(response.status).toBe(200);
      expect(response.body.path).toBe('/data/images/test.png');
      expect(imageGen.generateImage).toHaveBeenCalledWith(expect.objectContaining({ prompt: 'a fantasy landscape' }));
    });

    it('durably attaches a synchronous FableLoom scene render', async () => {
      getLoom.mockResolvedValueOnce({
        id: 'loom-1',
        renderSettings: { formatId: 'landscape-16-9' },
        episodes: [{ id: 'ep-1', number: 1, startNodeId: 'node-1', nodes: [{ id: 'node-1', transitions: [] }] }],
      });
      imageGen.generateImage.mockResolvedValue({
        generationId: 'gen-scene-001',
        filename: 'scene.png',
        path: '/data/images/scene.png',
      });

      const response = await request(app)
        .post('/api/image-gen/generate')
        .send({
          prompt: 'an example scene',
          fableLoom: { loomId: 'loom-1', episodeId: 'ep-1', nodeId: 'node-1' },
        });

      expect(response.status).toBe(200);
      expect(attachNodeImage).toHaveBeenCalledWith(
        'loom-1',
        'ep-1',
        'node-1',
        {
          filename: 'scene.png',
          jobId: 'gen-scene-001',
          visualConditioning: expect.objectContaining({
            render: expect.objectContaining({
              parameters: { width: 1024, height: 576, aspectRatio: '16:9' },
            }),
          }),
        },
      );
      expect(imageGen.generateImage).toHaveBeenCalledWith(expect.objectContaining({
        width: 1024, height: 576, aspectRatio: '16:9',
      }));
      expect(compileFableLoomVisualRequest).toHaveBeenCalledWith(expect.objectContaining({
        tag: { loomId: 'loom-1', episodeId: 'ep-1', nodeId: 'node-1' }, kind: 'image',
      }));
    });

    // The install pin used to be read only inside resolveLocalImageModel, so a
    // FableLoom generate with no body modelId compiled capability from `dev`
    // and then queued the pinned FLUX.2 model — stripping refs/LoRAs that the
    // actual runner would have accepted (#7362).
    it('threads the install-local pin through FableLoom capability compile and the queued job', async () => {
      getSettings.mockResolvedValueOnce({
        imageGen: { mode: 'local', local: { modelId: 'flux2-klein-9b' } },
      });
      getLoom.mockResolvedValueOnce({
        id: 'loom-1',
        renderSettings: { formatId: 'landscape-16-9' },
        episodes: [{ id: 'ep-1', number: 1, startNodeId: 'node-1', nodes: [{ id: 'node-1', transitions: [] }] }],
      });
      mediaJobQueue.enqueueJob.mockReturnValueOnce({ jobId: 'queued-pin-001', position: 1, status: 'queued' });

      const response = await request(app)
        .post('/api/image-gen/generate')
        .send({
          prompt: 'an example scene',
          fableLoom: { loomId: 'loom-1', episodeId: 'ep-1', nodeId: 'node-1' },
        });

      expect(response.status).toBe(200);
      expect(response.body.model).toBe('flux2-klein-9b');
      expect(fableLoomImageCapabilities).toHaveBeenCalledWith(expect.objectContaining({
        mode: 'local',
        model: expect.objectContaining({ id: 'flux2-klein-9b' }),
      }));
      expect(mediaJobQueue.enqueueJob).toHaveBeenCalledWith(expect.objectContaining({
        kind: 'image',
        params: expect.objectContaining({ modelId: 'flux2-klein-9b' }),
      }));
    });

    it('refuses a scene image in a later episode until prior storyboard images exist', async () => {
      getLoom.mockResolvedValueOnce({
        id: 'loom-1',
        episodes: [
          {
            id: 'ep-1',
            number: 1,
            startNodeId: 'scene-1',
            nodes: [{ id: 'scene-1', title: 'Prior scene', image: null, transitions: [] }],
          },
          {
            id: 'ep-2',
            number: 2,
            startNodeId: 'scene-2',
            nodes: [{ id: 'scene-2', title: 'Later scene', transitions: [] }],
          },
        ],
      });

      const response = await request(app)
        .post('/api/image-gen/generate')
        .send({
          prompt: 'a later episode scene',
          fableLoom: { loomId: 'loom-1', episodeId: 'ep-2', nodeId: 'scene-2' },
        });

      expect(response.status).toBe(409);
      expect(response.body.code).toBe('FABLELOOM_EPISODE_ORDER_BLOCKED');
      expect(response.body.error).toContain('Finish storyboard images for Episode 1');
      expect(imageGen.generateImage).not.toHaveBeenCalled();
      expect(compileFableLoomVisualRequest).not.toHaveBeenCalled();
    });

    it('accepts a missing/empty prompt (i2i / edit / unconditional), defaulting it to empty', async () => {
      imageGen.generateImage.mockResolvedValue({
        generationId: 'gen-empty',
        filename: 'test.png',
        path: '/data/images/test.png'
      });
      const response = await request(app)
        .post('/api/image-gen/generate')
        .send({});

      expect(response.status).toBe(200);
      expect(imageGen.generateImage).toHaveBeenCalledWith(expect.objectContaining({ prompt: '' }));
    });

    it('rejects a Codex text-to-image request with no prompt and no init image (synchronous 400)', async () => {
      const response = await request(app)
        .post('/api/image-gen/generate')
        .send({ mode: 'codex' });

      expect(response.status).toBe(400);
      expect(response.body.code).toBe('VALIDATION_ERROR');
    });

    it('should validate width and height bounds', async () => {
      const response = await request(app)
        .post('/api/image-gen/generate')
        .send({ prompt: 'test', width: 50000 });

      expect(response.status).toBe(400);
    });

    it('rejects a NUL character in the prompt or negative prompt with 400 (#11862)', async () => {
      imageGen.generateImage.mockClear();
      for (const body of [{ prompt: 'a\u0000b' }, { prompt: 'ok', negativePrompt: 'x\u0000' }]) {
        const response = await request(app).post('/api/image-gen/generate').send(body);
        expect(response.status).toBe(400);
      }
      expect(imageGen.generateImage).not.toHaveBeenCalled();
    });

    it('should pass optional parameters', async () => {
      imageGen.generateImage.mockResolvedValue({ generationId: 'gen-002', filename: 'test2.png', path: '/data/images/test2.png' });

      await request(app)
        .post('/api/image-gen/generate')
        .send({ prompt: 'test', width: 512, height: 768, steps: 30, cfgScale: 7, seed: 42 });

      expect(imageGen.generateImage).toHaveBeenCalledWith(
        expect.objectContaining({ prompt: 'test', width: 512, height: 768, steps: 30, cfgScale: 7, seed: 42 })
      );
    });

    // referenceStrengths is the multi-reference companion to the
    // multipart referenceImage1..16 uploads. The schema accepts the array on a
    // JSON body too so a future internal caller (no files attached) doesn't
    // 400 just by listing weights.
    it('accepts up to 16 referenceStrengths entries within 0..1', async () => {
      imageGen.generateImage.mockResolvedValue({ generationId: 'gen-ref', filename: 'r.png', path: '/data/images/r.png' });
      const response = await request(app)
        .post('/api/image-gen/generate')
        .send({ prompt: 'multi-ref', referenceStrengths: Array(16).fill(0.5) });
      expect(response.status).toBe(200);
    });

    it('rejects a referenceStrengths entry outside 0..1', async () => {
      const response = await request(app)
        .post('/api/image-gen/generate')
        .send({ prompt: 'multi-ref', referenceStrengths: [0.5, 1.7] });
      expect(response.status).toBe(400);
    });

    it('rejects more than 16 referenceStrengths entries', async () => {
      const response = await request(app)
        .post('/api/image-gen/generate')
        .send({ prompt: 'multi-ref', referenceStrengths: Array(17).fill(0.5) });
      expect(response.status).toBe(400);
    });

    // Local mode goes through the mediaJobQueue rather than calling
    // generateImage synchronously; the route returns immediately with
    // { jobId, status: 'queued', position } so the UI can attach SSE.
    it('local mode enqueues through mediaJobQueue and returns queued status', async () => {
      getSettings.mockResolvedValueOnce({ imageGen: { mode: 'local', local: { pythonPath: '/usr/bin/python3' } } });
      mediaJobQueue.enqueueJob.mockReturnValueOnce({ jobId: 'queued-job-001', position: 1, status: 'queued' });

      const response = await request(app)
        .post('/api/image-gen/generate')
        .send({ prompt: 'a fox in a forest' });

      expect(response.status).toBe(200);
      expect(response.body.status).toBe('queued');
      expect(response.body.position).toBe(1);
      expect(response.body.mode).toBe('local');
      expect(response.body.jobId).toBe('queued-job-001');
      expect(response.body.generationId).toBe('queued-job-001');
      expect(response.body.path).toBe('/data/images/queued-job-001.png');
      expect(mediaJobQueue.enqueueJob).toHaveBeenCalledWith(expect.objectContaining({
        kind: 'image',
        params: expect.objectContaining({ prompt: 'a fox in a forest', pythonPath: '/usr/bin/python3', modelId: 'qwen-image-2.1' }),
      }));
      // Synchronous generateImage MUST NOT be called in local mode — the
      // queue takes ownership of the job lifecycle.
      expect(imageGen.generateImage).not.toHaveBeenCalled();
      expect(recordUserAction).toHaveBeenCalledWith(expect.objectContaining({
        type: 'media.image.enqueue',
        target: 'queued-job-001',
        summary: 'enqueued image job',
        payload: { jobId: 'queued-job-001' },
      }));
      expect(JSON.stringify(recordUserAction.mock.calls[0][0])).not.toContain('a fox in a forest');
    });

    // #8326: a full media queue must answer with a retryable refusal before
    // any job id exists — and before the render's inputs are staged.
    it('answers a full media queue with a retryable 429 and no job id', async () => {
      const { mediaQueueFullError } = await import('../services/mediaJobQueue/admission.js');
      getSettings.mockResolvedValueOnce({ imageGen: { mode: 'local', local: { pythonPath: '/usr/bin/python3' } } });
      mediaJobQueue.assertMediaQueueRoom.mockImplementationOnce(() => { throw mediaQueueFullError({ pending: 250 }); });

      const response = await request(app)
        .post('/api/image-gen/generate')
        .send({ prompt: 'a fox in a forest' });

      expect(response.status).toBe(429);
      expect(response.body).toMatchObject({ code: 'MEDIA_QUEUE_FULL', context: { retryable: true, maxPendingJobs: 250 } });
      expect(response.body.jobId).toBeUndefined();
      expect(mediaJobQueue.enqueueJob).not.toHaveBeenCalled();
      expect(recordUserAction).not.toHaveBeenCalled();
    });

    it('local mode maps cfgScale to guidance before enqueueing', async () => {
      getSettings.mockResolvedValueOnce({ imageGen: { mode: 'local', local: { pythonPath: '/usr/bin/python3' } } });
      mediaJobQueue.enqueueJob.mockReturnValueOnce({ jobId: 'queued-job-cfg', position: 1, status: 'queued' });

      const response = await request(app)
        .post('/api/image-gen/generate')
        .send({ prompt: 'a fox in a forest', cfgScale: 6.5 });

      expect(response.status).toBe(200);
      expect(mediaJobQueue.enqueueJob).toHaveBeenCalledWith(expect.objectContaining({
        kind: 'image',
        params: expect.objectContaining({ cfgScale: 6.5, guidance: 6.5 }),
      }));
    });

    // The per-request `mode` override flips into queue mode even when the
    // saved default is external — protects against future regressions where
    // someone hard-codes settings.imageGen.mode as the only mode source.
    it('per-request mode=local override enqueues even when settings default is external', async () => {
      // Local mode now validates pythonPath up-front (mflux model needs it),
      // so the test must supply a configured local section. The override
      // contract — explicit `mode: 'local'` flips into queue mode regardless
      // of the saved default — is still what's being asserted here.
      getSettings.mockResolvedValueOnce({ imageGen: { mode: 'external', local: { pythonPath: '/usr/bin/python3' } } });
      mediaJobQueue.enqueueJob.mockReturnValueOnce({ jobId: 'queued-job-002', position: 2, status: 'queued' });

      const response = await request(app)
        .post('/api/image-gen/generate')
        .send({ prompt: 'a wizard tower', mode: 'local' });

      expect(response.status).toBe(200);
      expect(response.body.status).toBe('queued');
      expect(mediaJobQueue.enqueueJob).toHaveBeenCalledWith(expect.objectContaining({ kind: 'image' }));
      expect(imageGen.generateImage).not.toHaveBeenCalled();
    });

    // The base-style probe passes a `universeRun` identity so the SERVER files
    // the finished render into the universe collection. The route must resolve
    // the collectionId server-side and tag the queued job — the front-end never
    // sends a collectionId or does post-generation bookkeeping.
    describe('universeRun collection target', () => {
      it('resolves the collection server-side and tags the queued job', async () => {
        getSettings.mockResolvedValueOnce({ imageGen: { mode: 'local', local: { pythonPath: '/usr/bin/python3' } } });
        mediaJobQueue.enqueueJob.mockReturnValueOnce({ jobId: 'queued-style', position: 1, status: 'queued' });

        const response = await request(app)
          .post('/api/image-gen/generate')
          .send({
            prompt: 'a moody noir skyline',
            universeRun: { universeId: 'uni-1', universeName: 'NoirVerse', label: 'Base style', category: 'style' },
          });

        expect(response.status).toBe(200);
        expect(findOrCreateUniverseCollection).toHaveBeenCalledWith(
          expect.objectContaining({ universeId: 'uni-1', universeName: 'NoirVerse' }),
        );
        const [call] = mediaJobQueue.enqueueJob.mock.calls;
        // collectionId is server-resolved (never client-supplied), runId minted,
        // label/category preserved — exactly what universeBuilderCollectionHook reads.
        expect(call[0].params.universeRun).toEqual(expect.objectContaining({
          universeId: 'uni-1',
          collectionId: 'col-uni-1',
          label: 'Base style',
          category: 'style',
        }));
        expect(typeof call[0].params.universeRun.runId).toBe('string');
      });

      it('drops the tag (still renders) when collection provisioning fails', async () => {
        getSettings.mockResolvedValueOnce({ imageGen: { mode: 'local', local: { pythonPath: '/usr/bin/python3' } } });
        mediaJobQueue.enqueueJob.mockReturnValueOnce({ jobId: 'queued-style-2', position: 1, status: 'queued' });
        findOrCreateUniverseCollection.mockRejectedValueOnce(new Error('db down'));

        const response = await request(app)
          .post('/api/image-gen/generate')
          .send({
            prompt: 'a moody noir skyline',
            universeRun: { universeId: 'uni-2', universeName: 'FailVerse', label: 'Base style', category: 'style' },
          });

        // The render still proceeds — a collection-filing miss must not fail it.
        expect(response.status).toBe(200);
        const [call] = mediaJobQueue.enqueueJob.mock.calls;
        expect(call[0].params.universeRun).toBeUndefined();
      });

      it('ignores universeRun without a universeId (no collection resolution)', async () => {
        getSettings.mockResolvedValueOnce({ imageGen: { mode: 'local', local: { pythonPath: '/usr/bin/python3' } } });
        mediaJobQueue.enqueueJob.mockReturnValueOnce({ jobId: 'queued-plain', position: 1, status: 'queued' });

        const response = await request(app)
          .post('/api/image-gen/generate')
          .send({ prompt: 'a plain render' });

        expect(response.status).toBe(200);
        expect(findOrCreateUniverseCollection).not.toHaveBeenCalled();
        const [call] = mediaJobQueue.enqueueJob.mock.calls;
        expect(call[0].params.universeRun).toBeUndefined();
      });

      // #1395 — section-local canon renders carry an `entryRef` so the
      // completion hook durably appends the render to the entry's imageRefs[].
      it('carries the section-local entryRef into the queued job tag', async () => {
        getSettings.mockResolvedValueOnce({ imageGen: { mode: 'local', local: { pythonPath: '/usr/bin/python3' } } });
        mediaJobQueue.enqueueJob.mockReturnValueOnce({ jobId: 'queued-section', position: 1, status: 'queued' });

        const response = await request(app)
          .post('/api/image-gen/generate')
          .send({
            prompt: 'a confident pyromancer',
            universeRun: {
              universeId: 'uni-3',
              universeName: 'CanonVerse',
              label: 'Ash',
              category: 'characters',
              entryRef: { kind: 'canon', kindKey: 'characters', id: 'char-ash' },
            },
          });

        expect(response.status).toBe(200);
        const [call] = mediaJobQueue.enqueueJob.mock.calls;
        expect(call[0].params.universeRun).toEqual(expect.objectContaining({
          universeId: 'uni-3',
          collectionId: 'col-uni-3',
          entryRef: { kind: 'canon', kindKey: 'characters', id: 'char-ash' },
        }));
      });

      it('rejects a canon entryRef missing its kindKey (would no-op the append)', async () => {
        // Zod validation rejects before prepareGenerateParams reads settings, so
        // no getSettings/enqueueJob mock is primed here — priming an unconsumed
        // mockResolvedValueOnce would leak into the next test (clearAllMocks does
        // not drain the once-queue).
        const response = await request(app)
          .post('/api/image-gen/generate')
          .send({
            prompt: 'a confident pyromancer',
            universeRun: {
              universeId: 'uni-5',
              universeName: 'CanonVerse',
              entryRef: { kind: 'canon', id: 'char-ash' }, // no kindKey
            },
          });

        expect(response.status).toBe(400);
        expect(mediaJobQueue.enqueueJob).not.toHaveBeenCalled();
      });

      it('preserves the entryRef even when collection provisioning fails', async () => {
        getSettings.mockResolvedValueOnce({ imageGen: { mode: 'local', local: { pythonPath: '/usr/bin/python3' } } });
        mediaJobQueue.enqueueJob.mockReturnValueOnce({ jobId: 'queued-section-2', position: 1, status: 'queued' });
        findOrCreateUniverseCollection.mockRejectedValueOnce(new Error('db down'));

        const response = await request(app)
          .post('/api/image-gen/generate')
          .send({
            prompt: 'a confident pyromancer',
            universeRun: {
              universeId: 'uni-4',
              universeName: 'CanonVerse',
              entryRef: { kind: 'canon', kindKey: 'characters', id: 'char-ash' },
            },
          });

        expect(response.status).toBe(200);
        const [call] = mediaJobQueue.enqueueJob.mock.calls;
        // The durable imageRefs[] append must not depend on the gallery
        // collection existing — entryRef survives, collectionId/runId don't.
        expect(call[0].params.universeRun).toEqual({
          universeId: 'uni-4',
          entryRef: { kind: 'canon', kindKey: 'characters', id: 'char-ash' },
        });
      });
    });

    // Durable catalog attach (#1359): the Catalog ingredient editor's Generate
    // button passes `catalogIngredientId` so the queued job carries a
    // `catalogAttach` tag the completion hook reads to file the render even if
    // the page unmounts. The route collapses the raw fields into the tag and
    // drops them from params.
    describe('catalogAttach tag', () => {
      it('refuses a retained target before provider preparation or enqueue', async () => {
        const { assertCatalogIdentityWritable } = await import('../services/catalogDB/identityAccess.js');
        assertCatalogIdentityWritable.mockRejectedValueOnce(Object.assign(new Error('Retained original'), { status: 409, code: 'CATALOG_IDENTITY_RETAINED' }));
        const response = await request(app).post('/api/image-gen/generate').send({ prompt: 'example', catalogIngredientId: 'retained-original' });
        expect(response.status).toBe(409);
        expect(mediaJobQueue.enqueueJob).not.toHaveBeenCalled();
      });
      it('folds catalogIngredientId into a catalogAttach job tag and drops the raw field', async () => {
        getSettings.mockResolvedValueOnce({ imageGen: { mode: 'local', local: { pythonPath: '/usr/bin/python3' } } });
        mediaJobQueue.enqueueJob.mockReturnValueOnce({ jobId: 'queued-cat', position: 1, status: 'queued' });

        const response = await request(app)
          .post('/api/image-gen/generate')
          .send({ prompt: 'a catalog hero', catalogIngredientId: 'ing-42' });

        expect(response.status).toBe(200);
        const [call] = mediaJobQueue.enqueueJob.mock.calls;
        expect(call[0].params.catalogAttach).toEqual({ ingredientId: 'ing-42' });
        // Raw fields are stripped — only the canonical tag persists in job.params.
        expect(call[0].params.catalogIngredientId).toBeUndefined();
        expect(call[0].params.catalogMediaKind).toBeUndefined();
      });

      it('preserves an explicit catalogMediaKind in the tag', async () => {
        getSettings.mockResolvedValueOnce({ imageGen: { mode: 'local', local: { pythonPath: '/usr/bin/python3' } } });
        mediaJobQueue.enqueueJob.mockReturnValueOnce({ jobId: 'queued-cat-kind', position: 1, status: 'queued' });

        const response = await request(app)
          .post('/api/image-gen/generate')
          .send({ prompt: 'a reference shot', catalogIngredientId: 'ing-7', catalogMediaKind: 'reference' });

        expect(response.status).toBe(200);
        const [call] = mediaJobQueue.enqueueJob.mock.calls;
        expect(call[0].params.catalogAttach).toEqual({ ingredientId: 'ing-7', kind: 'reference' });
      });

      it('rejects an invalid catalogMediaKind', async () => {
        const response = await request(app)
          .post('/api/image-gen/generate')
          .send({ prompt: 'x', catalogIngredientId: 'ing-9', catalogMediaKind: 'thumbnail' });
        expect(response.status).toBe(400);
      });

      it('omits catalogAttach when no catalogIngredientId is sent', async () => {
        getSettings.mockResolvedValueOnce({ imageGen: { mode: 'local', local: { pythonPath: '/usr/bin/python3' } } });
        mediaJobQueue.enqueueJob.mockReturnValueOnce({ jobId: 'queued-nocat', position: 1, status: 'queued' });

        const response = await request(app)
          .post('/api/image-gen/generate')
          .send({ prompt: 'untagged render' });

        expect(response.status).toBe(200);
        const [call] = mediaJobQueue.enqueueJob.mock.calls;
        expect(call[0].params.catalogAttach).toBeUndefined();
      });
    });

    // An explicit mflux model without a configured pythonPath rejects up-front
    // (400) rather than enqueueing a job that can never run. The new Qwen
    // default uses the shared diffusers runtime and does not require this path.
    it('mflux model with missing pythonPath returns 400 IMAGE_GEN_NOT_CONFIGURED', async () => {
      getSettings.mockResolvedValueOnce({ imageGen: { mode: 'local' } }); // no `local.pythonPath`

      const response = await request(app)
        .post('/api/image-gen/generate')
        .send({ prompt: 'a fox in a forest', modelId: 'dev' });

      expect(response.status).toBe(400);
      expect(response.body.error).toMatch(/not configured/i);
      expect(mediaJobQueue.enqueueJob).not.toHaveBeenCalled();
    });

    // z-image and ernie use the FLUX.2 venv — they must NOT require pythonPath.
    it('local mode with z-image model and missing pythonPath still enqueues (exempted)', async () => {
      getSettings.mockResolvedValueOnce({ imageGen: { mode: 'local' } }); // no pythonPath
      mediaJobQueue.enqueueJob.mockReturnValueOnce({ jobId: 'mock-image-job', position: 1, status: 'queued' });

      const response = await request(app)
        .post('/api/image-gen/generate')
        .send({ prompt: 'a fox in a forest', modelId: 'z-image-turbo-bf16' });

      expect(response.status).toBe(200);
      expect(response.body.status).toBe('queued');
      expect(mediaJobQueue.enqueueJob).toHaveBeenCalled();
    });

    it('local mode with ernie model and missing pythonPath still enqueues (exempted)', async () => {
      getSettings.mockResolvedValueOnce({ imageGen: { mode: 'local' } }); // no pythonPath
      mediaJobQueue.enqueueJob.mockReturnValueOnce({ jobId: 'mock-image-job', position: 1, status: 'queued' });

      const response = await request(app)
        .post('/api/image-gen/generate')
        .send({ prompt: 'a wizard tower', modelId: 'ernie-image' });

      expect(response.status).toBe(200);
      expect(response.body.status).toBe('queued');
      expect(mediaJobQueue.enqueueJob).toHaveBeenCalled();
    });

    // Codex mode now goes through the mediaJobQueue (codex lane), so a
    // burst of writers-room storyboard renders queues against itself
    // instead of failing the second-and-onwards calls with 409
    // IMAGE_GEN_BUSY.
    it('codex mode enqueues through mediaJobQueue and returns queued status', async () => {
      getSettings.mockResolvedValueOnce({
        imageGen: { mode: 'codex', codex: { enabled: true, codexPath: '/usr/local/bin/codex', model: 'gpt-5.4' } },
      });
      mediaJobQueue.enqueueJob.mockReturnValueOnce({ jobId: 'queued-codex-001', position: 1, status: 'queued' });

      const response = await request(app)
        .post('/api/image-gen/generate')
        .send({ prompt: 'a tavern at dusk' });

      expect(response.status).toBe(200);
      expect(response.body.status).toBe('queued');
      expect(response.body.mode).toBe('codex');
      expect(response.body.model).toBe('gpt-5.4');
      expect(response.body.jobId).toBe('queued-codex-001');
      expect(response.body.path).toBe('/data/images/queued-codex-001.png');
      expect(mediaJobQueue.enqueueJob).toHaveBeenCalledWith(expect.objectContaining({
        kind: 'image',
        params: expect.objectContaining({
          mode: 'codex',
          codexPath: '/usr/local/bin/codex',
          model: 'gpt-5.4',
          prompt: 'a tavern at dusk',
        }),
      }));
      // Synchronous generateImage MUST NOT be called in codex mode either —
      // the queue takes ownership.
      expect(imageGen.generateImage).not.toHaveBeenCalled();
    });

    // #11317: the compose preview runs the same preparation and Codex builder as
    // /generate, so the form shows the wrapper and chips before anything queues.
    it('prompt-preview shows the exact Codex message and its additions without queueing', async () => {
      getSettings.mockResolvedValueOnce({
        imageGen: { mode: 'codex', codex: { enabled: true, codexPath: '/usr/local/bin/codex', model: 'gpt-5.4' } },
      });
      const style = { id: 'style-1', label: 'Universe style', text: 'muted earth tones' };

      const response = await request(app)
        .post('/api/image-gen/prompt-preview')
        .send({ prompt: 'muted earth tones. a tavern at dusk', width: 1024, height: 1024, promptAdditions: [style], uploadedInitImage: true });

      expect(response.status).toBe(200);
      expect(response.body.mode).toBe('codex');
      expect(response.body.sentPrompt).toMatch(/^\$imagegen .*muted earth tones\. a tavern at dusk/s);
      expect(response.body.promptAdditions[0]).toEqual(style);
      expect(response.body.promptAdditions[1]).toMatchObject({ id: 'agent-instructions', label: 'Codex image tool instructions' });
      expect(response.body.promptAdditions[1].text).toContain('[prompt]');
      expect(response.body.promptAdditions[1].text).not.toContain('a tavern at dusk');
      expect(mediaJobQueue.enqueueJob).not.toHaveBeenCalled();
      expect(mediaJobQueue.assertMediaQueueRoom).not.toHaveBeenCalled();
    });

    it('prompt-preview refuses a disabled provider the way Generate does', async () => {
      getSettings.mockResolvedValueOnce({ imageGen: { mode: 'codex', codex: { enabled: false } } });
      const response = await request(app).post('/api/image-gen/prompt-preview').send({ prompt: 'a tavern at dusk' });
      expect(response.status).toBe(400);
      expect(response.body.error).toMatch(/disabled/);
    });

    // Per-request codex override: even when the saved default is external,
    // an explicit `mode: 'codex'` on the payload (e.g. the writers-room
    // storyboard chip strip) flips into queue mode so renders serialize.
    it('per-request mode=codex override enqueues even when settings default is external', async () => {
      getSettings.mockResolvedValueOnce({
        imageGen: { mode: 'external', codex: { enabled: true, model: 'gpt-5.4' } },
      });
      mediaJobQueue.enqueueJob.mockReturnValueOnce({ jobId: 'queued-codex-002', position: 2, status: 'queued' });

      const response = await request(app)
        .post('/api/image-gen/generate')
        .send({ prompt: 'a wizard tower', mode: 'codex' });

      expect(response.status).toBe(200);
      expect(response.body.status).toBe('queued');
      expect(response.body.mode).toBe('codex');
      expect(mediaJobQueue.enqueueJob).toHaveBeenCalledWith(expect.objectContaining({
        kind: 'image',
        params: expect.objectContaining({ mode: 'codex' }),
      }));
      expect(imageGen.generateImage).not.toHaveBeenCalled();
    });

    // Per-queue-item model override. `cloudModel` is dispatcher-level: it
    // replaces the provider's `model` and must NOT survive into the persisted
    // job params (the queue runner would hand the provider an unknown field).
    it('cloudModel overrides the saved cloud model for one queue item without leaking the raw field', async () => {
      getSettings.mockResolvedValueOnce({
        imageGen: { mode: 'codex', codex: { enabled: true, model: 'gpt-5.4' } },
      });
      mediaJobQueue.enqueueJob.mockReturnValueOnce({ jobId: 'queued-codex-003', position: 1, status: 'queued' });

      const response = await request(app)
        .post('/api/image-gen/generate')
        .send({ prompt: 'a lighthouse', cloudModel: 'gpt-5.6-luna' });

      expect(response.status).toBe(200);
      expect(response.body.model).toBe('gpt-5.6-luna');
      const enqueued = mediaJobQueue.enqueueJob.mock.calls.at(-1)[0];
      expect(enqueued.params.model).toBe('gpt-5.6-luna');
      expect(enqueued.params).not.toHaveProperty('cloudModel');
    });

    // Agy is the backend the override was actually built for — exercise it
    // directly instead of inferring from the codex case. (Its unpinned default
    // is now the concrete AGY_IMAGEGEN_DEFAULT_MODEL cheap-tier pin, #3231.)
    it('agy: cloudModel replaces the configured-default sentinel for one queue item', async () => {
      getSettings.mockResolvedValueOnce({
        imageGen: { mode: 'agy', agy: { enabled: true, agyPath: '/opt/agy' } },
      });
      mediaJobQueue.enqueueJob.mockReturnValueOnce({ jobId: 'queued-agy-001', position: 1, status: 'queued' });

      const response = await request(app)
        .post('/api/image-gen/generate')
        .send({ prompt: 'a lighthouse', cloudModel: 'gemini-3.1-pro-high' });

      expect(response.status).toBe(200);
      expect(response.body.mode).toBe('agy');
      expect(response.body.model).toBe('gemini-3.1-pro-high');
      const enqueued = mediaJobQueue.enqueueJob.mock.calls.at(-1)[0];
      expect(enqueued.params.model).toBe('gemini-3.1-pro-high');
      expect(enqueued.params.agyPath).toBe('/opt/agy');
      expect(enqueued.params).not.toHaveProperty('cloudModel');
    });

    it('agy: an omitted cloudModel leaves the saved default in place', async () => {
      getSettings.mockResolvedValueOnce({
        imageGen: { mode: 'agy', agy: { enabled: true, model: 'gemini-3.5-flash-high' } },
      });
      mediaJobQueue.enqueueJob.mockReturnValueOnce({ jobId: 'queued-agy-002', position: 1, status: 'queued' });

      const response = await request(app)
        .post('/api/image-gen/generate')
        .send({ prompt: 'a lighthouse' });

      expect(response.status).toBe(200);
      expect(response.body.model).toBe('gemini-3.5-flash-high');
      expect(mediaJobQueue.enqueueJob.mock.calls.at(-1)[0].params.model).toBe('gemini-3.5-flash-high');
    });

    // Defense-in-depth for the cheap-tier pin (#3231): a fully-unpinned agy
    // enqueue (no saved model, no cloudModel) must persist the concrete
    // default into the queue job — a refactor that stops spreading
    // cloud.jobParams into the enqueue would otherwise only fail at the
    // resolver-level test.
    it('agy: a fully-unpinned render enqueues the cheap-tier default model', async () => {
      getSettings.mockResolvedValueOnce({
        imageGen: { mode: 'agy', agy: { enabled: true } },
      });
      mediaJobQueue.enqueueJob.mockReturnValueOnce({ jobId: 'queued-agy-003', position: 1, status: 'queued' });

      const response = await request(app)
        .post('/api/image-gen/generate')
        .send({ prompt: 'a lighthouse' });

      expect(response.status).toBe(200);
      expect(response.body.model).toBe(AGY_IMAGEGEN_DEFAULT_MODEL);
      expect(mediaJobQueue.enqueueJob.mock.calls.at(-1)[0].params.model).toBe(AGY_IMAGEGEN_DEFAULT_MODEL);
    });

    // No getSettings mock here on purpose: Zod rejects before the route ever
    // reads settings, and a queued mockResolvedValueOnce would leak into the
    // next test.
    it('rejects a cloudModel with shell-unsafe characters', async () => {
      const response = await request(app)
        .post('/api/image-gen/generate')
        .send({ prompt: 'a lighthouse', cloudModel: '--dangerously-skip-permissions' });

      expect(response.status).toBe(400);
      expect(mediaJobQueue.enqueueJob).not.toHaveBeenCalled();
    });

    describe('cleaner resolution (body wins over saved setting)', () => {
      it('external mode: body denoise=true overrides saved setting=false', async () => {
        getSettings.mockResolvedValueOnce({
          imageGen: { mode: 'external', external: { cleanC2PA: false, denoise: false } },
        });
        imageGen.generateImage.mockResolvedValue({ filename: 'x.png', path: '/data/images/x.png' });

        await request(app).post('/api/image-gen/generate').send({ prompt: 'p', denoise: true });

        expect(imageGen.generateImage).toHaveBeenCalledWith(expect.objectContaining({ denoise: true, cleanC2PA: false }));
      });

      it('external mode: omitted body inherits saved cleanC2PA=true + denoise=false', async () => {
        getSettings.mockResolvedValueOnce({
          imageGen: { mode: 'external', external: { cleanC2PA: true, denoise: false } },
        });
        imageGen.generateImage.mockResolvedValue({ filename: 'x.png', path: '/data/images/x.png' });

        await request(app).post('/api/image-gen/generate').send({ prompt: 'p' });

        expect(imageGen.generateImage).toHaveBeenCalledWith(expect.objectContaining({ cleanC2PA: true, denoise: false }));
      });

      it.each([
        ['local', false],
        ['grok', false],
        ['agy', false],
        ['codex', true],
      ])('%s mode: omitted flags use the mode default without enabling denoise', async (mode, cleanC2PA) => {
        getSettings.mockResolvedValueOnce({
          imageGen: { mode, [mode]: { enabled: true, pythonPath: '/p' } },
        });

        const response = await request(app).post('/api/image-gen/generate').send({ prompt: 'p' });

        expect(response.status).toBe(200);
        expect(mediaJobQueue.enqueueJob).toHaveBeenCalledWith(expect.objectContaining({
          params: expect.objectContaining({ cleanC2PA, denoise: false }),
        }));
      });

      it('local mode: body flags flow through into enqueued params', async () => {
        getSettings.mockResolvedValueOnce({
          imageGen: { mode: 'local', local: { pythonPath: '/p', cleanC2PA: false, denoise: false } },
        });

        await request(app).post('/api/image-gen/generate').send({ prompt: 'p', cleanC2PA: true, denoise: true });

        const [call] = mediaJobQueue.enqueueJob.mock.calls;
        expect(call[0].params.cleanC2PA).toBe(true);
        expect(call[0].params.denoise).toBe(true);
      });

      it('codex mode: explicit false overrides enabled cleaner settings', async () => {
        getSettings.mockResolvedValueOnce({
          imageGen: { mode: 'codex', codex: { enabled: true, cleanC2PA: true, denoise: true } },
        });

        await request(app).post('/api/image-gen/generate').send({ prompt: 'p', cleanC2PA: false, denoise: false });

        const [call] = mediaJobQueue.enqueueJob.mock.calls;
        expect(call[0].params.cleanC2PA).toBe(false);
        expect(call[0].params.denoise).toBe(false);
      });

      it('defaults to cleanC2PA=true + denoise=false when neither body nor settings specify', async () => {
        getSettings.mockResolvedValueOnce({ imageGen: { mode: 'external' } });
        imageGen.generateImage.mockResolvedValue({ filename: 'x.png', path: '/data/images/x.png' });

        await request(app).post('/api/image-gen/generate').send({ prompt: 'p' });

        expect(imageGen.generateImage).toHaveBeenCalledWith(expect.objectContaining({ cleanC2PA: true, denoise: false }));
      });

      it('legacy autoClean=true on settings does NOT silently enable denoise on read', async () => {
        // Pre-split installs persisted `autoClean: true`. We no longer carry
        // that into denoise — denoise is lossy (blurs text) and must be an
        // explicit opt-in. Upgrading users get cleanC2PA on (it defaults on
        // anyway) and denoise off until they explicitly toggle it.
        getSettings.mockResolvedValueOnce({
          imageGen: { mode: 'external', external: { autoClean: true } },
        });
        imageGen.generateImage.mockResolvedValue({ filename: 'x.png', path: '/data/images/x.png' });

        await request(app).post('/api/image-gen/generate').send({ prompt: 'p' });

        expect(imageGen.generateImage).toHaveBeenCalledWith(expect.objectContaining({ cleanC2PA: true, denoise: false }));
      });

      it('legacy autoClean=true on body maps to BOTH new flags via the coerceFormFields shim', async () => {
        getSettings.mockResolvedValueOnce({ imageGen: { mode: 'external' } });
        imageGen.generateImage.mockResolvedValue({ filename: 'x.png', path: '/data/images/x.png' });

        await request(app).post('/api/image-gen/generate').send({ prompt: 'p', autoClean: true });

        expect(imageGen.generateImage).toHaveBeenCalledWith(expect.objectContaining({ cleanC2PA: true, denoise: true }));
      });
    });

    // Edit-only models (Qwen-Image-Edit) require a source image. A text-only
    // submission must be rejected up-front (400) — enqueueing it would crash
    // the runner deep inside the diffusers QwenImageEditPipeline.
    it('local mode with an edit-only model and no init image returns 400 IMAGE_GEN_EDIT_IMAGE_REQUIRED', async () => {
      getSettings.mockResolvedValueOnce({ imageGen: { mode: 'local' } }); // qwen uses the flux2 venv — no pythonPath needed

      const response = await request(app)
        .post('/api/image-gen/generate')
        .send({ prompt: 'make the sky purple', modelId: 'qwen-image-edit' });

      expect(response.status).toBe(400);
      expect(response.body.code).toBe('IMAGE_GEN_EDIT_IMAGE_REQUIRED');
      expect(response.body.error).toMatch(/source image/i);
      expect(mediaJobQueue.enqueueJob).not.toHaveBeenCalled();
    });

    // Codex with the toggle off rejects up-front rather than enqueueing.
    it('codex mode with disabled toggle returns 400 CODEX_IMAGEGEN_DISABLED', async () => {
      getSettings.mockResolvedValueOnce({
        imageGen: { mode: 'codex', codex: { enabled: false } },
      });

      const response = await request(app)
        .post('/api/image-gen/generate')
        .send({ prompt: 'a fox' });

      expect(response.status).toBe(400);
      expect(response.body.error).toMatch(/disabled/i);
      expect(mediaJobQueue.enqueueJob).not.toHaveBeenCalled();
    });

    it('grok mode enqueues through mediaJobQueue with the saved grok params', async () => {
      getSettings.mockResolvedValueOnce({
        imageGen: { mode: 'grok', grok: { enabled: true, grokPath: '/usr/local/bin/grok', aspectRatio: '16:9' } },
      });
      mediaJobQueue.enqueueJob.mockReturnValueOnce({ jobId: 'queued-grok-001', position: 1, status: 'queued' });

      const response = await request(app)
        .post('/api/image-gen/generate')
        .send({ prompt: 'a tavern at dusk' });

      expect(response.status).toBe(200);
      expect(response.body.status).toBe('queued');
      expect(response.body.mode).toBe('grok');
      expect(response.body.jobId).toBe('queued-grok-001');
      expect(mediaJobQueue.enqueueJob).toHaveBeenCalledWith(expect.objectContaining({
        kind: 'image',
        params: expect.objectContaining({
          mode: 'grok',
          grokPath: '/usr/local/bin/grok',
          aspectRatio: '16:9',
          prompt: 'a tavern at dusk',
        }),
      }));
      // Synchronous generateImage MUST NOT be called in grok mode either —
      // the queue takes ownership.
      expect(imageGen.generateImage).not.toHaveBeenCalled();
    });

    it('grok mode with disabled toggle returns 400 GROK_IMAGEGEN_DISABLED', async () => {
      getSettings.mockResolvedValueOnce({
        imageGen: { mode: 'grok', grok: { enabled: false } },
      });

      const response = await request(app)
        .post('/api/image-gen/generate')
        .send({ prompt: 'a fox' });

      expect(response.status).toBe(400);
      expect(response.body.error).toMatch(/disabled/i);
      expect(mediaJobQueue.enqueueJob).not.toHaveBeenCalled();
    });

    it('rejects a Grok text-to-image request with no prompt and no init image (synchronous 400)', async () => {
      getSettings.mockResolvedValueOnce({
        imageGen: { mode: 'grok', grok: { enabled: true } },
      });

      const response = await request(app)
        .post('/api/image-gen/generate')
        .send({ prompt: '' });

      expect(response.status).toBe(400);
      expect(response.body.error).toMatch(/prompt is required/i);
      expect(mediaJobQueue.enqueueJob).not.toHaveBeenCalled();
    });
  });

  describe('POST /api/image-gen/avatar', () => {
    it('should generate an avatar', async () => {
      imageGen.generateAvatar.mockResolvedValue({
        generationId: 'gen-003',
        filename: 'avatar.png',
        path: '/data/images/avatar.png'
      });

      const response = await request(app)
        .post('/api/image-gen/avatar')
        .send({ name: 'Gandalf', characterClass: 'Wizard' });

      expect(response.status).toBe(200);
      expect(response.body.path).toBe('/data/images/avatar.png');
    });

    it('should accept empty body for default avatar and return a response shape', async () => {
      imageGen.generateAvatar.mockResolvedValue({
        generationId: 'gen-004',
        filename: 'default.png',
        path: '/data/images/default.png'
      });

      const response = await request(app)
        .post('/api/image-gen/avatar')
        .send({});

      expect(response.status).toBe(200);
      expect(response.body.generationId).toBe('gen-004');
      expect(response.body.filename).toBe('default.png');
      expect(response.body.path).toBe('/data/images/default.png');
    });

    it('persists the rendered path onto the character when persistToCharacter is set', async () => {
      imageGen.generateAvatar.mockResolvedValue({
        generationId: 'gen-005',
        filename: 'avatar.png',
        path: '/data/images/avatar.png',
      });

      const response = await request(app)
        .post('/api/image-gen/avatar')
        .send({ name: 'Gandalf', characterClass: 'Wizard', persistToCharacter: true });

      expect(response.status).toBe(200);
      expect(response.body.path).toBe('/data/images/avatar.png');
      expect(characterService.setAvatar).toHaveBeenCalledWith('/data/images/avatar.png');
    });

    it('does NOT persist to the character when persistToCharacter is omitted', async () => {
      imageGen.generateAvatar.mockResolvedValue({
        generationId: 'gen-006',
        filename: 'avatar.png',
        path: '/data/images/avatar.png',
      });

      const response = await request(app)
        .post('/api/image-gen/avatar')
        .send({ name: 'Gandalf', characterClass: 'Wizard' });

      expect(response.status).toBe(200);
      expect(characterService.setAvatar).not.toHaveBeenCalled();
    });
  });

  describe('POST /api/image-gen/upload', () => {
    it('saves uploaded bytes into the gallery and returns a /data/images path', async () => {
      imageGen.local.saveUploadedGalleryImage.mockResolvedValue({
        filename: 'upload-deadbeef.png',
        path: '/data/images/upload-deadbeef.png',
      });

      const response = await request(app)
        .post('/api/image-gen/upload')
        .send({ data: Buffer.from('fake-png-bytes').toString('base64') });

      expect(response.status).toBe(200);
      expect(response.body.path).toBe('/data/images/upload-deadbeef.png');
      // The service receives the raw base64 string (route doesn't pre-decode).
      expect(imageGen.local.saveUploadedGalleryImage).toHaveBeenCalledWith(
        Buffer.from('fake-png-bytes').toString('base64'),
      );
    });

    it('rejects a missing data field with 400', async () => {
      const response = await request(app)
        .post('/api/image-gen/upload')
        .send({});

      expect(response.status).toBe(400);
      expect(imageGen.local.saveUploadedGalleryImage).not.toHaveBeenCalled();
    });
  });

  // GET /:jobId/events and POST /cancel both go through the dispatcher's
  // attachSseClient/cancel — these tests lock in that contract so a future
  // refactor can't accidentally re-couple them to the local provider.
  describe('SSE attach + cancel via dispatcher', () => {
    it('GET /:jobId/events returns 404 when no provider owns the job', async () => {
      imageGen.attachSseClient.mockReturnValueOnce(false);
      const response = await request(app).get('/api/image-gen/missing-job/events');
      expect(response.status).toBe(404);
      expect(response.body.error).toMatch(/not found/i);
      expect(response.body.code).toBe('NOT_FOUND');
      expect(imageGen.attachSseClient).toHaveBeenCalledWith('missing-job', expect.anything());
    });

    it('POST /cancel returns ok=false when no provider had a job', async () => {
      imageGen.cancel.mockReturnValueOnce(false);
      const response = await request(app).post('/api/image-gen/cancel');
      expect(response.status).toBe(200);
      expect(response.body.ok).toBe(false);
      expect(imageGen.cancel).toHaveBeenCalled();
    });

    it('POST /cancel returns ok=true when a provider cancelled', async () => {
      imageGen.cancel.mockReturnValueOnce(true);
      const response = await request(app).post('/api/image-gen/cancel');
      expect(response.status).toBe(200);
      expect(response.body.ok).toBe(true);
    });

    it('POST /cancel { all: true } cancels every queued/running image job', async () => {
      mediaJobQueue.listJobs.mockReturnValueOnce([
        { id: 'a', status: 'running' },
        { id: 'b', status: 'queued' },
        { id: 'c', status: 'queued' },
      ]);
      const response = await request(app).post('/api/image-gen/cancel').send({ all: true });
      expect(response.status).toBe(200);
      expect(response.body.ok).toBe(true);
      expect(response.body.attempted).toBe(3);
      expect(mediaJobQueue.cancelJob).toHaveBeenCalledTimes(3);
      // Queued jobs cancelled before the running one — slot doesn't refill mid-loop.
      expect(mediaJobQueue.cancelJob.mock.calls.map((c) => c[0])).toEqual(['b', 'c', 'a']);
      // Belt-and-braces: legacy single-process cancel also poked.
      expect(imageGen.cancel).toHaveBeenCalled();
    });

    it('POST /cancel (no jobId) picks the most-recently-submitted job by queuedAt — NOT the listJobs() ordering', async () => {
      // listJobs() returns jobs in queue-internal order: gpuRunning first,
      // then codexRunning, then queue. Without explicit queuedAt sorting, a
      // bare `/cancel` (the user's "stop the last thing I submitted" gesture)
      // would target the gpuRunning job — even when the user just queued a
      // newer Codex job that should be the cancel target. The route must
      // tie-break by queuedAt DESC so the newest submit always wins.
      mediaJobQueue.listJobs.mockReturnValueOnce([
        // listJobs ordering: gpu-running first (oldest submit, started long ago).
        { id: 'gpu-running', status: 'running', queuedAt: '2026-05-05T08:00:00Z' },
        // Codex job queued AFTER the GPU job started — this is the "most
        // recent submit" and should be the cancel target.
        { id: 'codex-newest', status: 'queued', queuedAt: '2026-05-05T08:30:00Z' },
        // Older queued job, should NOT be picked.
        { id: 'queued-older', status: 'queued', queuedAt: '2026-05-05T08:15:00Z' },
      ]);
      const response = await request(app).post('/api/image-gen/cancel').send({});
      expect(response.status).toBe(200);
      // The newest-submit (codex-newest at 08:30) wins — not 'gpu-running'
      // (which appeared first in listJobs) and not 'queued-older'.
      expect(mediaJobQueue.cancelJob).toHaveBeenCalledTimes(1);
      expect(mediaJobQueue.cancelJob.mock.calls[0][0]).toBe('codex-newest');
    });

    it('POST /cancel (explicit jobId) cancels exactly that job and skips queuedAt selection', async () => {
      // When a jobId is provided, the route must cancel THAT job — even if a
      // newer queued job exists. This locks in that explicit selection wins
      // over the queuedAt fallback (writers-room "cancel this scene").
      mediaJobQueue.listJobs.mockReturnValueOnce([
        { id: 'newest', status: 'queued', queuedAt: '2026-05-05T08:30:00Z' },
        { id: 'middle', status: 'queued', queuedAt: '2026-05-05T08:20:00Z' },
        { id: 'oldest', status: 'running', queuedAt: '2026-05-05T08:00:00Z' },
      ]);
      const response = await request(app).post('/api/image-gen/cancel').send({ jobId: 'middle' });
      expect(response.status).toBe(200);
      expect(mediaJobQueue.cancelJob).toHaveBeenCalledTimes(1);
      expect(mediaJobQueue.cancelJob.mock.calls[0][0]).toBe('middle');
    });
  });

  // Explicit-target contract (#9932): a named id cancels that job or nothing —
  // it never degrades to bulk cancellation or to a different live job.
  describe('POST /cancel explicit-target contract', () => {
    it.each([
      ['array', []],
      ['object', {}],
      ['null', null],
      ['whitespace', '   '],
      ['number', 7],
    ])('rejects a %s jobId with 400 and cancels nothing', async (_label, jobId) => {
      // Validation runs before any job lookup, so no queue state is needed.
      const response = await request(app).post('/api/image-gen/cancel').send({ jobId });
      expect(response.status).toBe(400);
      expect(response.body.code).toBe('VALIDATION_ERROR');
      expect(mediaJobQueue.cancelJob).not.toHaveBeenCalled();
      expect(imageGen.cancelJob).not.toHaveBeenCalled();
      expect(imageGen.cancel).not.toHaveBeenCalled();
    });

    it('rejects a non-boolean all flag with 400', async () => {
      const response = await request(app).post('/api/image-gen/cancel').send({ all: 'yes' });
      expect(response.status).toBe(400);
      expect(mediaJobQueue.cancelJob).not.toHaveBeenCalled();
      expect(imageGen.cancel).not.toHaveBeenCalled();
    });

    it('409s for a known terminal job without touching live job B or any bulk method', async () => {
      mediaJobQueue.listJobs.mockReturnValueOnce([
        { id: 'running-b', kind: 'image', status: 'running' },
        { id: 'finished-a', kind: 'image', status: 'completed' },
      ]);
      const response = await request(app).post('/api/image-gen/cancel').send({ jobId: 'finished-a' });
      expect(response.status).toBe(409);
      expect(response.body.code).toBe('ALREADY_TERMINAL');
      expect(mediaJobQueue.cancelJob).not.toHaveBeenCalled();
      expect(imageGen.cancelJob).not.toHaveBeenCalled();
      expect(imageGen.cancel).not.toHaveBeenCalled();
    });

    it('404s for an unknown id after asking providers for that exact id only', async () => {
      mediaJobQueue.listJobs.mockReturnValueOnce([{ id: 'running-b', kind: 'image', status: 'running' }]);
      imageGen.cancelJob.mockReturnValueOnce(false);
      const response = await request(app).post('/api/image-gen/cancel').send({ jobId: 'expired-a' });
      expect(response.status).toBe(404);
      expect(response.body.code).toBe('NOT_FOUND');
      expect(imageGen.cancelJob).toHaveBeenCalledWith('expired-a');
      expect(mediaJobQueue.cancelJob).not.toHaveBeenCalled();
      expect(imageGen.cancel).not.toHaveBeenCalled();
    });

    it('cancels an exact legacy-provider job the queue does not know, never the bulk path', async () => {
      mediaJobQueue.listJobs.mockReturnValueOnce([]);
      imageGen.cancelJob.mockReturnValueOnce(true);
      const response = await request(app).post('/api/image-gen/cancel').send({ jobId: ' codex-1 ' });
      expect(response.status).toBe(200);
      expect(response.body.ok).toBe(true);
      expect(imageGen.cancelJob).toHaveBeenCalledWith('codex-1');
      expect(imageGen.cancel).not.toHaveBeenCalled();
    });

    it('maps a queue-reported ALREADY_TERMINAL race (job finished mid-request) to 409', async () => {
      mediaJobQueue.listJobs.mockReturnValueOnce([{ id: 'racing', kind: 'image', status: 'running' }]);
      mediaJobQueue.cancelJob.mockResolvedValueOnce({ ok: false, code: 'ALREADY_TERMINAL', status: 'completed', error: 'Job is already finishing' });
      const response = await request(app).post('/api/image-gen/cancel').send({ jobId: 'racing' });
      expect(response.status).toBe(409);
      expect(imageGen.cancel).not.toHaveBeenCalled();
    });
  });

  describe('FLUX.2 installer contract', () => {
    it('GET /setup/flux2-install reports status without starting an install', async () => {
      const { installFlux2Venv, isFlux2InstallSatisfied } = await import('../lib/pythonSetup.js');
      isFlux2InstallSatisfied.mockResolvedValueOnce(false);
      const response = await request(app).get('/api/image-gen/setup/flux2-install');
      expect(response.status).toBe(200);
      expect(response.body).toMatchObject({
        venvInstalled: false,
        expectedVenvPath: '/fake/flux2-venv',
      });
      expect(installFlux2Venv).not.toHaveBeenCalled();
    });

    it('POST /setup/flux2-install keeps the existing SSE completion contract', async () => {
      const response = await request(app).post('/api/image-gen/setup/flux2-install');
      expect(response.status).toBe(200);
      expect(response.text).toContain('"type":"complete"');
      expect(response.text).toContain('Already installed');
    });

    // The Install button appeared BECAUSE the per-model verdict probed that
    // model's own pipeline class; the installer's gate has to ask the same
    // question or it answers a real gap with "nothing to do".
    it('POST /setup/flux2-install scopes the already-installed gate to the selected model pipeline', async () => {
      const { isFlux2InstallSatisfied } = await import('../lib/pythonSetup.js');
      await request(app).post('/api/image-gen/setup/flux2-install?modelId=qwen-image-2.1');
      expect(isFlux2InstallSatisfied).toHaveBeenCalledWith('QwenImage21Pipeline');
    });

    // The client renders a stream that closes with no terminal frame as
    // "Connection to installer lost. Restart PortOS or try again." — a phantom
    // transport error that hides the real failure. installFlux2Venv emits its
    // own error frame; this is the route's backstop for a path that doesn't.
    it('POST /setup/flux2-install reports a silent installer failure instead of closing the stream bare', async () => {
      const { installFlux2Venv, isFlux2InstallSatisfied } = await import('../lib/pythonSetup.js');
      isFlux2InstallSatisfied.mockResolvedValueOnce(false);
      installFlux2Venv.mockReturnValueOnce({
        promise: Promise.resolve({ ok: false, stage: 'install' }),
        kill: vi.fn(),
      });

      const response = await request(app).post('/api/image-gen/setup/flux2-install');

      expect(response.status).toBe(200);
      expect(response.text).toContain('"type":"error"');
      expect(response.text).toContain('failed at the install stage');
    });

    it('POST /setup/flux2-install stays silent when the client cancelled the install', async () => {
      const { installFlux2Venv, isFlux2InstallSatisfied } = await import('../lib/pythonSetup.js');
      isFlux2InstallSatisfied.mockResolvedValueOnce(false);
      installFlux2Venv.mockReturnValueOnce({
        promise: Promise.resolve({ ok: false, stage: 'install', cancelled: true }),
        kill: vi.fn(),
      });

      const response = await request(app).post('/api/image-gen/setup/flux2-install');

      expect(response.text).not.toContain('"type":"error"');
    });

    it('does not start an install after the client disconnects during the health probe', async () => {
      const { installFlux2Venv, isFlux2InstallSatisfied } = await import('../lib/pythonSetup.js');
      let finishProbe;
      isFlux2InstallSatisfied.mockReturnValueOnce(new Promise((resolve) => { finishProbe = resolve; }));
      const server = await startLoopbackServer(app);
      const { port } = server.address();
      const clientRequest = httpRequest({
        host: '127.0.0.1',
        port,
        path: '/api/image-gen/setup/flux2-install',
        method: 'POST',
      });
      clientRequest.on('error', () => {});
      clientRequest.end();

      let serverClosed = false;
      try {
        await vi.waitFor(() => expect(isFlux2InstallSatisfied).toHaveBeenCalled());
        const closed = new Promise((resolve) => clientRequest.once('close', resolve));
        clientRequest.destroy();
        await closed;
        await vi.waitFor(() => expect(disconnectLifecycle.onDisconnect).toHaveBeenCalled());
        finishProbe(false);
        await closeLoopbackServer(server);
        serverClosed = true;
        expect(installFlux2Venv).not.toHaveBeenCalled();
      } finally {
        finishProbe?.(false);
        if (!serverClosed) await closeLoopbackServer(server);
      }
    });
  });

  describe('GET /setup/check (cache behavior)', () => {
    // Each test uses a unique pythonPath so the module-scope cache from one
    // test doesn't bleed into the next (vi.clearAllMocks() resets call counts
    // but not the cache Map).
    let probePythonHealth, createVenv;
    beforeEach(async () => {
      const mod = await import('../lib/pythonSetup.js');
      probePythonHealth = mod.probePythonHealth;
      createVenv = mod.createVenv;
      mockStat.mockReset();
      mockStat.mockResolvedValue({ mtimeMs: 1_700_000_000_000 });
    });

    it('returns the same payload on a cache hit and only spawns python once', async () => {
      const p = '/usr/bin/python3-cache-hit-test';
      const r1 = await request(app).get(`/api/image-gen/setup/check?pythonPath=${encodeURIComponent(p)}`);
      const r2 = await request(app).get(`/api/image-gen/setup/check?pythonPath=${encodeURIComponent(p)}`);
      expect(r1.status).toBe(200);
      expect(r2.status).toBe(200);
      expect(r1.body).toEqual(r2.body);
      expect(probePythonHealth).toHaveBeenCalledTimes(1);
    });

    it('busts the cache when the python interpreter mtime changes', async () => {
      const p = '/usr/bin/python3-mtime-test';
      mockStat.mockResolvedValueOnce({ mtimeMs: 1_700_000_000_000 });
      await request(app).get(`/api/image-gen/setup/check?pythonPath=${encodeURIComponent(p)}`);
      mockStat.mockResolvedValueOnce({ mtimeMs: 1_700_000_000_001 });
      await request(app).get(`/api/image-gen/setup/check?pythonPath=${encodeURIComponent(p)}`);
      expect(probePythonHealth).toHaveBeenCalledTimes(2);
    });

    it('does not cache when stat fails (broken / missing path)', async () => {
      const p = '/usr/bin/python3-stat-fail-test';
      mockStat.mockRejectedValue(new Error('ENOENT'));
      await request(app).get(`/api/image-gen/setup/check?pythonPath=${encodeURIComponent(p)}`);
      await request(app).get(`/api/image-gen/setup/check?pythonPath=${encodeURIComponent(p)}`);
      expect(probePythonHealth).toHaveBeenCalledTimes(2);
    });

    it('cache for distinct pythonPaths are independent', async () => {
      const p1 = '/usr/bin/python3-distinct-a';
      const p2 = '/opt/homebrew/bin/python3-distinct-b';
      await request(app).get(`/api/image-gen/setup/check?pythonPath=${encodeURIComponent(p1)}`);
      await request(app).get(`/api/image-gen/setup/check?pythonPath=${encodeURIComponent(p2)}`);
      // Two distinct paths → two probe spawns; both then cached for repeats.
      expect(probePythonHealth).toHaveBeenCalledTimes(2);
      await request(app).get(`/api/image-gen/setup/check?pythonPath=${encodeURIComponent(p1)}`);
      expect(probePythonHealth).toHaveBeenCalledTimes(2);
    });

    it('POST /setup/create-venv invalidates the base AND new venv cache entries', async () => {
      const base = '/usr/bin/python3-venv-test';
      // Warm cache for the base python.
      await request(app).get(`/api/image-gen/setup/check?pythonPath=${encodeURIComponent(base)}`);
      expect(probePythonHealth).toHaveBeenCalledTimes(1);

      // Create venv (mocked to return /fake/venv/python).
      const created = await request(app).post('/api/image-gen/setup/create-venv').send({ basePython: base });
      expect(created.status).toBe(200);
      expect(createVenv).toHaveBeenCalled();

      // Next probe of the base python re-spawns (cache busted).
      await request(app).get(`/api/image-gen/setup/check?pythonPath=${encodeURIComponent(base)}`);
      expect(probePythonHealth).toHaveBeenCalledTimes(2);
    });

    it('GET /setup/install reports setup status without starting pip', async () => {
      const { installPackages } = await import('../lib/pythonSetup.js');
      const p = '/usr/bin/python3-install-status-test';
      const status = await request(app).get(`/api/image-gen/setup/install?pythonPath=${encodeURIComponent(p)}&packages=mflux`);
      expect(status.status).toBe(200);
      expect(status.body).toMatchObject({ installed: ['mflux', 'mlx'], missing: [] });
      expect(installPackages).not.toHaveBeenCalled();
    });

    it('POST /setup/install completion invalidates the cache for that pythonPath', async () => {
      const p = '/usr/bin/python3-install-bust-test';
      // Warm cache.
      await request(app).get(`/api/image-gen/setup/check?pythonPath=${encodeURIComponent(p)}`);
      expect(probePythonHealth).toHaveBeenCalledTimes(1);

      // Run install (mocked installPackages resolves immediately).
      const installRes = await request(app).post(`/api/image-gen/setup/install?pythonPath=${encodeURIComponent(p)}&packages=mflux`);
      expect(installRes.status).toBe(200);

      // The next /setup/check must re-probe — the install just changed the
      // missing-packages list, and the SSE consumer re-runs /setup/check on
      // `complete` expecting fresh data.
      await request(app).get(`/api/image-gen/setup/check?pythonPath=${encodeURIComponent(p)}`);
      expect(probePythonHealth).toHaveBeenCalledTimes(2);
    });

    it('POST /setup/install rejects invalid packages with the standard error envelope', async () => {
      const p = '/usr/bin/python3-install-validation-test';
      const response = await request(app).post(`/api/image-gen/setup/install?pythonPath=${encodeURIComponent(p)}&packages=not-allowed`);
      expect(response.status).toBe(400);
      expect(response.body).toMatchObject({
        code: 'INSTALL_PACKAGE_NOT_ALLOWED',
        error: expect.stringContaining('not-allowed'),
      });
      expect(response.body.timestamp).toEqual(expect.any(Number));
    });

    it('single-flights package installs per interpreter without treating a completed POST body as a disconnect', async () => {
      const { installPackages } = await import('../lib/pythonSetup.js');
      let finishInstall;
      const pending = new Promise((resolve) => { finishInstall = resolve; });
      const kill = vi.fn();
      installPackages.mockReturnValueOnce({ promise: pending, kill });
      const p = '/usr/bin/python3-install-single-flight-test';
      const url = `/api/image-gen/setup/install?pythonPath=${encodeURIComponent(p)}&packages=mflux`;

      const first = request(app).post(url).then((response) => response);
      await vi.waitFor(() => expect(installPackages).toHaveBeenCalledTimes(1));
      expect(kill).not.toHaveBeenCalled();

      const second = await request(app).post(url);
      expect(second.text).toContain('Another package install is already running');
      expect(installPackages).toHaveBeenCalledTimes(1);

      finishInstall({ ok: true, code: 0 });
      expect((await first).status).toBe(200);
      expect(kill).not.toHaveBeenCalled();
    });

    it('write path sweeps expired entries so long-running processes do not accumulate', async () => {
      vi.useFakeTimers({ shouldAdvanceTime: true });
      try {
        const stale = '/usr/bin/python3-sweep-stale';
        const fresh = '/usr/bin/python3-sweep-fresh';
        // Warm the cache with one entry, then advance past the TTL.
        await request(app).get(`/api/image-gen/setup/check?pythonPath=${encodeURIComponent(stale)}`);
        vi.advanceTimersByTime(31_000);
        // A write for a different path triggers the sweep — stale entry drops.
        await request(app).get(`/api/image-gen/setup/check?pythonPath=${encodeURIComponent(fresh)}`);
        // A subsequent probe of the stale path re-spawns, confirming the entry
        // was actually removed (not merely TTL-bypassed).
        await request(app).get(`/api/image-gen/setup/check?pythonPath=${encodeURIComponent(stale)}`);
        // 3 spawns total: initial stale, fresh, post-sweep stale.
        expect(probePythonHealth).toHaveBeenCalledTimes(3);
      } finally {
        vi.useRealTimers();
      }
    });
  });

  describe('GET /setup/check (arch fields)', () => {
    // The route's archMismatch logic gates on `process.platform === 'darwin'` —
    // override it so the assertions run identically on Linux CI and a dev Mac.
    let restorePlatform = () => {};
    let probePythonHealth, detectArm64Python;

    beforeEach(async () => {
      restorePlatform = pinPlatform('darwin');
      const mod = await import('../lib/pythonSetup.js');
      probePythonHealth = mod.probePythonHealth;
      detectArm64Python = mod.detectArm64Python;
      mockStat.mockReset();
      mockStat.mockResolvedValue({ mtimeMs: 1_700_000_000_000 });
    });

    afterEach(() => {
      restorePlatform();
      hostArchHolder.value = 'arm64';
    });

    it('exposes hostArch + archMismatch + suggestedArm64Python on matched arch', async () => {
      const r = await request(app).get(`/api/image-gen/setup/check?pythonPath=${encodeURIComponent('/arch-fields-match')}`);
      expect(r.status).toBe(200);
      expect(r.body).toMatchObject({
        hostArch: 'arm64',
        archMismatch: false,
        suggestedArm64Python: null,
        interpreterArch: 'arm64',
      });
    });

    it('flips archMismatch true and includes the suggested arm64 python on an x86_64 interpreter', async () => {
      probePythonHealth.mockResolvedValueOnce({
        installed: [], missing: [], missingPip: [],
        externallyManaged: false, interpreterArch: 'x86_64',
      });
      detectArm64Python.mockResolvedValueOnce('/opt/homebrew/bin/python3');
      const r = await request(app).get(`/api/image-gen/setup/check?pythonPath=${encodeURIComponent('/arch-fields-x86')}`);
      expect(r.status).toBe(200);
      expect(r.body.archMismatch).toBe(true);
      expect(r.body.suggestedArm64Python).toBe('/opt/homebrew/bin/python3');
    });

    it('returns suggestedArm64Python null when no arm64 interpreter is available to suggest', async () => {
      probePythonHealth.mockResolvedValueOnce({
        installed: [], missing: [], missingPip: [],
        externallyManaged: false, interpreterArch: 'x86_64',
      });
      detectArm64Python.mockResolvedValueOnce(null);
      const r = await request(app).get(`/api/image-gen/setup/check?pythonPath=${encodeURIComponent('/arch-fields-no-arm64')}`);
      expect(r.status).toBe(200);
      expect(r.body.archMismatch).toBe(true);
      expect(r.body.suggestedArm64Python).toBeNull();
    });

    it('does not flag archMismatch on non-darwin even when interpreter arch differs', async () => {
      pinPlatform('linux'); // afterEach restores the pristine descriptor
      probePythonHealth.mockResolvedValueOnce({
        installed: [], missing: [], missingPip: [],
        externallyManaged: false, interpreterArch: 'x86_64',
      });
      const r = await request(app).get(`/api/image-gen/setup/check?pythonPath=${encodeURIComponent('/arch-fields-linux')}`);
      expect(r.status).toBe(200);
      expect(r.body.archMismatch).toBe(false);
      expect(r.body.suggestedArm64Python).toBeNull();
    });

    it('does not flag archMismatch on darwin/x86_64 hosts (Intel macs) — only arm64 hosts care about mlx wheels', async () => {
      hostArchHolder.value = 'x86_64';
      probePythonHealth.mockResolvedValueOnce({
        installed: [], missing: [], missingPip: [],
        externallyManaged: false, interpreterArch: 'x86_64',
      });
      const r = await request(app).get(`/api/image-gen/setup/check?pythonPath=${encodeURIComponent('/arch-fields-intel-mac')}`);
      expect(r.status).toBe(200);
      expect(r.body.hostArch).toBe('x86_64');
      expect(r.body.archMismatch).toBe(false);
      expect(r.body.suggestedArm64Python).toBeNull();
      expect(detectArm64Python).not.toHaveBeenCalled();
    });
  });

  // SynthID-defeat regen (issue #912).
  describe('GET /api/image-gen/regen/availability', () => {
    it('reports the local FLUX backend as available when the venv is healthy', async () => {
      // isFlux2VenvHealthy is mocked to true and the real model registry
      // carries FLUX.2 models, so a flux-venv model resolves.
      const response = await request(app).get('/api/image-gen/regen/availability');
      expect(response.status).toBe(200);
      expect(response.body.available).toBe(true);
      expect(typeof response.body.modelId).toBe('string');
    });

    it('carries the strength slider bounds for the lightbox control', async () => {
      const response = await request(app).get('/api/image-gen/regen/availability');
      expect(typeof response.body.strengthMin).toBe('number');
      expect(typeof response.body.strengthMax).toBe('number');
      expect(typeof response.body.strengthDefault).toBe('number');
      // Floor is a small positive value (strength 0 is the degenerate
      // ignore-the-init-image case), and the default sits within the bounds.
      expect(response.body.strengthMin).toBeGreaterThan(0);
      expect(response.body.strengthDefault).toBeGreaterThanOrEqual(response.body.strengthMin);
      expect(response.body.strengthDefault).toBeLessThanOrEqual(response.body.strengthMax);
    });

    it('threads a named source image’s model into the availability pick so the reported model matches the regen (issue #2036)', async () => {
      const resolveGallerySpy = vi.spyOn(fileUtils, 'resolveGalleryImage')
        .mockReturnValueOnce('/fake/gallery/source.png');
      imageGen.local.readImageSidecar.mockResolvedValueOnce({
        path: '', metadata: { modelId: 'flux2-klein-9b' },
      });
      const availSpy = vi.spyOn(regen, 'getRegenAvailability')
        .mockResolvedValueOnce({ available: true, modelId: 'flux2-klein-9b', strengthMin: 0.02, strengthMax: 0.6, strengthDefault: 0.25 });

      // A path-prefixed query value must never reach the sidecar read raw — the
      // sidecar is read by the RESOLVED gallery path's basename (traversal-safe).
      const response = await request(app).get('/api/image-gen/regen/availability?filename=..%2F..%2Fsource.png');

      expect(response.status).toBe(200);
      expect(response.body.modelId).toBe('flux2-klein-9b');
      expect(imageGen.local.readImageSidecar).toHaveBeenCalledWith('source.png');
      // The source model must reach the availability resolver, or the dialog can
      // name a different model than the POST enqueues on a multi-model install.
      expect(availSpy).toHaveBeenCalledWith({ sourceModelId: 'flux2-klein-9b' });

      resolveGallerySpy.mockRestore();
      availSpy.mockRestore();
    });
  });

  describe('POST /api/image-gen/:filename/regenerate', () => {
    it('rejects an out-of-range strength before touching the filesystem (400)', async () => {
      const response = await request(app)
        .post('/api/image-gen/whatever.png/regenerate')
        .send({ strength: 0.95 }); // max is 0.6
      expect(response.status).toBe(400);
      expect(mediaJobQueue.enqueueJob).not.toHaveBeenCalled();
    });

    it('404s when the source image is not in the gallery', async () => {
      const response = await request(app)
        .post('/api/image-gen/does-not-exist.png/regenerate')
        .send({});
      expect(response.status).toBe(404);
      expect(mediaJobQueue.enqueueJob).not.toHaveBeenCalled();
    });

    it('enqueues a regen job and returns the queued response shape', async () => {
      // Arrange — stand in for the real filesystem and regen helpers.
      const resolveGallerySpy = vi.spyOn(fileUtils, 'resolveGalleryImage')
        .mockReturnValueOnce('/fake/gallery/source.png');
      imageGen.local.readImageSidecar.mockResolvedValueOnce({
        path: '/fake/gallery/source.png.json',
        metadata: { modelId: 'flux-dev', prompt: 'a robot' },
      });
      const readDimsSpy = vi.spyOn(regen, 'readImageDimensions')
        .mockResolvedValueOnce({ width: 1024, height: 1024 });
      const resolveBackendSpy = vi.spyOn(regen, 'resolveRegenBackend')
        .mockResolvedValueOnce({ available: true, model: { id: 'flux-dev' }, pythonPath: '/fake/venv/python' });
      const buildParamsSpy = vi.spyOn(regen, 'buildRegenParams')
        .mockReturnValueOnce({ kind: 'image', regenJob: true, filename: 'source.png' });
      mediaJobQueue.enqueueJob.mockReturnValueOnce({ jobId: 'regen-job-001', position: 1, status: 'queued' });

      const response = await request(app)
        .post('/api/image-gen/source.png/regenerate')
        .send({ strength: 0.25 });

      expect(response.status).toBe(200);
      // Response must carry the queuedImageResponse shape: jobId, generationId,
      // filename, path, mode, model, status, position.
      expect(response.body.jobId).toBe('regen-job-001');
      expect(response.body.generationId).toBe('regen-job-001');
      expect(response.body.filename).toBe('regen-job-001.png');
      expect(response.body.mode).toBe('local');
      expect(response.body.model).toBe('flux-dev');
      expect(response.body.status).toBe('queued');
      expect(mediaJobQueue.enqueueJob).toHaveBeenCalledTimes(1);
      expect(buildParamsSpy).toHaveBeenCalledWith(expect.objectContaining({ strength: 0.25 }));

      resolveGallerySpy.mockRestore();
      readDimsSpy.mockRestore();
      resolveBackendSpy.mockRestore();
      buildParamsSpy.mockRestore();
    });

    // Annotation re-render (issue #2036 phase 2)
    it('400s an annotated re-render when no annotation has been saved', async () => {
      const resolveGallerySpy = vi.spyOn(fileUtils, 'resolveGalleryImage')
        .mockReturnValueOnce('/fake/gallery/source.png');
      const sketchPathSpy = vi.spyOn(mediaSketches, 'getSketchPngPath')
        .mockResolvedValueOnce(null);

      const response = await request(app)
        .post('/api/image-gen/source.png/regenerate')
        .send({ annotated: true });

      expect(response.status).toBe(400);
      expect(response.body.code).toBe('NO_ANNOTATION');
      expect(mediaJobQueue.enqueueJob).not.toHaveBeenCalled();

      resolveGallerySpy.mockRestore();
      sketchPathSpy.mockRestore();
    });

    it('400s an annotated re-render on the light method (init image needs the GPU pass)', async () => {
      const resolveGallerySpy = vi.spyOn(fileUtils, 'resolveGalleryImage')
        .mockReturnValueOnce('/fake/gallery/source.png');

      const response = await request(app)
        .post('/api/image-gen/source.png/regenerate')
        .send({ annotated: true, method: 'light' });

      expect(response.status).toBe(400);
      expect(response.body.code).toBe('VALIDATION_ERROR');
      expect(mediaJobQueue.enqueueJob).not.toHaveBeenCalled();

      resolveGallerySpy.mockRestore();
    });

    it('stages the flattened annotation into an init-image root the runner accepts, at the higher default strength', async () => {
      // A real flattened-sketch file for the route to copy — the fix stages a
      // snapshot into PATHS.imageRefs, and the runner's resolveImageInputPath
      // must accept the staged path (media-sketches/ is NOT an approved root).
      const srcSketch = pathJoin(tmpdir(), `annot-src-${Date.now()}.png`);
      await writeFile(srcSketch, Buffer.from('89504e470d0a1a0a', 'hex'));

      const resolveGallerySpy = vi.spyOn(fileUtils, 'resolveGalleryImage')
        .mockReturnValueOnce('/fake/gallery/source.png');
      const sketchPathSpy = vi.spyOn(mediaSketches, 'getSketchPngPath')
        .mockResolvedValueOnce(srcSketch);
      imageGen.local.readImageSidecar.mockResolvedValueOnce({
        path: '/fake/gallery/source.png.json',
        metadata: { modelId: 'flux-dev', prompt: 'a robot' },
      });
      const readDimsSpy = vi.spyOn(regen, 'readImageDimensions')
        .mockResolvedValueOnce({ width: 1024, height: 1024 });
      const resolveBackendSpy = vi.spyOn(regen, 'resolveRegenBackend')
        .mockResolvedValueOnce({ available: true, model: { id: 'flux-dev' }, pythonPath: '/fake/venv/python' });
      // buildRegenParams is NOT mocked — assert the REAL params the route enqueues.
      mediaJobQueue.enqueueJob.mockReturnValueOnce({ jobId: 'annot-job-001', position: 1, status: 'queued' });

      const response = await request(app)
        .post('/api/image-gen/source.png/regenerate')
        .send({ annotated: true }); // no explicit strength → annotated default

      expect(response.status).toBe(200);
      expect(response.body.jobId).toBe('annot-job-001');
      const [enqueued] = mediaJobQueue.enqueueJob.mock.calls;
      const params = enqueued[0].params;
      expect(params.annotatedRegen).toBe(true);
      expect(params.initImageStrength).toBe(regen.REGEN_ANNOTATED_STRENGTH_DEFAULT);
      // Regression guard for the silently-dropped-init-image bug: the staged
      // path must resolve under an approved image-input root, AND carry the
      // `init-<uuid>` name that imageRefsGc.js sweeps (so a canceled re-render
      // doesn't leak the snapshot).
      expect(params.initImagePath).toMatch(/[/\\]image-refs[/\\]init-[0-9a-f-]+\.png$/i);
      expect(fileUtils.resolveImageInputPath(params.initImagePath)).not.toBeNull();

      await rm(params.initImagePath, { force: true });
      await rm(srcSketch, { force: true });
      resolveGallerySpy.mockRestore();
      sketchPathSpy.mockRestore();
      readDimsSpy.mockRestore();
      resolveBackendSpy.mockRestore();
    });
  });

  describe('POST /api/image-gen/generate — federated media provider', () => {
    it('submits to the selected peer and keeps the prompt inside the versioned marker', async () => {
      const response = await request(app).post('/api/image-gen/generate').send({
        prompt: 'a lighthouse at dusk',
        modelId: 'dev',
        width: 512,
        height: 512,
        seed: 42,
        mediaProviderPeerId: federatedPeerId,
      });

      expect(response.status).toBe(200);
      expect(response.body).toMatchObject({
        jobId: 'mock-image-job',
        // No local backend renders this, so `mode` must not name one.
        mode: null,
        model: 'dev',
        mediaProviderPeerId: federatedPeerId,
      });
      expect(prepareRemoteMediaJob).toHaveBeenCalledWith({
        peerId: federatedPeerId,
        kind: 'image',
        request: {
          kind: 'image',
          engine: 'local',
          modelId: 'dev',
          prompt: 'a lighthouse at dusk',
          width: 512,
          height: 512,
          seed: 42,
        },
        // A text-to-image render carries none, but the field is always passed —
        // an empty list and an absent one must read the same to the submitter.
        inputAssets: [],
      });

      const [{ params }] = mediaJobQueue.enqueueJob.mock.calls[0];
      // The conditioning prompt rides only inside the versioned marker, and the
      // routing fields never reach the queue. enqueueJob owns blanking the
      // local render fields on top of this (#4683) — its own suites cover that,
      // and enqueueJob is mocked here.
      expect(params.remoteMedia.request.prompt).toBe('a lighthouse at dusk');
      expect(params.remoteMedia.request.modelId).toBe('dev');
      expect(params).not.toHaveProperty('mediaProviderPeerId');
      expect(params).not.toHaveProperty('mediaProviderEngine');
    });

    it('requires an explicit provider model instead of falling back to a local default', async () => {
      const response = await request(app).post('/api/image-gen/generate').send({
        prompt: 'a lighthouse at dusk',
        mediaProviderPeerId: federatedPeerId,
      });

      expect(response.status).toBe(400);
      expect(response.body.code).toBe('MEDIA_PROVIDER_MODEL_REQUIRED');
      expect(mediaJobQueue.enqueueJob).not.toHaveBeenCalled();
    });

    it('refuses a federated render that carries conditioning the wire cannot take', async () => {
      const response = await request(app).post('/api/image-gen/generate').send({
        prompt: 'a lighthouse at dusk',
        modelId: 'dev',
        loraFilenames: ['style.safetensors'],
        mediaProviderPeerId: federatedPeerId,
      });

      expect(response.status).toBe(400);
      expect(response.body.code).toBe('MEDIA_PROVIDER_INPUT_UNSUPPORTED');
      expect(response.body.error).toMatch(/LoRA weights/);
      expect(mediaJobQueue.enqueueJob).not.toHaveBeenCalled();
      expect(prepareRemoteMediaJob).not.toHaveBeenCalled();
    });
  });

});