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

59.5 KB
Raw Blame
import { getRunwayModelCatalog } from '../services/runwayModelCatalog.js';
import { assertCatalogIdentityWritable } from '../services/catalogDB/identityAccess.js';
/**
 * Image Generation Routes — works against the external SD API, local mflux,
 * or the Codex CLI built-in image_gen tool, depending on settings.imageGen.mode
 * (or the per-request `mode` override).
 *
 * Generic endpoints (status, generate, avatar) go through the dispatcher.
 * Async-mode endpoints (events SSE, cancel) also go through the dispatcher
 * which routes the jobId to whichever provider owns it. Local-only endpoints
 * (gallery, loras, models, delete) target the local module directly.
 */

import { createImageGalleryHandlers } from './imageGalleryRead.js';
import { Router } from 'express';
import { z } from 'zod';
import { asyncHandler, ServerError, failValidation } from '../lib/errorHandler.js';
import {
  validateRequest, modelDownloadQuerySchema, modelDownloadParamsSchema, imageCancelBodySchema, imageVisibilityBodySchema, imageEdgeSchema, refineImagePixelCap, PIXEL_CAP_MESSAGE,
} from '../lib/validation.js';
import { optionalUploadFields, optionalUpload } from '../lib/multipart.js';
import * as imageGen from '../services/imageGen/index.js';
import { local, IMAGE_GEN_MODE, IMAGE_GEN_MODES } from '../services/imageGen/index.js';
import { maxInputImages, resolveCloudProviderConfig } from '../services/imageGen/cloudProviderConfig.js';
import setupRouter, { streamMossAction } from './imageGenSetup.js';
import { usesMossSwift } from '../lib/imageRuntimeRemedies.js';
import { downloadMossWeights, mossModelCacheStatus, verifyMossWeights, repairMossWeights } from '../services/imageGen/mossWeights.js';
import { enqueueJob, attachSseClient as attachQueueSseClient, cancelJob, listJobs } from '../services/mediaJobQueue/index.js';
import { recordUserAction } from '../services/userActions.js';
import { getImageModels, requiredReposForModel } from '../lib/mediaModels.js';
import { inspectModelCache, verifyModelCache, repairModelCache, aggregateVerifies } from '../lib/hfCache.js';
import { startHfDownloadStream } from '../services/hfDownloadStream.js';
import { PATHS, ensureDir, resolveGalleryImage, unlinkGuarded, copyFileGuarded } from '../lib/fileUtils.js';
import { prepareGenerateParams, resolveLocalImageModel, selectLocalImageModelFromSettings } from '../services/imageGen/prepareParams.js';
import { applyImageClean, applyWatermarkRemoval, applyLightRegenVariant } from '../services/imageGen/variants.js';
import { applyFilmLookBake } from '../services/imageGen/filmLookBake.js';
import { previewImagePrompt } from '../services/imageGen/promptPreview.js';
import { filmLookBakeSchema } from '../lib/filmLookValidation.js';
import { join, basename } from 'node:path';
import { STYLE_PRESETS } from '../lib/writersRoomStylePresets.js';
import {
  resolveRegenBackend, getRegenAvailability, readImageDimensions, buildRegenParams,
  REGEN_STRENGTH_MIN, REGEN_STRENGTH_MAX,
  resolveRegenStrengthDefault, REGEN_ANNOTATED_STRENGTH_DEFAULT,
} from '../services/imageGen/regen.js';
import { getSketchPngPath, isValidKey as isValidSketchKey } from '../services/mediaSketches.js';
import { itemKey } from '../lib/mediaItemKey.js';
import { deleteGalleryImage } from '../services/galleryImageDeletion.js';
import * as characterService from '../services/character.js';
import { randomUUID } from 'crypto';
import { buildUniverseRunTag } from '../services/universeRunTag.js';
import { getSettings } from '../services/settings.js';
import { prepareRemoteMediaJob } from '../services/federatedMedia/remoteSubmission.js';
import { collectRemoteInputAssets } from '../services/federatedMedia/inputAssets.js';
import { buildFederatedMediaRequest } from '../lib/federatedMediaRequest.js';
import { asFableLoomRenderSettings, inspectEpisodeProductionOrder } from '../lib/fableLoomProduction.js';
import { attachNodeImage, getLoom } from '../services/fableLoom/records.js';
import {
  compileFableLoomVisualRequest, fableLoomImageCapabilities,
} from '../services/fableLoom/visualConditioning.js';
import { loraCompatKey } from '../lib/runners.js';
import { EFFORT_LEVELS } from '../lib/providerModels.js';
import { promptAdditionsSchema } from '../lib/modelInput.js';

const router = Router();

router.get('/runway-models', asyncHandler(async (_req, res) => {
  res.json(await getRunwayModelCatalog());
}));
router.post('/runway-models/refresh', asyncHandler(async (_req, res) => {
  res.json(await getRunwayModelCatalog({ refresh: true }));
}));

const routeSource = (req) => ({ route: `${req.baseUrl}${req.route?.path ?? ''}`, method: req.method });

// Event-only pointer: job id in `target`, never the generation prompt (#5596).
async function enqueueLoggedImage(req, job) {
  // Selective section revision (#9011): checked as the LAST step before the
  // actual queue write — every branch that reaches this helper has already
  // done its own staging/provider resolution, so this is as close to the
  // cancel/kickoff race as a request can get. A no-op when the tag carries no
  // revisionId; deferred import since only this rare path needs the revision
  // service's closure.
  if (job.params?.musicVideo?.revisionId) {
    const { assertRevisionOpen } = await import('../services/musicVideo/revisionService.js');
    await assertRevisionOpen(job.params.musicVideo.projectId, job.params.musicVideo.revisionId, { sceneId: job.params.musicVideo.sceneId, kind: 'image' });
  }
  const queued = await enqueueJob(job);
  try {
    const happenedAt = new Date().toISOString();
    await recordUserAction({
      type: 'media.image.enqueue',
      actor: 'user',
      target: queued.jobId,
      summary: 'enqueued image job',
      payload: { jobId: queued.jobId },
      source: routeSource(req),
      happenedAt,
      dedupeKey: `media.image.enqueue:${queued.jobId}`,
    });
  } catch (error) {
    // Ledger is a side effect — the job is already queued.
    console.error(`❌ Failed to record media.image.enqueue: ${error.message}`);
  }
  return queued;
}


// Shared validation limits. MAX_REFERENCE_IMAGES must stay in sync with the
// number of `referenceImageN` upload field names below.
const MAX_PROMPT_LENGTH = 32000;
const MAX_LORAS = 8;
const MAX_REFERENCE_IMAGES = 16;
const updatePromptSchema = z.object({ prompt: z.string().max(MAX_PROMPT_LENGTH) });
const galleryImageFilenameSchema = (label) => z.string().max(256)
  .regex(/^[^/\\]+\.(png|jpg|jpeg|webp)$/i, `${label} must be a basename ending in png/jpg/jpeg/webp`);

router.get('/style-presets', (_req, res) => res.json(STYLE_PRESETS));

// Rejected, never stripped: model input is not silently modified. spawn() also throws on NUL.
const noNulPrompt = z.string().max(MAX_PROMPT_LENGTH)
  .refine((v) => !v.includes('\0'), { message: 'Prompt may not contain a NUL character' });

const generateSchema = z.object({
  promptAdditions: promptAdditionsSchema,
  // Empty prompt allowed — i2i / edit / unconditional generation don't require
  // one. The multipart FormData builder drops empty-string fields, so an empty
  // prompt arrives as `undefined`; default it to '' rather than rejecting.
  prompt: noNulPrompt.optional().default(''),
  negativePrompt: noNulPrompt.optional(),
  // Per-request backend override. If omitted, the dispatcher uses
  // `imageGen.mode` from settings.json.
  mode: z.enum(IMAGE_GEN_MODES).optional(),
  modelId: z.string().max(64).optional(),
  // Per-render Codex reasoning effort. Other image backends ignore this
  // provider-specific preference, preserving the story pin across a backend
  // switch without inventing a second image request shape.
  effort: z.enum(EFFORT_LEVELS).optional(),
  // Per-render override of a cloud CLI's session model, replacing the saved
  // `settings.imageGen.<mode>.model` for this one queue item. Deliberately NOT
  // `modelId`: that field carries a *local* model id (`dev`, `schnell`), and a
  // form that keeps it populated while the user flips to a cloud backend would
  // otherwise hand the CLI an id it rejects. Ignored by providers whose spec
  // has no model knob (grok). Same charset as the provider-side MODEL_ID_RE so
  // a typo'd id fails validation here rather than at spawn time.
  cloudModel: z.string().max(64).regex(/^[A-Za-z0-9][A-Za-z0-9._:/-]*$/, 'invalid cloud model id').optional(),
  width: imageEdgeSchema,
  height: imageEdgeSchema,
  steps: z.number().int().min(1).max(150).optional(),
  cfgScale: z.number().min(0).max(30).optional(),
  guidance: z.number().min(0).max(30).optional(),
  seed: z.number().int().min(0).optional(),
  // mflux supports 3/4/5/6/8 bit quantization; 8 is the default.
  quantize: z.union([z.literal(3), z.literal(4), z.literal(5), z.literal(6), z.literal(8), z.literal('3'), z.literal('4'), z.literal('5'), z.literal('6'), z.literal('8')]).optional(),
  // Filenames only (basenames) — server resolves against PATHS.loras and
  // applies the prefix-check. Old payloads sent absolute server paths
  // (`loraPaths`); accept both for back-compat with stored gallery sidecars.
  loraFilenames: z.array(z.string().max(256).regex(/^[^/\\]+$/, 'lora filename must not contain path separators')).max(MAX_LORAS).optional(),
  loraPaths: z.array(z.string().max(512)).max(MAX_LORAS).optional(),
  loraScales: z.array(z.number().min(0).max(2)).max(MAX_LORAS).optional(),
  // i2i: pick an existing gallery image (basename) as the init image. If
  // initImage was uploaded via multipart, this is ignored in favor of the
  // upload. Strength: 0.0 = ignore source, 1.0 = max influence.
  initImageFile: galleryImageFilenameSchema('init image').optional(),
  initImageStrength: z.number().min(0).max(1).optional(),
  // Multi-reference image conditioning. Up to 4 reference images are uploaded
  // as separate multipart fields `referenceImage1` … `referenceImage4`, or
  // named from the existing gallery through JSON `referenceImageFiles`;
  // `referenceStrengths` is a parallel array of weights (0.0 = ignore the
  // reference, 1.0 = full influence), ordered as named files then uploads.
  // Uploaded file presence is enforced at the upload layer, and the route
  // pairs all surviving slots with their strengths positionally. Strengths are honored
  // numerically only by local FLUX.2; the cloud CLIs expose no per-reference
  // weight, so they receive the paths alone.
  referenceImageFiles: z.array(galleryImageFilenameSchema('reference image')).max(MAX_REFERENCE_IMAGES).optional(),
  referenceStrengths: z.array(z.number().min(0).max(1)).max(MAX_REFERENCE_IMAGES).optional(),
  // Per-render override of the cleaners. When omitted, the route inherits
  // from `settings.imageGen.{mode}.{cleanC2PA,denoise}`. Explicit booleans
  // here force the value for this one render. Legacy `autoClean` is still
  // accepted (mapped to both flags) so older clients keep working through
  // the deprecation window.
  cleanC2PA: z.boolean().optional(),
  denoise: z.boolean().optional(),
  autoClean: z.boolean().optional(),
  // Optional universe-collection target. When present, the route resolves the
  // universe's media collection server-side and tags the queued job so
  // `universeBuilderCollectionHook` files the finished render into that
  // collection — the same auto-filing path batch renders and character
  // reference sheets use. The client passes only the universe identity (never
  // a collectionId — that's server-resolved), so the front-end does no
  // collection bookkeeping. The base-style probe (StyleProbeImage) and the
  // Universe canon section-local renders (#1395) are the callers; JSON-only
  // (the multipart ImageGen page never sends it).
  universeRun: z.object({
    universeId: z.string().min(1).max(200),
    universeName: z.string().min(1).max(200),
    label: z.string().max(200).optional(),
    category: z.string().max(64).optional(),
    // Section-local canon renders (#1395) tag the target entry so the
    // completion hook durably appends the render to its `imageRefs[]` even
    // after the originating page unmounts — converging these renders onto the
    // same durable path batch renders use. Shape mirrors the batch path's
    // entryRef (server/services/universeBuilder.js `ENTRY_REF_KIND`).
    entryRef: z.object({
      kind: z.enum(['canon', 'variation', 'sheet']),
      kindKey: z.string().min(1).max(64).optional(),
      categoryKey: z.string().min(1).max(64).optional(),
      id: z.string().min(1).max(200),
    }).refine(
      // Each kind needs its locating key, else appendEntryImageRef silently
      // no-ops: canon→kindKey, variation→categoryKey (sheet needs neither).
      (r) => (r.kind === 'canon' ? !!r.kindKey : r.kind === 'variation' ? !!r.categoryKey : true),
      { message: 'entryRef requires its locating key (canon→kindKey, variation→categoryKey)' },
    ).optional(),
  }).optional(),
  // Writers-Room storyboard scene render (#1363). When present, the mediaJobQueue
  // completion hook (`writersRoomSceneImageHook`) files the finished render onto
  // the analysis snapshot's `sceneImages[sceneId]` AND mirrors it into the work's
  // auto-collection — durably, even if the editor unmounted mid-render (the
  // "navigated away → image never attached" failure mode the synchronous attach
  // suffered). Only the async local/Codex lanes ride the queue this hook listens
  // to; the synchronous external SD-API lane still attaches via the scene-image
  // route. The scene prompt is read from the job's own `prompt` param, so the tag
  // carries only the destination identity. JSON-only (the multipart ImageGen page
  // never sends it).
  writersRoom: z.object({
    workId: z.string().min(1).max(200),
    analysisId: z.string().min(1).max(200),
    sceneId: z.string().min(1).max(200),
  }).optional(),
  // FableLoom scene render. When present, the mediaJobQueue completion hook
  // (`fableLoomSceneImageHook`) files the finished render onto that loom
  // episode's scene node — durably, even if the editor unmounted mid-render.
  // Only the async local/Codex lanes ride the queue; the synchronous external
  // SD-API lane is attached directly by this route after generation. Rides
  // into job.params untouched via `...params`. JSON-only.
  fableLoom: z.object({
    loomId: z.string().min(1).max(200),
    episodeId: z.string().min(1).max(200),
    nodeId: z.string().min(1).max(200),
    role: z.literal('image').optional(),
  }).optional(),
  // Music Video scene reference-frame render (#1760 Phase 1b). When present, the
  // mediaJobQueue completion hook (`musicVideoSceneImageHook`) appends the
  // finished render to the project scene's takes (#8965) — durably, even if the
  // director board unmounted mid-render. Only the async local/Codex lanes ride
  // the queue this hook listens to; the synchronous external SD-API lane returns
  // the filename inline and the client adds it through the scene takes route. Rides
  // into job.params untouched via `...params` (like `writersRoom`). JSON-only.
  musicVideo: z.object({
    projectId: z.string().min(1).max(200),
    sceneId: z.string().min(1).max(200),
    // Selective section revision (#9011): see the matching comment on the
    // video route's musicVideo schema (server/routes/videoGen.js).
    revisionId: z.string().min(1).max(200).optional(),
    // #11173: 'end' files the render as the scene's style-break end frame
    // (an `endImage` take) instead of its start frame.
    slot: z.enum(['end']).optional(),
    // #11317: the prompt is the director's text; the server composes the still's
    // prompt and lists each block it adds. `fromFrame` reworks the first reference
    // image (a picked frame); `refine` makes the prompt an edit instruction for it.
    compose: z.boolean().optional(),
    fromFrame: z.boolean().optional(),
    refine: z.boolean().optional(),
  }).optional(),
  // File the render into this music video's media collection even when no shot
  // keeps it (sheets, tests, alternates): musicVideoCollectionHook for the
  // queued lanes, inline below for the synchronous one. Collection only; the
  // render itself is unchanged.
  musicVideoProjectId: z.string().min(1).max(200).optional(),
  // Durable catalog attach (#1359). When present, the mediaJobQueue completion
  // hook (catalogImageAttachHook) files the finished render onto this catalog
  // ingredient even if the page that started the render has since unmounted —
  // so a long queued local/Codex render is no longer lost to navigation.
  // `catalogMediaKind` forces portrait/reference; omitted = auto (first image →
  // portrait, later → reference, mirroring the client's optimistic path). Only
  // the async (local/codex) lanes need this — the synchronous external SD-API
  // path returns the filename to the client, which attaches it directly.
  catalogIngredientId: z.string().min(1).max(200).optional(),
  catalogMediaKind: z.enum(['portrait', 'reference']).optional(),
  // Federated media provider (#4348). When set, the render is submitted to
  // THIS registered peer instead of running on local hardware. Server-validated
  // against the per-peer allowlist — an agent cannot route work to an arbitrary
  // peer by naming one here. mediaProviderEngine names the provider-side
  // engine within that allowlist; local image/video generation registers as
  // 'local', which is the only engine a provider can currently advertise.
  // What may cross to a peer, and what may not:
  // docs/decisions/2026-08-20-federated-visual-prompts.md
  mediaProviderPeerId: z.string().uuid().optional(),
  mediaProviderEngine: z.string().trim().min(1).max(80).optional(),
}).refine(refineImagePixelCap, { message: PIXEL_CAP_MESSAGE, path: ['width'] });

// JSON callers (SDAPI bridge, avatar route, the Imagine page's old payload
// shape) skip the parser entirely; FormData callers get req.file + string
// req.body that coerceFormFields() converts before Zod validation.
// Only the formats mflux can decode — keep this in sync with the extension
// allowlist below so the route never silently relabels (e.g. HEIC) bytes
// as ".png".
const ACCEPTED_INIT_IMAGE_MIME = new Set(['image/png', 'image/jpeg', 'image/webp']);
const _MIME_TO_EXT = { 'image/png': '.png', 'image/jpeg': '.jpg', 'image/webp': '.webp' };

// Multi-reference editing accepts up to 4 references on dedicated field names.
// The legacy single `initImage` upload (mflux i2i) stays on its own slot so a
// FLUX.2 multi-ref upload and an mflux i2i upload don't collide.
const REFERENCE_IMAGE_FIELDS = Array.from({ length: MAX_REFERENCE_IMAGES }, (_, i) => `referenceImage${i + 1}`);
const IMAGE_UPLOAD_FIELDS = ['initImage', ...REFERENCE_IMAGE_FIELDS];

const imageGenUploads = optionalUploadFields(IMAGE_UPLOAD_FIELDS, {
  fileFilter: (_req, file, cb) => cb(null, ACCEPTED_INIT_IMAGE_MIME.has((file.mimetype || '').toLowerCase())),
});

// Numerics arrive as strings from FormData — coerce before Zod validation.
// `referenceStrengths` is a repeated key (one per slot), which arrives as a
// string OR an array of strings; coerce element-wise so Zod sees numbers.
function coerceFormFields(body) {
  const numericFields = ['width', 'height', 'steps', 'cfgScale', 'guidance', 'seed', 'initImageStrength'];
  for (const f of numericFields) {
    if (typeof body[f] === 'string' && body[f] !== '') body[f] = Number(body[f]);
  }
  if (typeof body.quantize === 'string' && /^\d+$/.test(body.quantize)) body.quantize = Number(body.quantize);
  if (body.referenceStrengths != null) {
    const raw = Array.isArray(body.referenceStrengths) ? body.referenceStrengths : [body.referenceStrengths];
    body.referenceStrengths = raw.map((v) => (typeof v === 'string' && v !== '' ? Number(v) : v));
  }
  // Array fields are repeated multipart keys. A single selected value arrives
  // as a bare string, not a one-element array — wrap it so Zod accepts it.
  // `loraScales` numbers also arrive as strings, so coerce element-wise like
  // referenceStrengths above.
  for (const f of ['loraFilenames', 'loraPaths', 'referenceImageFiles']) {
    if (body[f] != null && !Array.isArray(body[f])) body[f] = [body[f]];
  }
  if (body.loraScales != null) {
    const raw = Array.isArray(body.loraScales) ? body.loraScales : [body.loraScales];
    body.loraScales = raw.map((v) => (typeof v === 'string' && v !== '' ? Number(v) : v));
  }
  // Multipart sends checkbox values as 'true' / 'false' strings; coerce to
  // bool so Zod's `z.boolean()` accepts them.
  for (const f of ['cleanC2PA', 'denoise', 'autoClean']) {
    if (typeof body[f] === 'string') body[f] = body[f] === 'true';
  }
  // Legacy single-flag clients: an explicit `autoClean` on the wire maps to
  // BOTH new flags (preserves the pre-split behavior) only when the caller
  // didn't also send the new fields. Modern clients that pass cleanC2PA /
  // denoise explicitly win.
  if (typeof body.autoClean === 'boolean') {
    if (typeof body.cleanC2PA !== 'boolean') body.cleanC2PA = body.autoClean;
    if (typeof body.denoise !== 'boolean') body.denoise = body.autoClean;
  }
  return body;
}

const avatarSchema = z.object({
  name: z.string().max(100).optional(),
  characterClass: z.string().max(100).optional(),
  prompt: z.string().max(2000).optional(),
  // When set, the route persists the rendered path onto the singleton
  // character record itself (the character store has no id), so the client
  // skips the follow-up PUT /api/character round-trip.
  persistToCharacter: z.boolean().optional(),
});

// Upload a user-supplied image straight into the gallery (`data/images/`) so it
// rides the existing `image` peer-sync asset path. `data` is base64 (no data:
// URI prefix); the real format is sniffed server-side, so the schema only caps
// the legacy JSON request. Multipart uploads have no size cap.
const uploadImageSchema = z.object({
  data: z.string().min(1).max(24 * 1024 * 1024),
});

// SynthID-defeat regen (issue #912). Body is optional — every field defaults
// server-side (strength → DEFAULT_REGEN_STRENGTH, steps → the model default,
// prompt → empty for minimal mutation). An empty/whitespace `prompt` is treated
// as "no prompt" by buildRegenParams, so the UI can send '' for the default.
const regenerateSchema = z.object({
  strength: z.number().min(REGEN_STRENGTH_MIN).max(REGEN_STRENGTH_MAX).optional(),
  steps: z.number().int().min(1).max(50).optional(),
  prompt: z.string().max(MAX_PROMPT_LENGTH).optional(),
  // 'flux' (default) = GPU img2img round-trip; 'light' = CPU-only spatial pass
  // for installs without a FLUX runner (strength/steps/prompt ignored).
  method: z.enum(['flux', 'light']).optional(),
  // Annotation re-render (issue #2036 phase 2): seed the img2img init image from
  // the saved flattened sketch (source + drawn strokes) instead of the raw
  // gallery file, so the marks reshape the render. GPU-only (light ignores the
  // init image); defaults to a higher denoise so the strokes take effect.
  annotated: z.boolean().optional(),
});

// Film look (lib/filmLook.js) baked into a new copy of a gallery still — the
// same SVG filter the music-video preview and final render apply, rendered in
// the composition browser at the image's own size. Synchronous like Clean:
// writes a `_look-<preset>-<id>.png` variant + sidecar beside the untouched
// source, files it into the source's collections, and returns it.
router.post('/:filename/film-look', asyncHandler(async (req, res) => {
  const filename = req.params.filename;
  local.assertGalleryFilename(filename);
  const { look } = validateRequest(filmLookBakeSchema, req.body ?? {});
  const { metadata: sourceMeta } = await local.readImageSidecar(filename);
  res.json(await applyFilmLookBake({ filename, sourceMeta, look }));
}));

// Visible-watermark removal — erases the Gemini / Nano-Banana bottom-right ✦.
// Body is optional: with no fields the corner box is auto-sized to the
// sparkle's typical footprint. `size` overrides the square side; `region`
// pins an explicit box (each field clamped server-side into the image) for
// off-spec placements. All ints in pixels.
const removeWatermarkSchema = z.object({
  size: z.number().int().min(1).max(4096).optional(),
  region: z.object({
    x: z.number().int().min(0).max(100000).optional(),
    y: z.number().int().min(0).max(100000).optional(),
    w: z.number().int().min(1).max(4096).optional(),
    h: z.number().int().min(1).max(4096).optional(),
  }).optional(),
});

router.get('/status', asyncHandler(async (req, res) => {
  // Optional ?mode= override lets the Image Gen page probe a specific
  // backend (e.g. when the user flips the per-render chip to Codex but
  // hasn't saved Codex as the default yet). Express's default query
  // parser turns duplicated keys (?mode=local&mode=codex) into arrays,
  // so guard on string type before forwarding so `mode` always reaches
  // the dispatcher as `string | undefined`.
  const rawMode = req.query.mode;
  const mode = typeof rawMode === 'string' && IMAGE_GEN_MODES.includes(rawMode) ? rawMode : undefined;
  const rawModelId = req.query.modelId;
  const modelId = typeof rawModelId === 'string' && rawModelId.length <= 64 ? rawModelId : undefined;
  res.json(await imageGen.checkConnection({ mode, ...(modelId ? { modelId } : {}) }));
}));

router.get('/active', asyncHandler(async (_req, res) => {
  res.json({ activeJob: await imageGen.getActiveJob() });
}));

router.get('/agy/models', asyncHandler(async (_req, res) => {
  const settings = await getSettings();
  res.json(await imageGen.agy.listModels({
    agyPath: settings.imageGen?.agy?.agyPath,
  }));
}));

// SynthID-defeat regen availability (issue #912). Drives whether the lightbox
// shows the "Regenerate" action — it's hardware-gated on a local FLUX runner.
// Optional `?filename=` (issue #2036): when the caller names a source image, its
// model is resolved from the sidecar and threaded into the backend pick so the
// reported `modelId` matches the exact model a regen of THAT image would run —
// the annotate re-render dialog must disclose the real model before the render.
router.get('/regen/availability', asyncHandler(async (req, res) => {
  const rawFilename = req.query.filename;
  const galleryPath = typeof rawFilename === 'string' && rawFilename ? resolveGalleryImage(rawFilename) : null;
  let sourceModelId;
  if (galleryPath) {
    // Read the sidecar by the RESOLVED gallery path's basename, never the raw
    // query value: resolveGalleryImage only validated the basename, so a
    // `../foo.png` input could otherwise traverse out of PATHS.images in the
    // sidecar read. basename(galleryPath) is the sanitized filename.
    const { metadata } = await local.readImageSidecar(basename(galleryPath));
    sourceModelId = metadata?.modelId;
  }
  res.json(await getRegenAvailability({ sourceModelId }));
}));

// Shape returned for any image-gen job that goes through the mediaJobQueue
// (local + codex). Kept in one place so the two enqueue branches below stay
// in sync — the client's polling/SSE hooks key off these fields.
const queuedImageResponse = ({ jobId, position, status, mode, model, mediaProviderPeerId = null }) => ({
  jobId,
  generationId: jobId,
  filename: `${jobId}.png`,
  path: `/data/images/${jobId}.png`,
  mode,
  model,
  status,
  position,
  // Which peer is rendering this, or null for a local/cloud render. The client
  // needs it to label the in-flight card honestly — `mode` is null for a
  // federated render precisely because no local backend is running it.
  mediaProviderPeerId,
});

// What the render would send, before it is sent (#11317). Same preparation and
// prompt builders as POST /generate; the form says which uploads it holds by
// count rather than sending their bytes, and nothing is staged or queued.
const promptPreviewSchema = generateSchema.safeExtend({
  uploadedInitImage: z.boolean().optional(),
  uploadedReferenceCount: z.number().int().min(0).max(MAX_REFERENCE_IMAGES).optional(),
});

router.post('/prompt-preview', asyncHandler(async (req, res) => {
  res.json(await previewImagePrompt(validateRequest(promptPreviewSchema, req.body ?? {})));
}));

router.post('/generate', imageGenUploads, asyncHandler(async (req, res) => {
  const data = validateRequest(generateSchema, coerceFormFields(req.body));
  if (data.catalogIngredientId) await assertCatalogIdentityWritable(data.catalogIngredientId);
  const { data: params, mode, settings, uploadedTempPaths } = await prepareGenerateParams({
    data,
    files: req.files,
    referenceImageFields: REFERENCE_IMAGE_FIELDS,
  });

  // FableLoom is compiled server-side after the backend pin resolves. The
  // browser's prompt/reference fields are hints only: stable scene bindings,
  // approved assets and deterministic graph continuity own the final request.
  if (params.fableLoom) {
    const taggedLoom = await getLoom(params.fableLoom.loomId);
    const taggedEpisode = taggedLoom?.episodes?.find((episode) => episode.id === params.fableLoom.episodeId);
    const renderSettings = taggedLoom ? asFableLoomRenderSettings(taggedLoom.renderSettings) : null;
    if (renderSettings) {
      params.width = renderSettings.width;
      params.height = renderSettings.height;
      params.aspectRatio = renderSettings.aspectRatio;
    }
    if (taggedLoom && taggedEpisode) {
      const episodeOrder = inspectEpisodeProductionOrder(taggedLoom, taggedEpisode);
      if (!episodeOrder.ready) {
        throw new ServerError(
          `FableLoom storyboard production is out of order: ${episodeOrder.reason}`,
          {
            status: 409,
            code: 'FABLELOOM_EPISODE_ORDER_BLOCKED',
            context: { details: { episodeOrder } },
          },
        );
      }
    }
    const selected = mode === IMAGE_GEN_MODE.LOCAL
      ? selectLocalImageModelFromSettings(settings, params.modelId)
      : null;
    const cloud = selected ? null : resolveCloudProviderConfig(settings, mode, {
      model: params.cloudModel, modelIsShippedDefault: params.cloudModelIsShippedDefault,
    });
    const model = selected
      ? { ...selected, loraCompatKey: loraCompatKey(selected) }
      : (cloud ? { id: cloud.modelId } : null);
    const providerMode = params.mediaProviderPeerId ? 'federated' : mode;
    const compiled = await compileFableLoomVisualRequest({
      tag: params.fableLoom,
      kind: 'image',
      capability: fableLoomImageCapabilities({
        mode: providerMode,
        model,
        // The backend's own input cap (per model for fal.ai), never above
        // the form ceiling.
        inputBudget: Math.min(maxInputImages(mode, cloud?.modelId) ?? MAX_REFERENCE_IMAGES, MAX_REFERENCE_IMAGES),
      }),
      authoredPrompt: params.prompt,
      authoredNegativePrompt: params.negativePrompt,
    });
    if (compiled) {
      params.prompt = compiled.prompt;
      params.negativePrompt = compiled.negativePrompt;
      // The compiler's canon blocks, listed beside what the scene's own request listed (#11317).
      if (compiled.promptAdditions?.length) params.promptAdditions = [...(params.promptAdditions || []), ...compiled.promptAdditions];
      params.referenceImagePaths = compiled.referenceImagePaths;
      params.referenceImageStrengths = compiled.referenceImageStrengths;
      params.loraFilenames = compiled.loraFilenames;
      params.loraPaths = [];
      params.loraScales = compiled.loraScales;
      params.visualConditioning = compiled.visualConditioning ? {
        ...compiled.visualConditioning,
        render: {
          provider: providerMode,
          modelId: model?.id || null,
          modelRevision: model?.revision || null,
          parameters: {
            width: params.width,
            height: params.height,
            ...(params.aspectRatio ? { aspectRatio: params.aspectRatio } : {}),
          },
        },
      } : null;
    }
  }

  // Resolve an optional universe-collection target into a job tag the
  // completion hook understands. Done server-side so a base-style probe lands
  // in the same "Universe: <name>" bucket as batch renders without the
  // front-end doing any collection bookkeeping. Best-effort: a provisioning
  // failure drops the tag and the render still proceeds (it just won't
  // auto-file) rather than failing the user's generation over a side-effect.
  if (params.universeRun?.universeId) {
    const { universeId, universeName, label, category, entryRef } = params.universeRun;
    // The helper provisions the universe collection (best-effort) and assembles
    // the tag. It preserves `entryRef` even when provisioning fails — the
    // durable `imageRefs[]` append (#1395) must not depend on the gallery
    // collection existing — and returns `undefined` (dropping the tag) only
    // when there's nothing left to do (no collection AND no entryRef).
    params.universeRun = await buildUniverseRunTag({
      universeId,
      universeName,
      label,
      category,
      entryRef,
      errorContext: 'image-gen → universe collection provision failed',
    });
  }

  // Collapse the catalog-attach params into a single job tag the completion
  // hook understands (#1359). Folded into `params` so it rides into both the
  // local and codex `enqueueJob` branches below via `...params`; the raw fields
  // are dropped so persisted job.params carries only the canonical tag.
  if (params.catalogIngredientId) {
    params.catalogAttach = {
      ingredientId: params.catalogIngredientId,
      ...(params.catalogMediaKind ? { kind: params.catalogMediaKind } : {}),
    };
  }
  delete params.catalogIngredientId;
  delete params.catalogMediaKind;

  // Multer's tmp upload is no longer needed once we've copied it into
  // PATHS.images. Use res.on('close') so the temp files are cleaned up whether
  // generateImage resolves, throws (handled by errorHandler middleware), or
  // the client drops the connection mid-flight.
  if (uploadedTempPaths.length) {
    res.on('close', () => {
      for (const p of uploadedTempPaths) unlinkGuarded(p).catch(() => {});
    });
  }

  // Local + codex both go through mediaJobQueue (separate lanes — codex
  // doesn't share MLX). External SD-API stays synchronous: it's a remote
  // call with no local single-flight constraint to absorb. `settings` and
  // `mode` were already resolved above (so the FLUX.2 + local-backend gate
  // could fire before staging any uploads).

  // Federated render (#4348): submit to the selected peer instead of running
  // locally. Checked BEFORE the cloud/local dispatch below — those branches
  // resolve this machine's backends, which a remote render never uses.
  if (params.mediaProviderPeerId) {
    // LoRA weights are the one input that still cannot cross, and it is a
    // decision rather than a gap: a LoRA is a MODEL, not conditioning, and
    // remote model installation is out of scope for federation (ADR
    // docs/decisions/2026-08-22-federated-media-input-assets.md rule 3). Refuse
    // rather than silently dropping it — a render that quietly ignores its LoRA
    // is worse than one that says why.
    if (params.loraFilenames?.length || params.loraPaths?.length) {
      throw new ServerError(
        'A federated media provider renders with the models its own operator installed — LoRA weights do not cross. '
        + 'Render locally, or install the LoRA on the peer and allowlist a model that uses it.',
        { status: 400, code: 'MEDIA_PROVIDER_INPUT_UNSUPPORTED' },
      );
    }
    // Conditioning images DO cross (rule 1), by id: the bytes go up through the
    // provider's authenticated, digest-verified asset endpoint immediately
    // before submission. The marker keeps these LOCAL paths, never the
    // provider-issued ids, so a reconcile after a restart re-stages the same
    // bytes instead of naming staging slots that have since expired.
    const inputAssets = collectRemoteInputAssets('image', params);
    // A peer advertises specific models; it has no notion of 'this caller's
    // default'. Say so rather than letting the wire schema report a bare
    // 'expected string, received undefined' for a field the local path defaults.
    if (!params.modelId) {
      throw new ServerError(
        'A federated render must name the provider model explicitly (modelId)',
        { status: 400, code: 'MEDIA_PROVIDER_MODEL_REQUIRED' },
      );
    }
    // Re-validate against the wire schema here rather than trusting the route
    // schema's overlap with it: this object is what gets persisted and replayed
    // on every reconcile, so it must already be a body the provider accepts.
    const request = buildFederatedMediaRequest({ kind: 'image', params });
    const { peer, remoteMedia } = await prepareRemoteMediaJob({
      peerId: params.mediaProviderPeerId,
      kind: 'image',
      request,
      inputAssets,
    });
    // Drop every field that only means something to a LOCAL dispatch: the
    // routing inputs consumed above, plus the backend selectors this render
    // never uses. The destination tags (universeRun, writersRoom, musicVideo,
    // catalogAttach) deliberately stay — their completion hooks fire off the
    // finished filename and work identically for a federated render.
    const {
      mediaProviderPeerId: _peerId, mediaProviderEngine: _engine,
      mode: _mode, cloudModel: _cloudModel, cloudModelIsShippedDefault: _cloudModelProvenance,
      ...jobParams
    } = params;
    // The prompt and model ride only inside the versioned marker: enqueueJob
    // normalizes any job carrying one into the downgrade-safe shape, so this
    // render cannot be re-run for real by a build rolled back past
    // `remoteMedia`. Contract: services/federatedMedia/routedJobParams.js.
    const queued = await enqueueLoggedImage(req, {
      kind: 'image',
      params: { ...jobParams, remoteMedia },
    });
    return res.json(queuedImageResponse({
      ...queued,
      mode: null,
      model: request.modelId,
      mediaProviderPeerId: peer.id,
    }));
  }

  // `cloudModel` and its provenance flag are dispatcher-level knobs, not
  // provider params — the resolver folds them into the provider's own `model`
  // and `modelIsShippedDefault`, so drop the raw fields before they ride into
  // the persisted job params.
  const cloudModel = params.cloudModel;
  const modelIsShippedDefault = params.cloudModelIsShippedDefault;
  delete params.cloudModel;
  delete params.cloudModelIsShippedDefault;
  const cloud = resolveCloudProviderConfig(settings, mode, { model: cloudModel, modelIsShippedDefault });
  if (cloud) {
    // Reject up-front rather than enqueueing a doomed job — the cloud CLIs are
    // gated behind an explicit toggle each (not every Codex account has access
    // to the image_gen tool, and grok spends the user's Grok quota).
    if (!cloud.enabled) throw cloud.disabledError;
    // `mode` inside jobParams is the queue's discriminator — laneForJob()
    // routes cloud jobs to the parallel cloud lane, and runJob's image branch
    // dispatches to the matching imageGen provider module when it sees it.
    // `cloud.modelId` is the *effective* model so the response metadata reports
    // what actually renders (gpt-6-luna by default) instead of "codex"/null.
    const queued = await enqueueLoggedImage(req, { kind: 'image', params: { ...cloud.jobParams, ...params } });
    return res.json(queuedImageResponse({ ...queued, mode, model: cloud.modelId }));
  }
  if (mode === IMAGE_GEN_MODE.LOCAL) {
    const { pythonPath: py, selectedModel } = resolveLocalImageModel(settings, params);
    const queued = await enqueueLoggedImage(req, {
      kind: 'image',
      params: {
        ...params,
        pythonPath: py,
        ...(selectedModel?.id ? { modelId: selectedModel.id } : {}),
      },
    });
    // selectedModel reflects the actual fallback chain resolveLocalImageModel
    // applied (caller modelId → 'dev' → allModels[0]) rather than just the
    // requested id.
    return res.json(queuedImageResponse({
      ...queued,
      mode: IMAGE_GEN_MODE.LOCAL,
      model: selectedModel?.id || params.modelId || 'dev',
    }));
  }
  // Selective section revision (#9011): the external/agy lane renders
  // synchronously and never touches enqueueLoggedImage's guard above, so it
  // gets its own check right before the (paid) render call. A no-op when the
  // tag carries no revisionId.
  if (params.musicVideo?.revisionId) {
    const { assertRevisionOpen } = await import('../services/musicVideo/revisionService.js');
    await assertRevisionOpen(params.musicVideo.projectId, params.musicVideo.revisionId, { sceneId: params.musicVideo.sceneId, kind: 'image' });
  }
  const result = await imageGen.generateImage(params);
  if (params.musicVideoProjectId && result?.filename) {
    const { fileIntoMusicVideoCollection } = await import('../services/musicVideoCollectionHook.js');
    await fileIntoMusicVideoCollection(params.musicVideoProjectId, [{ kind: 'image', ref: result.filename }]);
  }
  if (params.fableLoom && result?.filename) {
    await attachNodeImage(
      params.fableLoom.loomId,
      params.fableLoom.episodeId,
      params.fableLoom.nodeId,
      {
        filename: result.filename,
        jobId: result.generationId,
        visualConditioning: params.visualConditioning,
      },
    );
  }
  res.json(result);
}));

router.post('/avatar', asyncHandler(async (req, res) => {
  const data = validateRequest(avatarSchema, req.body);
  const result = await imageGen.generateAvatar(data);
  // `result.path` is server-generated as `/data/images/<file>` (the same value
  // the client previously round-tripped through PUT /api/character), so it's
  // safe to persist directly without re-validating against the path regex.
  if (data.persistToCharacter && result?.path) {
    await characterService.setAvatar(result.path);
  }
  res.json(result);
}));

// Save an uploaded image into the gallery dir so callers (e.g. author
// headshots) get a `/data/images/<f>` URL that the peer-sync `image` asset
// path can transfer — unlike `/api/uploads/<f>`, which is not a pullable
// asset kind and 404s on a peer.
router.post('/upload', optionalUpload('file'), asyncHandler(async (req, res) => {
  if (req.file) {
    try {
      return res.json(await local.saveUploadedGalleryImage(null, req.file.path));
    } finally {
      await unlinkGuarded(req.file.path).catch(() => {});
    }
  }
  const { data } = validateRequest(uploadImageSchema, req.body);
  res.json(await local.saveUploadedGalleryImage(data));
}));

// Local-only: list image models and LoRAs the local backend can use.
router.get('/models', (_req, res) => {
  res.json(local.listImageModels());
});

// Per-model download status. Returns `[{ id, repo, cached, sizeBytes }]` so
// the form can show an inline "Available" or "Download" badge next to the
// model picker — without waiting until a render to discover a multi-GB HF
// download. Models without a known HF repo (typically third-party custom
// entries with `runner: 'mflux'` and a non-default name) report
// `cached: null` so the UI can render "unknown" rather than a misleading
// "not downloaded" state. Lazy generation still works regardless of badge.
const imageModelCacheStatus = async (m) => {
  if (usesMossSwift(m)) return mossModelCacheStatus(m.id);
  const required = requiredReposForModel(m);
  if (!required) return { id: m.id, repo: null, cached: null, sizeBytes: 0 };
  // Inspect every required repo (main + any aux text encoders). The badge
  // is `cached: true` only when ALL are cached; sizeBytes is the sum. The
  // `pendingRepos` field lets the UI explain WHICH repos still need a pull
  // so the user isn't surprised when clicking "Download" triggers >1 fetch.
  const inspections = await Promise.all(required.map((r) => inspectModelCache(r)));
  const cached = inspections.every((i) => i.cached);
  const sizeBytes = inspections.reduce((sum, i) => sum + (i.sizeBytes || 0), 0);
  const pendingRepos = required.filter((_, i) => !inspections[i].cached);
  // Integrity is only meaningful for repos that finished downloading — run
  // the cheap structural check across every cached required repo and report
  // the worst result, so a corrupt aux encoder still surfaces a Repair state.
  const integrity = cached ? aggregateVerifies(await Promise.all(required.map((r) => verifyModelCache(r)))) : null;
  return { id: m.id, repo: required[0], cached, sizeBytes, requiredRepos: required, pendingRepos, integrity };
};

router.get('/models/status', asyncHandler(async (_req, res) => {
  res.json(await Promise.all(getImageModels().map(imageModelCacheStatus)));
}));

// POST /models/verify — on-demand integrity re-scan. `deep:true` adds the
// per-file sha256 comparison on top of the structural check. With no `modelId`
// it scans every model.
const verifyImageBodySchema = z.object({
  modelId: z.string().min(1).optional(),
  deep: z.boolean().optional(),
});
router.post('/models/verify', asyncHandler(async (req, res) => {
  const parsed = verifyImageBodySchema.safeParse(req.body || {});
  if (!parsed.success) failValidation(parsed);
  const { modelId, deep = false } = parsed.data;
  const models = getImageModels().filter((m) => (modelId ? m.id === modelId : true));
  if (modelId && models.length === 0) {
    throw new ServerError(`Unknown model id: ${modelId}`, { status: 404, code: 'UNKNOWN_MODEL' });
  }
  const results = await Promise.all(models.map(async (m) => {
    if (usesMossSwift(m)) return { id: m.id, ...aggregateVerifies([await verifyMossWeights({ deep })]) };
    const required = requiredReposForModel(m) || [];
    const verifies = await Promise.all(required.map((r) => verifyModelCache(r, { deep })));
    return { id: m.id, ...(aggregateVerifies(verifies) || { status: 'missing', checkedDeep: deep, badFiles: [] }) };
  }));
  res.json({ deep, models: results });
}));

// POST /models/:modelId/repair — delete the flagged weight files across the
// model's required repos so the existing resumable HF fetch path re-downloads
// them. Returns the deleted-file list; the client then re-triggers the normal
// download SSE to pull clean copies with progress.
router.post('/models/:modelId/repair', asyncHandler(async (req, res) => {
  const model = getImageModels().find((m) => m.id === req.params.modelId);
  if (!model) throw new ServerError(`Unknown model id: ${req.params.modelId}`, { status: 404, code: 'UNKNOWN_MODEL' });
  const parsed = z.object({ deep: z.boolean().optional() }).safeParse(req.body || {});
  if (!parsed.success) failValidation(parsed);
  const deep = parsed.data.deep || false;
  if (usesMossSwift(model)) return res.json(await repairMossWeights({ deep }));
  const required = requiredReposForModel(model);
  if (!required) {
    throw new ServerError(`Model "${model.id}" has no HuggingFace repo on file.`, { status: 400, code: 'NO_REPO_FOR_MODEL' });
  }
  const repaired = await Promise.all(required.map((repo) => repairModelCache(repo, { deep })));
  const deleted = repaired.flatMap((r) => r.deleted.map((name) => ({ repo: r.repoId, name })));
  res.json({ deep, deleted, repos: required });
}));

// SSE-driven model download. Cancels the python child if the client
// disconnects mid-download; cross-route in-flight dedupe lives in
// startHfDownloadStream so a FLUX repo shared with video gen can't spawn
// two concurrent children.
const downloadableImageModel = (req) => {
  const { modelId } = validateRequest(modelDownloadParamsSchema, req.params);
  const model = getImageModels().find((m) => m.id === modelId);
  if (!model) throw new ServerError(`Unknown model id: ${modelId}`, { status: 404, code: 'UNKNOWN_MODEL' });
  return model;
};

router.get('/models/:modelId/download', asyncHandler(async (req, res) => {
  validateRequest(modelDownloadQuerySchema, req.query);
  res.json(await imageModelCacheStatus(downloadableImageModel(req)));
}));

router.post('/models/:modelId/download', asyncHandler(async (req, res) => {
  const { force } = validateRequest(modelDownloadQuerySchema, req.query);
  const model = downloadableImageModel(req);
  if (usesMossSwift(model)) return streamMossAction(req, res, downloadMossWeights);
  const repos = requiredReposForModel(model);
  if (!repos) {
    throw new ServerError(`Model "${model.id}" has no HuggingFace repo on file — cannot pre-download.`, {
      status: 400,
      code: 'NO_REPO_FOR_MODEL',
    });
  }
  // Sequentially fetch every required repo (main + aux text encoders for
  // HiDream). The SSE stream tags each event with `repo` so the client can
  // show per-repo progress / log lines. `?force=1` (repair-initiated) re-fetches
  // even when the repo still looks cached, so a deleted shard isn't skipped.
  await startHfDownloadStream({ req, res, repos, force });
}));

router.get('/loras', asyncHandler(async (_req, res) => {
  res.json(await local.listLoraFilenames());
}));

const galleryReads = createImageGalleryHandlers(local.listGallery);
router.get('/gallery/collections', galleryReads.collections);
router.get('/gallery/facets', galleryReads.facets);
router.post('/gallery/lookup', galleryReads.lookup);
router.get('/gallery', galleryReads.list);

// SSE progress stream. Local renders run via the mediaJobQueue and emit
// `queued` → `started` → `progress` → `complete` events; the queue owns the
// SSE attachment for those. Codex still produces job-keyed SSE through its
// own provider — fall through to the dispatcher when the queue doesn't know
// the job. External backend has no SSE (it's blocking).
router.get('/:jobId/events', (req, res) => {
  if (attachQueueSseClient(req.params.jobId, res)) return;
  if (imageGen.attachSseClient(req.params.jobId, res)) return;
  throw new ServerError('Job not found or expired', { status: 404 });
});

router.post('/cancel', asyncHandler(async (req, res) => {
  // Cancel selection rules, in priority order:
  //   1. body.all === true — cancel every queued/running image job. Used by
  //      the writers-room storyboard "Cancel renders" CTA, which can have
  //      20+ scene renders in flight at once.
  //   2. Explicit body.jobId — cancel exactly that job and NOTHING else. An id
  //      that is unknown (404) or already terminal (409) never falls through
  //      to another job or a bulk cancel (#9932). A malformed id is a 400.
  //   3. No jobId — cancel the newest queued/running local image job (most
  //      recent activity wins, matching the user's last "submit" gesture).
  //   4. No queue match — fall through to the codex-mode cancel.
  const { jobId: requestedJobId, all } = validateRequest(imageCancelBodySchema, req.body ?? {});
  const imageJobs = listJobs({ kind: 'image' });
  const cancellable = imageJobs.filter((j) => j.status === 'queued' || j.status === 'running');
  if (all === true) {
    // Cancel queued first so the running job's slot doesn't get refilled the
    // moment we cancel it. Settle individually so one stale job doesn't
    // block the rest. cancellable is already a fresh filter() result.
    const ordered = cancellable.sort((a, b) => {
      if (a.status === b.status) return 0;
      return a.status === 'queued' ? -1 : 1;
    });
    const results = await Promise.all(ordered.map((j) => cancelJob(j.id).catch((err) => ({ ok: false, error: err.message }))));
    // Belt-and-braces: also poke the legacy single-process cancel so any
    // in-flight gen outside the queue (codex sync mode) gets stopped.
    imageGen.cancel();
    return res.json({ ok: true, canceled: results.filter((r) => r?.ok).length, attempted: results.length });
  }
  if (requestedJobId) {
    const known = imageJobs.find((j) => j.id === requestedJobId);
    if (known) {
      if (!cancellable.includes(known)) {
        throw new ServerError(`Job already ${known.status}`, { status: 409, code: 'ALREADY_TERMINAL' });
      }
      const result = await cancelJob(known.id);
      if (!result?.ok && result?.code) {
        throw new ServerError(result.error || 'Cancel failed', { status: result.code === 'ALREADY_TERMINAL' ? 409 : 404, code: result.code });
      }
      return res.json(result);
    }
    // Not in the queue — it may be a legacy provider job (sync codex/grok/agy/
    // fal, local) the dispatcher owns. Exact-ID only; never the bulk path.
    if (imageGen.cancelJob(requestedJobId)) return res.json({ ok: true });
    throw new ServerError('Job not found or expired', { status: 404 });
  } else if (cancellable.length) {
    // "Most recent submit" — explicitly sort by queuedAt DESC instead of
    // relying on listJobs() ordering (which puts gpuRunning before
    // codexRunning, then queue, then archive). queuedAt is the user's
    // actual submit timestamp; startedAt would mis-order an older queued
    // job that just dequeued ahead of a more-recently-submitted job
    // still waiting in queue.
    const latestSubmitFirst = [...cancellable].sort((a, b) => {
      const ta = new Date(a.queuedAt || 0).getTime();
      const tb = new Date(b.queuedAt || 0).getTime();
      return tb - ta;
    });
    return res.json(await cancelJob(latestSubmitFirst[0].id));
  }
  const cancelled = imageGen.cancel();
  res.json({ ok: cancelled });
}));

// Also purges the filename from universe canon (entry `imageRefs` and style
// references) inside the same backup admission as the file removal.
router.delete('/:filename', asyncHandler(async (req, res) => {
  res.json(await deleteGalleryImage(req.params.filename));
}));

// Variant set for ONE image, for the lightbox original-vs-cleaned toggle —
// see listImageVariants for why no host list can answer it.
router.get('/:filename/variants', asyncHandler(async (req, res) => {
  const filename = req.params.filename;
  local.assertGalleryFilename(filename);
  const { listImageVariants } = await import('../services/mediaAssetIndex/gallery.js');
  res.json({ items: await listImageVariants(filename, local.listGallery) });
}));

router.post('/:filename/visibility', asyncHandler(async (req, res) => {
  res.json(await local.setImageHidden(req.params.filename, validateRequest(imageVisibilityBodySchema, req.body ?? {}).hidden));
}));

router.patch('/:filename/prompt', asyncHandler(async (req, res) => {
  const body = validateRequest(updatePromptSchema, req.body ?? {});
  res.json(await local.updateImagePrompt(req.params.filename, body.prompt));
}));

router.post('/:filename/clean', asyncHandler(async (req, res) => {
  const filename = req.params.filename;
  local.assertGalleryFilename(filename);
  const { metadata: sourceMeta } = await local.readImageSidecar(filename);
  res.json(await applyImageClean({ filename, sourceMeta }));
}));

// Visible-watermark removal — erases the Gemini / Nano-Banana bottom-right ✦.
// Unlike SynthID regen (which round-trips the WHOLE image to overwrite an
// invisible per-pixel signal), this localizes the corner logo and reconstructs
// only that box via a dependency-free harmonic inpaint — so it's a CPU-only
// sharp pass that runs on every install, GPU or not, and leaves the rest of the
// image byte-faithful. Synchronous like Clean: writes a `_nowatermark.png`
// variant + sidecar, files it into the source's collections, and returns it.
router.post('/:filename/remove-watermark', asyncHandler(async (req, res) => {
  const filename = req.params.filename;
  local.assertGalleryFilename(filename);
  const body = validateRequest(removeWatermarkSchema, req.body || {});
  const { metadata: sourceMeta } = await local.readImageSidecar(filename);
  res.json(await applyWatermarkRemoval({ filename, sourceMeta, size: body.size, region: body.region }));
}));

// SynthID-defeat regeneration (issue #912). Round-trips an existing gallery
// image through local FLUX img2img at low–moderate denoise so the per-pixel
// watermark is overwritten by fresh sampling — the only honest defeat path
// (the lossless clean above can't touch SynthID). Post-hoc + history-only:
// enqueues a normal local image job (GPU lane) using the source's own prompt;
// the new render lands in the gallery as a variant of the source. Hardware-
// gated — 400s with an actionable message when no local FLUX runner exists.
router.post('/:filename/regenerate', asyncHandler(async (req, res) => {
  const filename = req.params.filename;
  local.assertGalleryFilename(filename);
  const body = validateRequest(regenerateSchema, req.body || {});

  const sourceAbsPath = resolveGalleryImage(filename);
  if (!sourceAbsPath) {
    throw new ServerError('Image not found', { status: 404, code: 'NOT_FOUND' });
  }

  // Annotation re-render (issue #2036 phase 2): use the saved flattened sketch
  // (source + strokes) as the img2img init image. It's a whole-image denoise, so
  // the light spatial pass can't honor the marks — GPU only. Validate cheaply
  // here (no disk writes) so a bad request 400s without leaving anything behind;
  // the actual staging copy happens below, only once every gate has passed.
  let annotatedSketchPath = null;
  if (body.annotated) {
    if (body.method === 'light') {
      throw new ServerError('Annotation re-render needs the GPU img2img pass, not the light method.', { status: 400, code: 'VALIDATION_ERROR' });
    }
    const key = itemKey({ kind: 'image', ref: filename });
    if (!isValidSketchKey(key)) {
      throw new ServerError('Image cannot be annotated', { status: 400, code: 'VALIDATION_ERROR' });
    }
    annotatedSketchPath = await getSketchPngPath(key);
    if (!annotatedSketchPath) {
      throw new ServerError('No saved annotation to re-render — draw over the image and save first.', { status: 400, code: 'NO_ANNOTATION' });
    }
  }

  // Sidecar (for prompt/model) and the on-disk dimension probe have no data
  // dependency — overlap the two reads.
  const [{ metadata: sourceMeta }, sourceDims] = await Promise.all([
    local.readImageSidecar(filename),
    readImageDimensions(sourceAbsPath),
  ]);

  // CPU-only light path (no FLUX runner required). A best-effort spatial pass
  // for installs that can't run the GPU round-trip — synchronous like Clean:
  // it writes a `_regen-light.png` variant inline and returns it (no queue).
  if (body.method === 'light') {
    return res.json(await applyLightRegenVariant({ filename, sourceAbsPath, sourceMeta }));
  }

  const backend = await resolveRegenBackend({ sourceModelId: sourceMeta.modelId });
  if (!backend.available) {
    throw new ServerError(backend.reason, { status: 400, code: 'REGEN_BACKEND_UNAVAILABLE' });
  }

  // Stage the flattened annotation ONLY now that every gate has passed and the
  // job is about to enqueue — so a rejected request (unavailable backend, failed
  // read) never leaves an orphaned snapshot behind. The local runner re-validates
  // initImagePath against its approved image roots (gallery / image-refs /
  // visual-templates) and silently drops anything outside them — `data/media-
  // sketches/` is NOT one, so the sidecar is copied into the image-refs root the
  // runner accepts. The copy also freezes the markup at enqueue time (a later
  // re-save can't change what this queued job renders from), and the `init-<uuid>`
  // name (it IS this job's init image) lets imageRefsGc.js sweep it once
  // unreferenced.
  let initImageAbsPath = null;
  if (annotatedSketchPath) {
    await ensureDir(PATHS.imageRefs);
    initImageAbsPath = join(PATHS.imageRefs, `init-${randomUUID()}.png`);
    await copyFileGuarded(annotatedSketchPath, initImageAbsPath);
  }

  // Provider-aware default (issue #912): SynthID-bearing sources keep the
  // known-good 0.25; local FLUX sources use a lighter pass. An annotation
  // re-render instead defaults higher so the drawn marks reshape the render
  // (issue #2036). The explicit `strength` override always wins.
  const strength = body.strength
    ?? (body.annotated ? REGEN_ANNOTATED_STRENGTH_DEFAULT : resolveRegenStrengthDefault(sourceMeta));
  const params = buildRegenParams({
    filename,
    sourceAbsPath,
    sourceMeta,
    sourceDims,
    model: backend.model,
    pythonPath: backend.pythonPath,
    strength,
    steps: body.steps,
    promptOverride: body.prompt,
    initImageAbsPath,
    annotated: !!body.annotated,
  });
  const queued = await enqueueLoggedImage(req, { kind: 'image', params });
  const via = body.annotated ? 'annotation re-render' : 'Regenerating';
  console.log(`♻️ ${via} ${filename} via ${backend.model.id} (strength=${strength}) → job ${queued.jobId.slice(0, 8)}`);
  return res.json(queuedImageResponse({ ...queued, mode: IMAGE_GEN_MODE.LOCAL, model: backend.model.id }));
}));

// Local-mode setup automation (python probe/venv, FLUX.2 install/status,
// HF token store, pip installer) lives in its own router.
router.use("/setup", setupRouter);

export default router;