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

83.7 KB
Raw Blame
import { maintenance } from '../../lib/maintenanceAdmission.js';
/**
 * Image Gen — Local provider (mflux, diffusers, and platform-specific runners).
 *
 * Spawns a Python child process to generate the selected local image model. HF model weights
 * stream into the user's standard HF cache (`~/.cache/huggingface/`) — PortOS
 * doesn't override HF_HOME. Generated images land in `data/images/<jobId>.png`
 * with a sidecar metadata JSON so the gallery and Remix flow can recover
 * prompt/seed/steps.
 *
 * Progress comes back via the imageGenEvents bus (Socket.IO bridge) and over
 * a per-job SSE stream so EventSource consumers (the Imagine page) get the
 * raw status text mflux prints to stderr.
 */

import { spawn } from '../../lib/childProcess.js';
import sharp from 'sharp';
import { readFile, readdir, stat, mkdtemp, open, rename } from 'fs/promises';
import { existsSync, watch as fsWatch } from 'fs';
import { join, dirname, resolve as resolvePath, sep as PATH_SEP, basename } from 'path';
import { tmpdir } from 'os';
import { randomUUID } from 'crypto';
import { trashFiles } from '../../lib/trashFiles.js';
import { atomicWrite, assertSafeFilename, detectImageFormat, ensureDir, listDirectoryByExtension, PATHS, safeJSONParse, resolveImageInputPath, tryReadFile, rmGuarded, unlinkGuarded } from '../../lib/fileUtils.js';
import { extractPngGenerationMetadata, extractPngGenerationMetadataFile } from '../../lib/pngMetadata.js';
import { ServerError } from '../../lib/errorHandler.js';
import { withBackupAssetPublication } from '../../lib/backupSnapshotBoundary.js';
import { autoCleanGeneratedImage } from '../../lib/imageClean.js';
import { rejectDegenerateFrame } from './frameGuard.js';
import { imageGenEvents } from '../imageGenEvents.js';
import { broadcastSse, attachSseClient as attachSse, closeJobAfterDelay, dispatchTerminalEvent, PYTHON_NOISE_RE } from '../../lib/sseUtils.js';
import { resolveFlux2Python, FLUX2_VENV_DEFAULT, isFlux2VenvHealthy, invalidateFlux2Health } from '../../lib/pythonSetup.js';
import { usesTorchVenv, usesMossSwift } from '../../lib/imageRuntimeRemedies.js';
import { mossRenderArgs, mossChildEnv, MOSS_MANIFEST } from './mossRuntime.js';
import { hfChildEnv } from '../hfToken.js';
import { extractGatedRepo, isGatedRepoError } from '../../lib/hfErrors.js';
import { killWithEscalation } from '../../lib/killWithEscalation.js';
import { renderTimingFields } from '../../lib/renderTiming.js';
import { createLineReader } from '../../lib/streamLines.js';
import { claimHeavyLocalJob } from '../../lib/heavyJobClaim.js';
import { safeChildProcessOptions } from '../../lib/processEnv.js';
import { IMAGE_GEN_MODE, LOCAL_IMAGEGEN_DEFAULT_MODEL } from './modes.js';
import { parseByteProgress, formatDownloadMessage, bufferChildExit } from '../videoGen/generateVideoHelpers.js';


import { getImageModels, isFlux2, isErnie, isHiDream, isQwen } from '../../lib/mediaModels.js';
import { hardwareUnavailableReason, isHardwareCompatible } from '../../lib/systemCapabilities.js';
import { usesDiffusersRunner, flux2Bf16BaseRepo } from '../../lib/runners.js';
import { weaveLoraTriggers } from '../../lib/loraTriggers.js';
import { provenanceForRender } from '../../lib/assetProvenance.js';
import { createKeyCachedQueue } from '../../lib/createKeyCachedQueue.js';
import { readTriggerWordsByFilename, readLoraLicensesByFilename } from '../loras.js';
import { carriedPromptAdditions, promptAddition, sentPromptRecord } from '../../lib/modelInput.js';

// Read the registry lazily — callers below hit getImageModels() at request
// time. A prior `IMAGE_MODELS = Object.fromEntries(getImageModels()...)`
// snapshot lived here but fired loadMediaModels() at import time, breaking
// any test that mocks PATHS.data to a non-writable path.
export const listImageModels = () => getImageModels();

// Per-job clients: jobId -> { clients, status, meta, broadcast }
const jobs = new Map();
let activeProcess = null;
// Snapshot of the currently-running job for /api/image-gen/active so the UI
// can rehydrate prompt + settings + progress + last-rendered frame after
// navigating away. Cleared on completion / error / cancel.
let activeJob = null;

export const getActiveJob = () => activeJob;

export const attachSseClient = (jobId, res) => attachSse(jobs, jobId, res);

// The job between stepwise-dir creation and a wired child. cancel() has no
// process to signal in that window (heavy-claim wait, model unload), so it flags
// the job and the pre-spawn gate aborts it.
let preparing = null;

export const cancel = () => {
  if (!activeProcess) {
    if (!preparing) return false;
    preparing.cancelRequested = true;
    return 'pending';
  }
  const proc = activeProcess;
  // KEEP activeProcess + activeJob set until proc.on('close') clears them.
  // Otherwise BUSY immediately allows a new generation while the SIGTERM'd
  // mflux child is still running, and we lose the handle for a follow-up
  // SIGKILL. The `activeProcess === proc` guard escalates only when this is
  // still the tracked child (mflux can ignore SIGTERM mid-tensor-op).
  killWithEscalation(proc, { label: 'image child', stillRunning: () => activeProcess === proc });
  return true;
};

const diffusersRenderArgs = ({ model, prompt, negativePrompt, width, height, steps, guidance, seed, outputPath, loraPaths = [], loraScales = [], stepwiseDir, initImagePath, initImageStrength, referenceImagePaths = [] }) => {
  const modelId = model?.id;
  const runnerLabel = isErnie(model) ? 'ERNIE' : isHiDream(model) ? 'HiDream' : isQwen(model) ? 'Qwen' : 'Z-Image';
  const errCode = isErnie(model)
    ? 'IMAGE_GEN_ERNIE_MISCONFIGURED'
    : isHiDream(model)
      ? 'IMAGE_GEN_HIDREAM_MISCONFIGURED'
      : isQwen(model)
        ? 'IMAGE_GEN_QWEN_MISCONFIGURED'
        : 'IMAGE_GEN_Z_IMAGE_MISCONFIGURED';
  if (!model.repo) {
    throw new ServerError(
      `${runnerLabel} model "${modelId}" is missing the 'repo' field in data/media-models.json`,
      { status: 500, code: errCode },
    );
  }
  // Z-Image / ERNIE / HiDream / Qwen all reuse the FLUX.2 venv (same
  // diffusers + torch stack, no extra setup). Same not-installed error code
  // so the UI's existing "run setup" CTA fires for any of these runners.
  const torchPython = resolveFlux2Python();
  if (!torchPython) {
    throw new ServerError(
      `Image-gen torch venv not found. Run \`INSTALL_FLUX2=1 bash scripts/setup-image-video.sh\` to bootstrap it (expected at ${FLUX2_VENV_DEFAULT}). FLUX.2, Z-Image, ERNIE, HiDream, and Qwen share this venv.`,
      { status: 400, code: 'IMAGE_GEN_FLUX2_NOT_INSTALLED' },
    );
  }
  const scriptPath = join(PATHS.root, 'scripts', 'z_image_turbo.py');
  const args = [
    scriptPath,
    '--model', modelId,
    '--repo', model.repo,
    '--prompt', prompt,
    '--height', String(height),
    '--width', String(width),
    '--steps', String(steps),
    '--guidance', String(guidance ?? 1.0),
    '--seed', String(seed),
    '--output', outputPath,
  ];
  if (model.pipelineClass === 'QwenImage21Pipeline') {
    if (referenceImagePaths.length + (initImagePath ? 1 : 0) > 10) {
      throw new ServerError('Qwen Image 2.1 accepts at most 10 input images', { status: 400, code: 'TOO_MANY_INPUT_IMAGES' });
    }
    if (referenceImagePaths.length) args.push('--reference-images', ...referenceImagePaths);
  }
  if (negativePrompt) args.push('--negative-prompt', negativePrompt);
  if (initImagePath) args.push('--image-path', initImagePath);
  if (initImagePath && initImageStrength != null) args.push('--image-strength', String(initImageStrength));
  if (stepwiseDir) args.push('--stepwise-image-output-dir', stepwiseDir);
  if (loraPaths?.length) args.push('--lora-paths', ...loraPaths);
  if (loraScales?.length) args.push('--lora-scales', ...loraScales.map(String));
  if (model.pipelineClass) args.push('--pipeline-class', String(model.pipelineClass));
  if (model.usePromptEnhancer) args.push('--use-pe');
  // HiDream needs a 4th text encoder loaded separately (Llama-3.1-8B) —
  // the Diffusers HiDreamImagePipeline expects `text_encoder_4` /
  // `tokenizer_4` kwargs at from_pretrained() time. The runner script
  // branches on these flags; Z-Image / ERNIE / Qwen leave them unset.
  if (model.textEncoderRepo) args.push('--text-encoder-repo', String(model.textEncoderRepo));
  if (model.textEncoderClass) args.push('--text-encoder-class', String(model.textEncoderClass));
  if (model.tokenizerClass) args.push('--tokenizer-class', String(model.tokenizerClass));
  return { bin: torchPython, args, providerInputs: {
    initImagePath: initImagePath || null,
    referenceImagePaths: model.pipelineClass === 'QwenImage21Pipeline' ? referenceImagePaths : [],
  } };
};

// Resolves the repo / quantization / sibling repos / reference images FLUX.2
// actually renders with. A LoRA reroutes a quantized base onto bf16.
const flux2LoraRoute = (model, { loraPaths, referenceImagePaths, referenceImageStrengths }) => {
  const modelId = model?.id;
  let repo = model.repo;
  let quantization = model.quantization || 'sdnq';
  let { tokenizerRepo, basePipelineRepo, kvRepo } = model;
  let refImagePaths = referenceImagePaths;
  let refImageStrengths = referenceImageStrengths;
  // LoRA + quantized base is incompatible: PEFT can't inject an adapter into
  // SDNQ/int8-quantized Linear layers, and the runner swallows the failure
  // into a base render (lora_utils.apply_loras), so the LoRA silently does
  // nothing. The adapter was trained against the bf16 base anyway — route the
  // render onto it.
  if (loraPaths?.length && quantization !== 'none') {
    const bf16 = flux2Bf16BaseRepo(model);
    if (!bf16) {
      throw new ServerError(
        `Can't render a LoRA on "${modelId}" — a LoRA needs a bf16 FLUX.2 base and the size variant couldn't be resolved`,
        { status: 400, code: 'IMAGE_GEN_LORA_NEEDS_BF16' },
      );
    }
    console.log(`🎚️  flux2 LoRA render → routing ${modelId} (${quantization}) onto bf16 base ${bf16}`);
    repo = bf16;
    quantization = 'none';
    tokenizerRepo = null;
    basePipelineRepo = null;
    // Multi-reference editing needs the `-kv` sibling repo, which the bf16
    // LoRA route doesn't load (and the 4B variant has none). Drop the refs so
    // the LoRA render proceeds as txt2img/i2i instead of the runner hard-
    // failing on the missing kv pipeline — the LoRA is the primary intent
    // when one is attached. i2i (single init image) is unaffected.
    kvRepo = null;
    if (refImagePaths?.length) {
      console.log(`⚠️ flux2 LoRA render dropped ${refImagePaths.length} reference image(s) — multi-ref editing isn't supported on the bf16 LoRA route`);
      refImagePaths = [];
      refImageStrengths = [];
    }
  }
  return { repo, quantization, tokenizerRepo, basePipelineRepo, kvRepo, refImagePaths, refImageStrengths };
};

const flux2RenderArgs = (model, inputs) => {
  const { prompt, negativePrompt, width, height, steps, guidance, seed, outputPath, loraPaths = [], loraScales = [], stepwiseDir, initImagePath, initImageStrength } = inputs;
  const modelId = model?.id;
  if (!model.repo) {
    throw new ServerError(
      `FLUX.2 model "${modelId}" is missing the 'repo' field in data/media-models.json`,
      { status: 500, code: 'IMAGE_GEN_FLUX2_MISCONFIGURED' },
    );
  }
  const { repo, quantization, tokenizerRepo, basePipelineRepo, kvRepo, refImagePaths, refImageStrengths } = flux2LoraRoute(model, inputs);
  if (quantization !== 'sdnq' && quantization !== 'int8' && quantization !== 'none') {
    throw new ServerError(
      `FLUX.2 model "${modelId}" has unsupported quantization "${quantization}" (supported: sdnq, int8, none)`,
      { status: 500, code: 'IMAGE_GEN_FLUX2_MISCONFIGURED' },
    );
  }
  if (quantization === 'sdnq' && !tokenizerRepo) {
    throw new ServerError(
      `FLUX.2 SDNQ model "${modelId}" requires 'tokenizerRepo' (the gated base repo for the tokenizer)`,
      { status: 500, code: 'IMAGE_GEN_FLUX2_MISCONFIGURED' },
    );
  }
  if (quantization === 'int8' && !basePipelineRepo) {
    throw new ServerError(
      `FLUX.2 Int8 model "${modelId}" requires 'basePipelineRepo' (the gated base repo for VAE/scheduler)`,
      { status: 500, code: 'IMAGE_GEN_FLUX2_MISCONFIGURED' },
    );
  }
  // quantization=none uses model.repo directly (gated base repo). No
  // sibling-repo flag required, but the repo must be the gated base.
  const flux2Python = resolveFlux2Python();
  if (!flux2Python) {
    throw new ServerError(
      `FLUX.2 venv not found. Run \`INSTALL_FLUX2=1 bash scripts/setup-image-video.sh\` to bootstrap it (expected at ${FLUX2_VENV_DEFAULT}).`,
      { status: 400, code: 'IMAGE_GEN_FLUX2_NOT_INSTALLED' },
    );
  }
  const scriptPath = join(PATHS.root, 'scripts', 'flux2_macos.py');
  // No --metadata flag: local.js's proc.on('close') already writes the
  // canonical sidecar at <jobId>.metadata.json after a successful exit.
  // Letting the runner write its own would duplicate work and the JS
  // sidecar would clobber any flux2-specific fields anyway.
  const args = [
    scriptPath,
    '--model', modelId,
    '--quantization', quantization,
    '--repo', repo,
    '--prompt', prompt,
    '--height', String(height),
    '--width', String(width),
    '--steps', String(steps),
    '--guidance', String(guidance ?? 0),
    '--seed', String(seed),
    '--output', outputPath,
  ];
  if (tokenizerRepo) args.push('--tokenizer-repo', tokenizerRepo);
  if (basePipelineRepo) args.push('--base-pipeline-repo', basePipelineRepo);
  // bf16 multi-reference editing loads the `-kv` sibling repo (whose
  // transformer is tuned for reference editing) instead of `repo`.
  // The runner only uses --kv-repo when --reference-images is also present;
  // the plain text/i2i bf16 path stays on the base repo.
  if (kvRepo) args.push('--kv-repo', kvRepo);
  if (negativePrompt) args.push('--negative-prompt', negativePrompt);
  if (initImagePath) args.push('--image-path', initImagePath);
  if (initImagePath && initImageStrength != null) args.push('--image-strength', String(initImageStrength));
  // Multi-reference editing for FLUX.2. When the path list is non-empty,
  // scripts/flux2_macos.py loads Flux2KleinKVPipeline (instead of the
  // single-image Flux2KleinPipeline) and passes the refs as image=[PIL...].
  // The route always emits parallel referenceImageStrengths (defaulting to
  // 1.0 per ref); the runner honors them per-reference via a runtime patch
  // on Flux2KVLayerCache.store + _flux2_kv_causal_attention.
  if (refImagePaths?.length) {
    args.push('--reference-images', ...refImagePaths);
    if (refImageStrengths?.length) {
      args.push('--reference-strengths', ...refImageStrengths.map(String));
    }
  }
  if (stepwiseDir) args.push('--stepwise-image-output-dir', stepwiseDir);
  if (loraPaths?.length) args.push('--lora-paths', ...loraPaths);
  if (loraScales?.length) args.push('--lora-scales', ...loraScales.map(String));
  return { bin: flux2Python, args, providerInputs: { initImagePath: initImagePath || null, referenceImagePaths: refImagePaths } };
};

// imagine_win.py does not implement i2i — silently drop the init-image
// args so the request still produces a normal txt2img result rather
// than failing argparse with "unrecognized arguments".
const mfluxWindowsArgs = ({ pythonPath, model, prompt, negativePrompt, width, height, steps, guidance, seed, quantize, outputPath, loraPaths = [], loraScales = [] }) => {
  const scriptPath = join(PATHS.root, 'scripts', 'imagine_win.py');
  return {
    bin: pythonPath,
    providerInputs: { initImagePath: null, referenceImagePaths: [] },
    args: [scriptPath, '--model', model?.id, '--prompt', prompt, '--height', String(height), '--width', String(width), '--steps', String(steps), '--seed', String(seed), '--quantize', String(quantize), '--output', outputPath, '--metadata',
      ...(guidance > 0 ? ['--guidance', String(guidance)] : []),
      ...(negativePrompt ? ['--negative-prompt', negativePrompt] : []),
      ...(loraPaths.length ? ['--lora-paths', ...loraPaths] : []),
      ...(loraScales.length ? ['--lora-scales', ...loraScales.map(String)] : []),
    ],
  };
};

const mfluxArgs = ({ pythonPath, model, prompt, negativePrompt, width, height, steps, guidance, seed, quantize, outputPath, loraPaths = [], loraScales = [], stepwiseDir, initImagePath, initImageStrength }) => {
  const bin = join(dirname(pythonPath), 'mflux-generate');
  const args = ['--model', model?.id, '--prompt', prompt, '--height', String(height), '--width', String(width), '--steps', String(steps), '--seed', String(seed), '--quantize', String(quantize), '--output', outputPath, '--metadata'];
  if (guidance > 0) args.push('--guidance', String(guidance));
  if (negativePrompt) args.push('--negative-prompt', negativePrompt);
  if (loraPaths.length) args.push('--lora-paths', ...loraPaths);
  if (loraScales.length) args.push('--lora-scales', ...loraScales.map(String));
  if (initImagePath) args.push('--image-path', initImagePath);
  if (initImagePath && initImageStrength != null) args.push('--image-strength', String(initImageStrength));
  // mflux writes one PNG per step here as it diffuses; we watch the dir and
  // stream the latest frame back to the client as `currentImage` for the
  // live-preview area.
  if (stepwiseDir) args.push('--stepwise-image-output-dir', stepwiseDir);
  return { bin, args, providerInputs: { initImagePath: initImagePath || null, referenceImagePaths: [] } };
};

export const buildArgs = ({ loraPaths = [], loraScales = [], referenceImagePaths = [], referenceImageStrengths = [], platform = process.platform, ...rest }) => {
  const inputs = { ...rest, loraPaths, loraScales, referenceImagePaths, referenceImageStrengths };
  const { model } = inputs;
  if (usesMossSwift(model)) return mossRenderArgs(inputs);
  if (usesDiffusersRunner(model)) return diffusersRenderArgs(inputs);
  if (isFlux2(model)) return flux2RenderArgs(model, inputs);
  if (platform === 'win32') return mfluxWindowsArgs(inputs);
  return mfluxArgs(inputs);
};

// Clamp 0..1 with a finite-fallback — Math.max/min preserve NaN, so a
// corrupt sidecar value like Number('bad') would slip through and end up
// serialized into metadata / the CLI flag. `null` here means "no strength
// sent" (init-image), which the args builder already gates on; for refs
// we fall back to 1.0 (full influence).
const clampStrength01 = (raw, fallback) => {
  const n = Number(raw);
  if (!Number.isFinite(n)) return fallback;
  return Math.max(0, Math.min(1, n));
};

/**
 * Build the resolved/validated render parameters + sidecar `meta` object for a
 * generation job. Factored out of `generateImage` so the resolution rules
 * (seed/steps/guidance defaults, LoRA prefix-check, init/reference path
 * re-anchoring, strength clamping) are unit-testable without spawning Python
 * or touching the gallery filesystem.
 *
 * Filesystem touch-points are injected so the function stays pure:
 * - `resolveInputPath(rawPath)` — re-anchors an init/reference path against the
 *   approved image roots; returns the validated absolute path or `null`
 *   (production passes `resolveImageInputPath`).
 * - `loraExists(absPath)` — whether a prefix-checked LoRA path exists on disk
 *   (production passes `existsSync`).
 * - `loraTriggerWords` — `{ [loraBasename]: string[] }` read from the LoRA
 *   sidecars by `generateImage`, so the trigger-word weave (#4665) needs no I/O
 *   of its own.
 *
 * `meta` is the exact object `generateImage` persists as the `<jobId>.metadata.json`
 * sidecar AND spreads into the in-memory job + activeJob snapshots, so the
 * shape returned here is the contract the gallery/Remix flow reads back.
 */
export function buildSidecarMeta({
  jobId,
  model,
  prompt,
  negativePrompt = '',
  modelId,
  width,
  height,
  steps,
  guidance,
  seed,
  quantize,
  loraFilenames = [],
  loraPaths = [],
  loraScales = [],
  // LoRA trigger-word weaving (#4665). `loraTriggerWords` maps a LoRA basename
  // to its sidecar `triggerWords` array; `generateImage` reads the sidecars and
  // passes the map so this stays pure. Keyed rather than positional because the
  // valid-LoRA order is only known after the prefix-check below.
  loraTriggerWords = null,
  // License map keyed by LoRA basename, read from sidecars by generateImage
  // so this stays pure. Missing entries stamp license: null (unknown).
  loraLicenses = null,
  // The labeled additions the composer put around the user's text (lib/modelInput.js).
  promptAdditions = [],
  initImagePath = null,
  initImageStrength = null,
  referenceImagePaths = [],
  referenceImageStrengths = [],
  visualConditioning = null,
  // SynthID-defeat regen lineage. When `regenOf` is set, this render is a
  // post-hoc round-trip of an existing gallery image through local FLUX
  // img2img (issue #912) — stamp the source filename as `cleanedFrom` (so the
  // lightbox variant toggle groups the regen under its source the same way a
  // cleaned copy is) plus explicit `regenerated`/`regenSteps`/`regenStrength`/
  // `regenModelId` so the sidecar lineage stays honest about how it was made.
  regenOf = null,
  resolveInputPath,
  loraExists,
  now = () => new Date().toISOString(),
}) {
  const filename = `${jobId}.png`;
  const actualSeed = seed != null && seed !== '' ? Number(seed) : Math.floor(Math.random() * 2147483647);
  const actualSteps = steps ? Number(steps) : model.steps;
  // Step-wise distilled models (Schnell / FLUX.2 Klein / Z-Image-Turbo) ignore
  // any guidance scale > 1.0 internally; passing a real value just produces a
  // "Guidance scale X is ignored for step-wise distilled models." warning on
  // every render. Clamp to ≤1.0 (rather than hard-pin to 1.0) so registry
  // entries that intentionally use 0.0 — e.g. Flux.1 Schnell, where the mflux
  // runner historically *omits* --guidance entirely on 0 — keep their existing
  // behavior. The clamp keeps FLUX.2 / Z-Image / ERNIE quiet while leaving
  // sub-1.0 values (including 0.0) untouched.
  const requestedGuidance = guidance != null && guidance !== '' ? Number(guidance) : model.guidance;
  const actualGuidance = model.cfgDisabled
    ? Math.min(1.0, Number.isFinite(requestedGuidance) ? requestedGuidance : 1.0)
    : requestedGuidance;
  // The new client-side surface sends `loraFilenames` (basenames only); the
  // server resolves them against PATHS.loras. `loraPaths` is kept as a
  // back-compat input for old gallery sidecars that stored absolute paths
  // pre-refactor — both go through the same resolve+prefix-check.
  const lorasRoot = resolvePath(PATHS.loras) + PATH_SEP;
  const candidates = [
    ...loraFilenames.map((f) => (typeof f === 'string' ? join(PATHS.loras, basename(f)) : null)),
    ...loraPaths,
  ];
  const validLoras = candidates.filter((p) => {
    if (!p || typeof p !== 'string') return false;
    const resolved = resolvePath(p);
    if (!resolved.startsWith(lorasRoot)) return false;
    return loraExists(resolved);
  });

  // Store loraFilenames (basenames) in the sidecar going forward — that's
  // what the new client API uses for remix. Keep `loraPaths` populated too
  // so older code paths reading the sidecar don't break.
  const validLoraFilenames = validLoras.map((p) => basename(p));
  // i2i: defense in depth — the route already validated a fresh request,
  // but an old sidecar replay can carry a stale absolute path outside the
  // approved image roots. resolveInputPath accepts gallery + image-refs
  // + visual templates — the latter so the universe-builder reference-sheet
  // renderer can use a shipped layout template as the init-image anchor.
  const validInitImagePath = (initImagePath && typeof initImagePath === 'string')
    ? resolveInputPath(initImagePath)
    : null;
  const validInitImageStrength = validInitImagePath && initImageStrength != null
    ? clampStrength01(initImageStrength, null)
    : null;
  // Multi-reference: re-anchor each path through resolveInputPath so a
  // sidecar replay can't sneak a path outside the approved image roots into
  // the runner. Accepts gallery + image-refs + visual templates — the gallery
  // path lets a canon portrait (e.g. character.primaryImageRef) flow in as a
  // multi-ref input. Pair each path with its strength BEFORE filtering so a
  // rejected entry doesn't shift the strength array — otherwise the surviving
  // path would inherit the wrong slot's strength.
  const rawRefPaths = Array.isArray(referenceImagePaths) ? referenceImagePaths : [];
  const validReferences = rawRefPaths
    .map((p, i) => {
      const resolved = typeof p === 'string' ? resolveInputPath(p) : null;
      if (!resolved) return null;
      const rawStrength = referenceImageStrengths?.[i];
      const strength = rawStrength != null ? clampStrength01(rawStrength, 1.0) : 1.0;
      return { path: resolved, strength };
    })
    .filter(Boolean);
  const validReferenceImagePaths = validReferences.map((r) => r.path);
  const validReferenceImageStrengths = validReferences.map((r) => r.strength);
  // `referenceImageStrengths` is honored end-to-end: the FLUX.2 runner installs
  // a Flux2KVLayerCache.store + _flux2_kv_causal_attention patch that scales
  // each reference's V slice by the corresponding strength (1.0 = upstream
  // baseline, 0.0 = ignored). Mirrors the Python sidecar's `referenceStrengths`.
  const meta = { id: jobId, prompt, negativePrompt, modelId, seed: actualSeed, width: Number(width), height: Number(height), steps: actualSteps, guidance: actualGuidance, quantize, filename, loraFilenames: validLoraFilenames, loraPaths: validLoras, loraScales, initImageFilename: validInitImagePath ? basename(validInitImagePath) : null, initImageStrength: validInitImageStrength, referenceImageFilenames: validReferenceImagePaths.map((p) => basename(p)), referenceImageStrengths: validReferenceImageStrengths, ...(visualConditioning ? { visualConditioning } : {}), createdAt: now() };
  // Regen lineage (issue #912). `regenOf` is the source gallery filename this
  // render was generated from. We reuse the existing `cleanedFrom` field so the
  // lightbox's `computeImageVariantGroup` groups the regen under its source with
  // zero changes to the grouping key, and add explicit regen* fields so the
  // sidecar honestly records that the per-pixel watermark was overwritten by a
  // fresh sampling pass rather than stripped. `regenStrength`/`regenSteps`/
  // `regenModelId` mirror the resolved render params (not the raw inputs) so a
  // replayed/clamped value is what's recorded.
  // Only stamp the lineage when the init image actually resolved — if the
  // source path was rejected/missing, this render degraded to txt2img and is
  // NOT a regen of anything, so claiming `regenerated: true` would be a lie.
  if (typeof regenOf === 'string' && regenOf && validInitImagePath) {
    meta.cleanedFrom = regenOf;
    meta.regenerated = true;
    // Explicit method so consumers never infer it by absence — the CPU path
    // stamps 'light-spatial', this GPU round-trip stamps 'flux'.
    meta.regenMethod = 'flux';
    meta.regenStrength = validInitImageStrength;
    meta.regenSteps = actualSteps;
    meta.regenModelId = modelId;
  }
  // Weave each selected LoRA's activation token into the prompt that actually
  // reaches the runner (#4665). Provenance stays honest: `meta.prompt` remains
  // the user's own text, so a Remix re-derives triggers from whatever LoRAs are
  // selected at THAT time instead of compounding this render's clause. The
  // render-time text and what was added are recorded alongside it, and only when
  // something was actually appended — an un-woven render's sidecar stays
  // byte-identical to every sidecar written before this feature.
  const { prompt: wovenPrompt, added: addedTriggerWords } = weaveLoraTriggers(
    prompt,
    validLoraFilenames.map((f) => loraTriggerWords?.[f]),
  );
  const renderPrompt = addedTriggerWords.length ? wovenPrompt : prompt;
  if (addedTriggerWords.length) {
    meta.renderPrompt = renderPrompt;
    meta.addedTriggerWords = addedTriggerWords;
  }
  Object.assign(meta, sentPromptRecord({
    sentPrompt: renderPrompt, sentNegativePrompt: negativePrompt, carried: carriedPromptAdditions({ promptAdditions }),
    added: [promptAddition('lora-triggers', 'LoRA trigger words', addedTriggerWords.join(', '))],
  }));
  // Stamp the licenses known at THIS render. A later re-read of the LoRA
  // sidecar or model card must not rewrite what was true when the pixels
  // were made (#5638). Unknown stays null.
  meta.provenance = provenanceForRender({
    model: {
      id: modelId,
      name: model?.name || modelId,
      license: usesMossSwift(model) ? 'apache-2.0' : model?.license,
      repo: usesMossSwift(model) ? MOSS_MANIFEST.repo : model?.repo,
      disclosure: model?.disclosure,
    },
    loras: validLoraFilenames.map((filename) => ({
      filename,
      ...(loraLicenses?.[filename] || {}),
    })),
    capturedAt: meta.createdAt,
  });
  return {
    meta,
    renderPrompt,
    addedTriggerWords,
    actualSeed,
    actualSteps,
    actualGuidance,
    validLoras,
    validInitImagePath,
    validInitImageStrength,
    validReferenceImagePaths,
    validReferenceImageStrengths,
  };
}

/**
 * Resolve where a render's PNG + sidecar go (issue #2264). Pure so the
 * gallery-vs-temp branch is unit-testable without spawning a render.
 *
 * - No `outputTarget` (the default, every existing caller) → the gallery dir
 *   with a sidecar written — the lightbox/regenerate/gen behavior, untouched.
 * - `outputTarget.dir` (the Image Cleaner's temp render) → that dir, and
 *   `skipSidecar` (defaulting true for a non-gallery dir) suppresses the
 *   `<jobId>.metadata.json` write + the gallery `completed` index/federate hooks.
 *
 * A gallery-dir target always keeps its sidecar even if `skipSidecar` was
 * passed — a gallery citizen without a sidecar would be an un-remixable orphan.
 */
export function resolveOutputPlacement(outputTarget) {
  const target = outputTarget && typeof outputTarget === 'object' ? outputTarget : null;
  const outputDir = target?.dir && typeof target.dir === 'string' ? target.dir : PATHS.images;
  const isGallery = outputDir === PATHS.images;
  // Non-gallery renders default to no sidecar; a gallery render always writes one.
  const skipSidecar = isGallery ? false : (target?.skipSidecar !== false);
  return { outputDir, skipSidecar, isGallery };
}

const IMAGE_EXECUTION_MARKER = 'IMAGE_EXECUTION:';
const IMAGE_EXECUTION_DEVICES = new Set(['auto', 'mps', 'cuda', 'cpu']);
const IMAGE_EXECUTION_EFFECTIVE_DEVICES = new Set(['mps', 'cuda', 'cpu']);
const IMAGE_EXECUTION_PLACEMENTS = new Set(['mps', 'cuda', 'cuda+offload', 'cpu']);
const IMAGE_EXECUTION_RUNTIMES = new Set(['flux2', 'diffusers-image']);
const IMAGE_EXECUTION_PACKAGES = new Set(['torch', 'diffusers', 'transformers', 'accelerate']);

const boundedString = (value, max = 80) => (typeof value === 'string' && value.length > 0 && value.length <= max ? value : null);

// A malformed marker is evidence of neither GPU nor CPU execution. Keep it
// distinct from an older runner that emitted no marker at all, while refusing
// to persist arbitrary subprocess JSON into a gallery sidecar.
export function parseImageExecutionMarker(line) {
  if (typeof line !== 'string' || !line.startsWith(IMAGE_EXECUTION_MARKER)) return null;
  let value;
  try {
    value = JSON.parse(line.slice(IMAGE_EXECUTION_MARKER.length));
  } catch {
    return { state: 'malformed' };
  }
  if (!value || value.version !== 1
    || !IMAGE_EXECUTION_DEVICES.has(value.requestedDevice)
    || !IMAGE_EXECUTION_EFFECTIVE_DEVICES.has(value.effectiveDevice)
    || !IMAGE_EXECUTION_PLACEMENTS.has(value.placement)
    || !IMAGE_EXECUTION_RUNTIMES.has(value.runtime?.runtime)
    || typeof value.cpuFallback !== 'boolean') return { state: 'malformed' };
  const expectedState = value.effectiveDevice === 'cpu' ? 'degraded' : 'confirmed';
  if (value.state !== expectedState || value.cpuFallback !== (expectedState === 'degraded')) return { state: 'malformed' };
  const versions = Object.fromEntries(Object.entries(value.runtime.versions || {})
    .filter(([name, version]) => IMAGE_EXECUTION_PACKAGES.has(name) && boundedString(version))
    .map(([name, version]) => [name, version]));
  return {
    version: 1,
    state: expectedState,
    requestedDevice: value.requestedDevice,
    effectiveDevice: value.effectiveDevice,
    placement: value.placement,
    cpuFallback: value.cpuFallback,
    runtime: { runtime: value.runtime.runtime, versions },
  };
}

/**
 * What the local runner would receive for this prompt — the LoRA trigger weave
 * included — as the compose preview's record (#11317). Same buildSidecarMeta
 * the render calls.
 */
export async function localSentPrompt({ model, modelId, prompt = '', negativePrompt = '', loraFilenames = [], loraPaths = [], promptAdditions = [] }) {
  const loraTriggerWords = await readTriggerWordsByFilename([...loraFilenames, ...loraPaths]);
  const { meta } = buildSidecarMeta({
    jobId: 'preview', model: model || { id: modelId }, prompt, negativePrompt, modelId,
    loraFilenames, loraPaths, loraTriggerWords, promptAdditions,
    resolveInputPath: resolveImageInputPath, loraExists: existsSync,
  });
  return sentPromptRecord({ sentPrompt: meta.sentPrompt, sentNegativePrompt: meta.sentNegativePrompt, carried: meta.promptAdditions || [] });
}

export async function generateImage({ pythonPath, prompt = '', negativePrompt = '', modelId = LOCAL_IMAGEGEN_DEFAULT_MODEL, width = 1024, height = 1024, steps, guidance, seed, quantize = '8', loraFilenames = [], loraPaths = [], loraScales = [], initImagePath = null, initImageStrength = null, referenceImagePaths = [], referenceImageStrengths = [], visualConditioning = null, jobId: providedJobId = null, cleanC2PA = false, denoise = false, regenOf = null, upscaleTo = null, outputTarget = null, promptAdditions = [] }) {
  // The ingestion instant `renderTimingFields` measures from — the queue calls
  // generateImage the moment it picks this job up. See lib/renderTiming.js.
  const renderStartedAtMs = Date.now();
  // Empty prompt is allowed: img2img / edit / unconditional renders are driven
  // by the init image (or run unconditionally), so text isn't required. The
  // mflux/diffusers runners accept an empty `--prompt` — the regen pass (#912)
  // has always relied on this for minimal-mutation, watermark-overwriting img2img.
  // Single-flight is enforced by the mediaJobQueue worker upstream. Direct
  // callers that bypass the queue must not run two concurrent renders — the
  // activeProcess handle below would be clobbered and cancel() would orphan
  // the first child.
  // loadMediaModels memoizes — on-disk edits to data/media-models.json still
  // need a server restart to apply. Don't re-check model.broken here:
  // getImageModels() already filtered current-platform entries; an extra
  // check would also reject entries broken on the OTHER platform (e.g.
  // 'windows' on a macOS box).
  const model = getImageModels().find((m) => m.id === modelId);
  if (!model) throw new ServerError(`Unknown or unsupported model: ${modelId}`, { status: 400, code: 'VALIDATION_ERROR' });
  if (!isHardwareCompatible(model.hardwareCompatibility)) {
    throw new ServerError(
      hardwareUnavailableReason(`Image model "${modelId}"`, model.hardwareCompatibility),
      { status: 400, code: 'MODEL_HARDWARE_UNAVAILABLE' },
    );
  }
  // Both flux2 and z-image runners resolve their own Python via the FLUX.2
  // venv — only the legacy mflux/imagine_win path needs the user-configured
  // Settings > Image Gen pythonPath.
  if (usesMossSwift(model)) {
    // Check raw requests before sidecar normalization can discard a missing input file or LoRA.
    if (loraFilenames.length || loraPaths.length || initImagePath || referenceImagePaths.length) {
      throw new ServerError('MOSS SFT supports text-to-image only; remove LoRAs and input images.', { status: 400, code: 'MOSS_INPUT_UNSUPPORTED' });
    }
    const { diagnoseLocalRuntime } = await import('./localRuntime.js');
    const runtime = await diagnoseLocalRuntime({ modelId });
    if (runtime.readiness !== 'ready') throw new ServerError(runtime.reason, { status: 400, code: 'MOSS_NOT_READY' });
  }
  if (!usesTorchVenv(model) && !usesMossSwift(model) && !pythonPath) {
    throw new ServerError('Python path not configured — set it in Settings > Image Gen', { status: 400, code: 'IMAGE_GEN_NOT_CONFIGURED' });
  }
  // Health, not mere presence. buildArgs below only checks that the shared
  // torch venv's python BINARY exists, so a venv left half-installed (killed
  // mid-download, a hand-run pip upgrade that broke diffusers) spawned anyway
  // and died with an ImportError the caller saw as a bare "Exit code 1" — the
  // Decks page rendered that as an unexplained "Failed" badge. Refuse up front
  // with the same reason and one-button remedy the status probe reports.
  if (usesTorchVenv(model)) {
    const healthy = await isFlux2VenvHealthy(model.pipelineClass).then((v) => v).catch(() => null);
    if (healthy === false) {
      throw new ServerError(
        `The shared torch image runtime is not installed or healthy (expected at ${FLUX2_VENV_DEFAULT}). Install it from Settings › Image Gen › Local, then retry. FLUX.2, Z-Image, ERNIE, HiDream and Qwen all render through it.`,
        // Same code buildArgs throws when the venv's python is missing outright:
        // "the shared torch runtime is not usable" is one state to a caller,
        // whether it is absent or broken.
        { status: 400, code: 'IMAGE_GEN_FLUX2_NOT_INSTALLED' },
      );
    }
  }
  // FLUX.2 and Z-Image runners now load LoRAs via diffusers'
  // pipe.load_lora_weights — but only LoRAs trained against the matching
  // base model will produce sensible output. The LoRA picker UI uses the
  // sidecar's `runnerFamily` field to filter; we don't enforce here so a
  // user can deliberately experiment with off-family weights and see what
  // happens (the runner will surface a shape-mismatch error from diffusers).

  // Non-gallery render target (issue #2264): the Image Cleaner's GPU FLUX
  // round-trip renders to a temp dir with NO sidecar, so a clean pass never
  // pollutes the gallery by default. See `resolveOutputPlacement` for the exact
  // branch logic (unit-tested in local.test.js).
  const { outputDir, skipSidecar } = resolveOutputPlacement(outputTarget);

  await ensureDir(outputDir);
  await ensureDir(PATHS.loras);

  const jobId = providedJobId || randomUUID();
  const filename = `${jobId}.png`;
  const outputPath = join(outputDir, filename);
  // The public path a gallery render mounts at (`/data/images/<f>`). A
  // non-gallery render has no static mount, so the queue reads the finished
  // bytes off `outputPath` directly (surfaced as `outputPath` in the result).
  const publicPath = outputDir === PATHS.images ? `/data/images/${filename}` : null;
  // Trigger words for the selected LoRAs (#4665). Read against the RAW request
  // (a superset of what survives the prefix-check inside buildSidecarMeta) so
  // the map is available before validation runs; an absent or legacy sidecar
  // simply contributes nothing and the render is unchanged. A no-LoRA render
  // short-circuits inside the helper, so the common case does zero extra I/O.
  const loraTriggerWords = await readTriggerWordsByFilename([...loraFilenames, ...loraPaths]);
  const loraLicenses = await readLoraLicensesByFilename([...loraFilenames, ...loraPaths]);
  const {
    meta,
    renderPrompt,
    addedTriggerWords,
    actualSeed,
    actualSteps,
    actualGuidance,
    validLoras,
    validInitImagePath,
    validInitImageStrength,
    validReferenceImagePaths,
    validReferenceImageStrengths,
  } = buildSidecarMeta({
    jobId,
    model,
    prompt,
    negativePrompt,
    modelId,
    width,
    height,
    steps,
    guidance,
    seed,
    quantize,
    loraFilenames,
    loraPaths,
    loraScales,
    initImagePath,
    initImageStrength,
    referenceImagePaths,
    referenceImageStrengths,
    visualConditioning,
    regenOf,
    loraTriggerWords,
    loraLicenses,
    promptAdditions,
    resolveInputPath: resolveImageInputPath,
    loraExists: existsSync,
  });
  if (usesMossSwift(model)) {
    meta.quantize = null;
    meta.quantization = 'bf16';
    meta.modelRepo = MOSS_MANIFEST.repo;
    meta.modelRevision = MOSS_MANIFEST.revision;
    meta.nativeRuntime = { runtime: 'moss-swift', sourceRevision: MOSS_MANIFEST.sourceRevision, adapterVersion: MOSS_MANIFEST.adapterVersion };
  }
  if (addedTriggerWords.length) {
    console.log(`🔤 LoRA trigger words woven [${jobId.slice(0, 8)}]: ${addedTriggerWords.join(', ')}`);
  }
  const job = { ...meta, clients: [], status: 'running', renderStartedAtMs };
  jobs.set(jobId, job);

  // Per-job stepwise output dir under the OS temp dir. mflux writes one PNG
  // per inference step here; we watch and stream the latest as `currentImage`.
  const stepwiseDir = await mkdtemp(join(tmpdir(), 'portos-stepwise-'));
  const preparation = { cancelRequested: false };
  preparing = preparation;

  let heavyClaim = null;
  const releaseHeavyClaim = () => {
    if (!heavyClaim?.release) return Promise.resolve();
    return maintenance.continueSettlement(() => heavyClaim.release())
      .catch((err) => {
        maintenance.markCurrentUnsettled();
        console.error(`❌ Image generation claim release [${jobId.slice(0, 8)}]: ${err.message}`);
      });
  };
  const removeStepwise = () => maintenance.continueSettlement(
    () => rmGuarded(stepwiseDir, { recursive: true, force: true }),
  ).catch((err) => {
    maintenance.markCurrentUnsettled();
    console.error(`❌ Image generation scratch cleanup [${jobId.slice(0, 8)}]: ${err.message}`);
  });
  let bin, args, providerInputs;
  let proc;
  let claimHandedOff = false;
  let takeEarlyExit = null;
  let startedEmitted = false;
  try {
    // `renderPrompt` — the user's prompt plus any LoRA activation tokens it was
    // missing (#4665). Identical to `prompt` when nothing was woven.
    ({ bin, args, providerInputs } = buildArgs({ pythonPath, model, prompt: renderPrompt, negativePrompt, width: Number(width), height: Number(height), steps: actualSteps, guidance: actualGuidance, seed: actualSeed, quantize, outputPath, loraPaths: validLoras, loraScales, stepwiseDir, initImagePath: validInitImagePath, initImageStrength: validInitImageStrength, referenceImagePaths: validReferenceImagePaths, referenceImageStrengths: validReferenceImageStrengths }));
    // Record only inputs the selected runner actually receives. Unsupported
    // references and Windows mflux init images remain explicit request evidence.
    const requestedInputs = [
      ...(meta.initImageFilename ? [{ role: 'initImage', filename: meta.initImageFilename }] : []),
      ...meta.referenceImageFilenames.map(filename => ({ role: 'referenceImages', filename })),
    ];
    const omittedInputs = [
      ...(validInitImagePath && !providerInputs.initImagePath ? [{ role: 'initImage', filename: meta.initImageFilename }] : []),
      ...validReferenceImagePaths.filter(path => !providerInputs.referenceImagePaths.includes(path))
        .map(path => ({ role: 'referenceImages', filename: basename(path) })),
    ];
    if (omittedInputs.length) {
      meta.requestedInputImages = requestedInputs;
      meta.omittedInputImages = omittedInputs.map(input => ({ ...input, reason: 'unsupported-render-path' }));
    }
    meta.inputProvenance = 'provider-inputs';
    meta.referenceImageFilenames = providerInputs.referenceImagePaths.map(path => basename(path));
    meta.referenceImageStrengths = validReferenceImageStrengths.filter((_, index) => providerInputs.referenceImagePaths.includes(validReferenceImagePaths[index]));
    if (!providerInputs.initImagePath) {
      meta.initImageFilename = null;
      meta.initImageStrength = null;
      for (const key of ['cleanedFrom', 'regenerated', 'regenMethod', 'regenStrength', 'regenSteps', 'regenModelId']) {
        delete meta[key];
        delete job[key];
      }
    }
    Object.assign(job, meta);
    heavyClaim = await claimHeavyLocalJob({ kind: 'local image generation', id: jobId });
    if (!heavyClaim.ok) {
      throw new ServerError(heavyClaim.message, { status: 409, code: 'HEAVY_LOCAL_JOB_BUSY', context: { holder: heavyClaim.holder } });
    }
    const { prepareLocalMemory, gpuBlockersMessage } = await import('../localMemory.js');
    const memoryReport = await prepareLocalMemory();
    // Something the unload above cannot evict already owns the GPU (today: the
    // vLLM Qwen container). Refuse here rather than let mflux die inside its
    // model load with an OOM that names neither the tenant nor the fix (#4766).
    if (memoryReport.blockers.length) {
      throw new ServerError(gpuBlockersMessage(memoryReport.blockers), { status: 409, code: 'GPU_BLOCKED', context: { blockers: memoryReport.blockers } });
    }
    if (memoryReport.unloaded.length) console.log(`🧹 Image generation [${jobId.slice(0, 8)}] freed ${memoryReport.unloaded.length} resident model(s)`);

    const childEnv = usesMossSwift(model) ? mossChildEnv() : await hfChildEnv();
    // Last spawn gate: a cancel() during the awaits above found no child to signal.
    if (preparation.cancelRequested) {
      throw new ServerError('Canceled before the render started', { status: 409, code: 'IMAGE_GEN_CANCELED' });
    }

    console.log(`🎨 Generating image [${jobId.slice(0, 8)}] local: ${modelId} ${width}x${height} steps=${actualSteps} references=${meta.referenceImageFilenames.length}`);
    imageGenEvents.emit('started', { generationId: jobId, totalSteps: actualSteps });
    startedEmitted = true;
    activeJob = { ...meta, generationId: jobId, totalSteps: actualSteps, step: 0, progress: 0, currentImage: null, mode: IMAGE_GEN_MODE.LOCAL };

    proc = spawn(bin, args, safeChildProcessOptions({ env: childEnv, stdio: ['ignore', 'pipe', 'pipe'] }));
    // Same tick as the spawn, before the claim handoff below awaits file I/O: a
    // child that dies inside that window would otherwise emit 'close' with no
    // listener, leaving the job running and the GPU lane held forever (#11761).
    takeEarlyExit = bufferChildExit(proc, { bufferOutput: true });
    activeProcess = proc;
    preparing = null;
    await heavyClaim.handoffTo?.(proc.pid);
    claimHandedOff = true;
  } catch (err) {
    if (preparing === preparation) preparing = null;
    // Nothing is wired to this job yet, so it can never report its own terminal
    // event — unwind it exactly the way the busy branch above does, or a refusal
    // strands a `running` entry and its stepwise dir every time.
    if (!claimHandedOff) {
      if (proc?.pid) {
        maintenance.markCurrentUnsettled();
        // No close handler is wired yet, so nothing else will ever reap this child.
        try {
          killWithEscalation(proc, { label: 'abandoned image child', stillRunning: () => true });
        } catch (killErr) {
          console.error(`❌ Abandoned image child would not stop [${jobId.slice(0, 8)}]: ${killErr.message}`);
        }
      }
      if (activeProcess === proc) activeProcess = null;
      if (activeJob?.generationId === jobId) activeJob = null;
      if (startedEmitted) {
        imageGenEvents.emit('failed', { mode: IMAGE_GEN_MODE.LOCAL, generationId: jobId, error: err.message });
      }
      await releaseHeavyClaim();
      jobs.delete(jobId);
      await removeStepwise();
    }
    throw err;
  }
  // Spawn ENOENT (missing/non-executable pythonPath) fires BOTH 'error' and
  // 'close' on Node — without this guard, a typo'd pythonPath emits two
  // 'failed' events to imageGenEvents and two SSE error frames to the
  // client. The mediaJobQueue's terminate() is idempotent on the first, but
  // the duplicate noise still confuses anything else listening. Track
  // whether we've finalized so the close handler can detect "already
  // handled" and skip the second emit.
  let finalized = false;
  let processError;
  proc.on('error', (err) => {
    processError = err;
    if (finalized || proc.pid) return;
    finalized = true;
    job.status = 'error';
    const reason = `Failed to spawn ${bin}: ${err.message}`;
    console.error(`❌ Image generation spawn error [${jobId.slice(0, 8)}]: ${reason}`);
    void releaseHeavyClaim();
    // The close handler skips its own watcher.close() once finalized.
    if (watcher) { try { watcher.close(); } catch { /* ignore */ } }
    void removeStepwise();
    dispatchTerminalEvent(
      jobId,
      () => broadcastSse(job, { type: 'error', error: reason }),
      () => imageGenEvents.emit('failed', { mode: IMAGE_GEN_MODE.LOCAL, generationId: jobId, error: reason }),
    );
    activeProcess = null;
    activeJob = null;

    closeJobAfterDelay(jobs, jobId);
  });

  // Watch the stepwise output dir for new PNGs. When a new file appears,
  // base64-encode the latest one and emit it as `currentImage`. fs.watch
  // fires multiple times per write — keep a single in-flight read and a
  // pending flag so we always get the *latest* frame without piling up reads.
  let watcher = null;
  let reading = false;
  let pendingFrame = false;
  const processLatestFrame = async () => {
    if (reading) { pendingFrame = true; return; }
    reading = true;
    try {
      // Sort by mtime, not filename. mflux names files like `step_1.png` …
      // `step_20.png` (no zero-padding), so alphabetical sort puts `step_2`
      // *after* `step_19` and we'd render an early-step latent (mostly noise)
      // instead of the latest. Also drop mflux's `seed_*_composite.png` —
      // it writes that grid right after every step, so its mtime always wins
      // the "latest" race and the user would see a growing thumbnail strip
      // instead of the live diffusion frame.
      const names = (await readdir(stepwiseDir)).filter((f) => f.endsWith('.png') && !f.includes('composite'));
      const stats = await Promise.all(names.map(async (n) => {
        const s = await stat(join(stepwiseDir, n)).catch(() => null);
        return s ? { n, mtimeMs: s.mtimeMs } : null;
      }));
      const latest = stats.filter(Boolean).sort((a, b) => b.mtimeMs - a.mtimeMs)[0]?.n;
      if (latest) {
        const buf = await readFile(join(stepwiseDir, latest));
        const currentImage = buf.toString('base64');
        if (activeJob && activeJob.generationId === jobId) activeJob.currentImage = currentImage;
        imageGenEvents.emit('progress', { generationId: jobId, currentImage });
      }
    } catch (err) {
      // Partial PNG mid-write or stepwise dir gone after cancel — common,
      // don't spam, but surface the message so a stalled preview is debuggable.
      console.log(`⚠️ Frame read error [${jobId.slice(0, 8)}]: ${err?.message}`);
    }
    reading = false;
    if (pendingFrame) { pendingFrame = false; processLatestFrame(); }
  };
  try {
    watcher = fsWatch(stepwiseDir, (event) => {
      if (event === 'rename') processLatestFrame();
    });
    // Windows raises EPERM here when the watched dir is deleted; with no listener
    // that is an uncaught exception and the server exits.
    watcher.on?.('error', (err) => {
      console.warn(`⚠️ Stepwise watcher error [${jobId.slice(0, 8)}]: ${err?.message}`);
    });
  } catch { /* if watch fails, we still get final image — degrade gracefully */ }

  // Bounded tail of recent stderr — only the last ~64KB is kept, since the
  // failure path only uses the trailing 10 lines for context. Without this
  // bound a noisy backend (HF download progress, deprecation warnings)
  // would grow this buffer for the full duration of a long render.
  const STDERR_TAIL_BYTES = 64 * 1024;
  let stderrBuffer = '';
  // Returns true when the line drove a progress event (so the pm2-log echo
  // below skips it — progress bars are spammy and already visible in the UI).
  // Status / debug / error lines fall through to console.log so a stuck render
  // (model download, HF auth probe, weight load) shows up in pm2 logs instead
  // of vanishing into the SSE channel only the browser ever sees.
  // Phase tracking. Lifecycle events from the runner (STAGE:download-pipeline,
  // STAGE:inference, etc.) flip the phase so the UI can show "Downloading
  // model weights" instead of misleading "step 0/8" while HF pulls multi-GB
  // shards. Inference progress events also tag themselves with the current
  // phase so the client knows whether `step/total` reflects download chunks
  // (out of N safetensors files) or actual generation steps.
  let currentPhase = 'starting';
  let isDownloading = false;
  const handleLine = (line) => {
    const trimmed = line.trim();
    if (!trimmed || PYTHON_NOISE_RE.test(trimmed)) return true;
    // Heartbeat — any non-noise line resets the queue's idle watchdog so
    // first-run multi-GB HF downloads don't trip the timeout when
    // tqdm is slow to update during connection-establishment.
    imageGenEvents.emit('activity', { generationId: jobId });

    const execution = parseImageExecutionMarker(trimmed);
    if (execution) {
      meta.executionProvenance = execution;
      job.executionProvenance = execution;
      if (activeJob?.generationId === jobId) activeJob.executionProvenance = execution;
      return true;
    }

    if (trimmed.startsWith('STAGE:')) {
      const rest = trimmed.slice(6); // strip 'STAGE:'
      const colon = rest.indexOf(':');
      const stage = colon === -1 ? rest : rest.slice(0, colon);
      const detail = colon === -1 ? '' : rest.slice(colon + 1);
      currentPhase = stage;
      // Track download phase for tqdm bar formatting
      isDownloading = stage.startsWith('download');
      broadcastSse(job, { type: 'stage', stage, detail });
      return true;
    }

    // DOWNLOAD: marker — parse byte values and emit formatted progress
    if (trimmed.startsWith('DOWNLOAD:')) {
      isDownloading = true;
      currentPhase = 'download';
      const rawText = trimmed.slice(9);
      const byteInfo = parseByteProgress(rawText);
      const message = formatDownloadMessage(rawText, byteInfo);
      const frame = { type: 'status', message, phase: currentPhase };
      if (byteInfo.downloaded != null) frame.downloadedBytes = byteInfo.downloaded;
      if (byteInfo.total != null) frame.totalBytes = byteInfo.total;
      broadcastSse(job, frame);
      return true;
    }

    const m = trimmed.match(/(\d+)%\|.*?(\d+)\/(\d+)/);
    if (m) {
      const pct = parseInt(m[1], 10) / 100;
      const step = parseInt(m[2], 10);
      const total = parseInt(m[3], 10);
      // Check for byte sizes in tqdm bars during downloads
      const byteInfo = parseByteProgress(trimmed);
      let displayMessage = trimmed;
      const frame = { type: 'progress', progress: pct, phase: currentPhase };
      if (isDownloading && (byteInfo.downloaded != null || byteInfo.total != null)) {
        displayMessage = formatDownloadMessage(trimmed, byteInfo);
        if (byteInfo.downloaded != null) frame.downloadedBytes = byteInfo.downloaded;
        if (byteInfo.total != null) frame.totalBytes = byteInfo.total;
      }
      frame.message = displayMessage;
      broadcastSse(job, frame);
      // Only forward to imageGenEvents (which drives the UI step counter)
      // when we're actually in the inference phase — download tqdm bars
      // count safetensors files, not diffusion steps.
      if (currentPhase === 'inference') {
        imageGenEvents.emit('progress', { generationId: jobId, progress: pct, step, totalSteps: total });
        if (activeJob && activeJob.generationId === jobId) {
          activeJob.progress = pct; activeJob.step = step; activeJob.totalSteps = total;
        }
      }
      return true;
    }
    broadcastSse(job, { type: 'status', message: trimmed });
    return false;
  };

  const shortId = jobId.slice(0, 8);
  // Route marker parsing through per-stream line readers so a STAGE:/STATUS:/
  // DOWNLOAD: marker (or a multibyte char) split across a pipe chunk boundary
  // can't tear a progress event. Each reader carries the partial trailing line
  // across chunks and is flushed on 'close'.
  const stderrReader = createLineReader((line) => {
    const trimmed = line.trim();
    if (!handleLine(line) && trimmed) console.log(`🐍 [${shortId}] ${trimmed}`);
  }, { splitRe: /[\n\r]+/ });
  const stdoutReader = createLineReader((line) => {
    const trimmed = line.trim();
    if (!handleLine(line) && trimmed) console.log(`🐍-out [${shortId}] ${trimmed}`);
  }, { splitRe: /[\n\r]+/ });
  proc.stderr.on('data', (chunk) => {
    // The bounded error-tail stays on the raw chunk text — the failure path
    // slices its last N bytes for context independently of line parsing.
    const text = chunk.toString();
    stderrBuffer += text;
    if (stderrBuffer.length > STDERR_TAIL_BYTES) {
      stderrBuffer = stderrBuffer.slice(-STDERR_TAIL_BYTES);
    }
    stderrReader.push(chunk);
  });
  proc.stdout.on('data', (chunk) => {
    stdoutReader.push(chunk);
  });

  proc.on('close', async (code, signal) => {
    await withBackupAssetPublication(async () => {
      // Guard against the spawn-ENOENT path where 'error' already finalized
      // the job. Node fires 'error' THEN 'close' (with code -2/null signal)
      // for a missing binary, and re-running the failure path here would
      // emit a second 'failed' event + second SSE error frame.
      if (finalized) return;
      finalized = true;
      // Emit any final unterminated marker line each stream wrote without a
      // trailing newline (a SIGKILL mid-write, or a progress bar whose last
      // redraw never terminated) BEFORE nulling activeJob — handleLine's
      // inference-progress branch mutates activeJob, so flushing first keeps a
      // final progress line able to update it (mirrors videoGen's ordering).
      stderrReader.flush();
      stdoutReader.flush();
      activeProcess = null;
      activeJob = null;
      void releaseHeavyClaim();
      if (watcher) { try { watcher.close(); } catch { /* ignore */ } }
      void removeStepwise();
      // EventEmitter doesn't await async listeners — without this try/catch, a
      // throw from any of the post-exit work below (rejectDegenerateFrame,
      // sharp, atomicWrite, autoCleanGeneratedImage) would surface as an
      // unhandled rejection (process-killing on Node >= 15), leave the job
      // stuck in 'running' forever, and hang any connected SSE client with no
      // terminal frame. Mirrors codex.js / grok.js's finalizeJobFailure.
      // `terminalEmitted` is set right before each branch's `broadcastSse` call
      // — i.e. once we've committed to a terminal outcome and are about to tell
      // consumers about it, not after. That ordering matters: it's set BEFORE
      // the SSE frame goes out, not after imageGenEvents.emit(), so a listener
      // that itself throws while handling one of these events can't cause the
      // catch below to retry the very emit that just threw. It's also checked
      // in the catch so a throw AFTER a terminal event was already dispatched
      // (e.g. autoCleanGeneratedImage failing once job.status is already
      // 'complete') logs the secondary failure without re-emitting a
      // contradictory terminal frame or downgrading a delivered 'complete'.
      let terminalEmitted = false;
      try {
        // Degenerate-frame gate (#4173): a runner can exit 0 having written a PNG
        // that decodes fine and holds no content (a solid-black frame from a run
        // that produced nothing). Fail the job instead of saving a black tile —
        // the file is removed so no gallery scan can pick it up. An unmeasurable
        // frame yields no reason and falls through to the normal success path.
        const emptyFrame = code === 0 ? await rejectDegenerateFrame(outputPath) : null;
        if (emptyFrame) {
          job.status = 'error';
          job.error = emptyFrame;
          console.error(`❌ Image generation failed [${jobId.slice(0, 8)}]: ${emptyFrame}`);
          terminalEmitted = true;
          dispatchTerminalEvent(
            jobId,
            () => broadcastSse(job, { type: 'error', error: emptyFrame }),
            () => imageGenEvents.emit('failed', { mode: IMAGE_GEN_MODE.LOCAL, generationId: jobId, error: emptyFrame }),
          );
          return;
        }
        if (code !== 0 || processError) {
          job.status = 'error';
          const reason = processError?.message || (signal ? `Killed by signal ${signal}` : `Exit code ${code}`);
          // Extract a structured user-error if the runner emitted one
          // (USER_ERROR:gated_repo:black-forest-labs/FLUX.2-klein-9B), and find
          // the matching `❌ …` prose line that follows it. Fall back to the last
          // 10 stderr lines if no structured error was emitted (unknown crash).
          const lines = stderrBuffer.split('\n').map((l) => l.trim()).filter(Boolean);
          const structIdx = lines.findIndex((l) => l.startsWith('USER_ERROR:'));
          let userMessage = null;
          let userKind = null;
          let userRepo = null;
          if (structIdx >= 0) {
            // Split with limit=2 so a kind containing colons can't shred the repo.
            const [kind, ...rest] = lines[structIdx].slice('USER_ERROR:'.length).split(':');
            userKind = kind;
            userRepo = rest.join(':') || null;
            const proseIdx = lines.findIndex((l, i) => i > structIdx && l.startsWith('❌'));
            userMessage = proseIdx >= 0 ? lines[proseIdx].replace(/^❌\s*/, '') : null;
          }
          // Heuristic detection for non-USER_ERROR failures we can still
          // surface actionably. mflux's entry-point shim breaks when a partial
          // package upgrade leaves user-site at the right version number but
          // with stale file layout — Python imports the wrong `mflux/` first.
          // Easier to spot at the source than to teach the user to read pip diffs.
          if (!userMessage) {
            const mfluxBroken = lines.some((l) => /ModuleNotFoundError: No module named 'mflux\.models\.flux\.cli'/.test(l));
            if (mfluxBroken) {
              userKind = 'mflux_install_corrupted';
              userMessage = 'Your mflux install is corrupted (entry-point shim and package layout out of sync). Repair with: `pip uninstall -y mflux && pip install --user --force-reinstall --no-cache-dir --no-deps mflux`. If you use conda, run the same in your conda env\'s pip.';
            }
          }
          // The precheck passed (or its memoized "healthy" answer is now stale) and
          // the runtime still failed to import. Bust the health cache so the next
          // status poll reports the truth instead of the cached pass, and name the
          // same one-button remedy rather than leaving the caller with "Exit code 1".
          if (userKind === 'torch_runtime_broken') invalidateFlux2Health();
          if (!userMessage && usesTorchVenv(model)) {
            const importBroken = lines.some((l) => /^(ModuleNotFoundError|ImportError)\b/.test(l) || /cannot import name /.test(l));
            if (importBroken) {
              invalidateFlux2Health();
              userKind = 'torch_runtime_broken';
              userMessage = `The shared torch image runtime at ${FLUX2_VENV_DEFAULT} could not import its packages. Reinstall it from Settings › Image Gen › Local, then retry this render.`;
            }
          }
          // Legacy mflux-generate is a pre-built binary, so it doesn't emit the
          // structured USER_ERROR markers the flux2/z-image Python runners use.
          // Match the raw huggingface_hub stack instead — `GatedRepoError` or the
          // "Cannot access gated repo for url …/<owner>/<name>/…" prose. Extract
          // the repo so the UI banner can link the user straight to the license
          // page (and we set kind=gated_repo so the client knows to surface the
          // token-entry form).
          if (!userMessage) {
            const gatedText = lines.join('\n');
            // Classify as gated ONLY on a gated-specific signal — extractGatedRepo
            // matches any huggingface.co/<owner>/<repo> URL, so a non-gated failure
            // (404, network error) that merely prints a HF URL must NOT be turned
            // into a misleading license-request flow. Extract the repo for the link
            // only after the gated signal is confirmed.
            const hasGatedError = isGatedRepoError(gatedText);
            if (hasGatedError) {
              userKind = 'gated_repo';
              userRepo = extractGatedRepo(gatedText);
              const repoText = userRepo || 'the model';
              userMessage = `Access to ${repoText} is gated. Accept the license at https://huggingface.co/${userRepo || '<repo>'} and paste your HuggingFace token into Image Gen settings, then retry.`;
            }
          }
          const tail = lines.slice(-10).join('\n');
          const errorText = userMessage
            ? `${userMessage}\n\n(diagnostic) ${reason}`
            : `Generation failed: ${reason}\n${tail}`;
          console.error(`❌ Image generation failed [${jobId.slice(0, 8)}]: ${userMessage || reason}`);
          job.error = userMessage || errorText;
          job.errorKind = userKind;
          job.errorRepo = userRepo;
          terminalEmitted = true;
          // Propagate the friendly message (not the raw "Exit code 1") to the
          // job queue so its `failed` log line and future SSE replays carry it.
          dispatchTerminalEvent(
            jobId,
            () => broadcastSse(job, { type: 'error', error: errorText, kind: userKind, repo: userRepo }),
            () => imageGenEvents.emit('failed', { mode: IMAGE_GEN_MODE.LOCAL, generationId: jobId, error: job.error }),
          );
        } else {
          job.status = 'complete';
          // Large-source regen (issue #912): the render ran at a clamped FLUX-sane
          // resolution. Upscale the result back to the requested delivery size so
          // the watermark-free copy matches the original's resolution. `meta.width/
          // height` currently hold the render dims; record those as render* and
          // promote the delivered dims so the gallery shows the real file size.
          const targetW = Math.round(Number(upscaleTo?.width));
          const targetH = Math.round(Number(upscaleTo?.height));
          if (targetW > 0 && targetH > 0 && (targetW !== meta.width || targetH !== meta.height)) {
            const resized = await sharp(outputPath)
              .resize(targetW, targetH, { fit: 'fill', kernel: 'lanczos3' })
              // compressionLevel 6 (sharp default) — near-identical size to 9 but
              // markedly faster, and this re-encode is on the render-completion path.
              .png({ compressionLevel: 6 })
              .toBuffer()
              .catch((err) => { console.warn(`⚠️ Regen upscale failed for ${filename}: ${err?.message || err}`); return null; });
            if (resized) {
              await atomicWrite(outputPath, resized);
              meta.renderWidth = meta.width;
              meta.renderHeight = meta.height;
              meta.width = targetW;
              meta.height = targetH;
              console.log(`🔍 Upscaled regen [${jobId.slice(0, 8)}] ${meta.renderWidth}x${meta.renderHeight} → ${targetW}x${targetH}`);
            }
          }
          // Regen fidelity (issue #912): for a regen pass, measure how much the
          // delivered image actually changed vs. the source so the sidecar records
          // the *realized* delta, not just the requested strength. Catches the
          // mflux strength-0.0 footgun, silent txt2img fallbacks, and over-mutation.
          // Best-effort — a decode failure just skips the stamp.
          if (regenOf && validInitImagePath) {
            const delta = await import('./regen.js')
              .then(({ computePixelDelta }) => computePixelDelta(validInitImagePath, outputPath))
              .catch(() => null);
            if (delta) {
              meta.regenPixelDeltaPct = delta.pixelDeltaPct;
              meta.regenPsnr = delta.psnr;
              console.log(`📐 Regen fidelity [${jobId.slice(0, 8)}]: ${delta.pixelDeltaPct}% changed, PSNR ${delta.psnr}dB`);
            }
          }
          // Sidecar: persist a metadata record next to the PNG so the gallery
          // and Remix flow can recover prompt/seed/steps even if mflux's own
          // --metadata sidecar lives at a slightly different filename shape.
          // A non-gallery target (issue #2264, the Image Cleaner's temp render)
          // skips this write entirely — the temp bytes are consumed by an explicit
          // result-fetch, so there's no gallery record to hydrate.
          const sidecar = join(outputDir, `${jobId}.metadata.json`);
          if (!skipSidecar) {
            // Render timing is stamped onto `meta` (not spread at the write) so the
            // sidecar and the `autoCleanGeneratedImage` rewrite below agree on it.
            Object.assign(meta, renderTimingFields(job.renderStartedAtMs));
            await atomicWrite(sidecar, meta);
            // Cleaners run BEFORE the SSE complete + completed events so subscribers
            // see the cleaned bytes. Local FLUX renders never carry C2PA chunks so
            // cleanC2PA is a no-op on local — denoise is the only mode that does
            // anything here. A throw here (or from the rest of this branch) is
            // caught below, before any terminal event has gone out for this job.
            await autoCleanGeneratedImage({ cleanC2PA, denoise, pngPath: outputPath, sidecarPath: sidecar, mode: IMAGE_GEN_MODE.LOCAL });
          }
          console.log(`✅ Image generated [${jobId.slice(0, 8)}]: ${filename}${skipSidecar ? ' (temp, no sidecar)' : ''}`);
          // A non-gallery render has no `/data/images` mount — carry the absolute
          // `outputPath` so the queue/route can read the finished bytes; `path`
          // stays null so nothing treats it as a gallery URL.
          const result = { filename, seed: actualSeed, path: publicPath, outputPath, ...(meta.executionProvenance ? { executionProvenance: meta.executionProvenance } : {}) };
          terminalEmitted = true;
          // Include `seed` so /sdapi/v1/txt2img can surface the actual seed used
          // (mflux generates a random one if the client didn't pass one). Emit the
          // gallery `completed` (which drives the media-asset index + peer-sync
          // hooks) ONLY for a gallery target — a temp render must not be indexed or
          // federated. The queue's own `completed` handler still fires off the
          // return value below, so the job settles either way.
          dispatchTerminalEvent(
            jobId,
            () => broadcastSse(job, { type: 'complete', result }),
            () => {
              if (!skipSidecar) {
                imageGenEvents.emit('completed', { mode: IMAGE_GEN_MODE.LOCAL, generationId: jobId, path: publicPath, filename, seed: actualSeed, ...(meta.executionProvenance ? { executionProvenance: meta.executionProvenance } : {}) });
              } else {
                // `temp: true` tells the media-asset-index + peer-sync hooks to
                // ignore this render — there's no gallery file or sidecar to
                // index/federate.
                imageGenEvents.emit('completed', { mode: IMAGE_GEN_MODE.LOCAL, generationId: jobId, path: null, filename, seed: actualSeed, outputPath, temp: true, ...(meta.executionProvenance ? { executionProvenance: meta.executionProvenance } : {}) });
              }
            },
          );
        }
      } catch (err) {
        const reason = err?.message || String(err);
        console.error(`❌ Image generation post-exit handler failed [${jobId.slice(0, 8)}]: ${reason}`);
        // `terminalEmitted` is already true here only when the throw came from
        // dispatching a terminal event itself (a downstream broadcastSse/
        // imageGenEvents listener throwing) — that event already reached
        // consumers, so don't downgrade a delivered outcome (e.g. a 'complete'
        // frame the client already saw) to 'error', and don't retry the same
        // emit that just threw.
        if (!terminalEmitted) {
          await Promise.all([outputPath, join(outputDir, `${jobId}.metadata.json`)].map(path => unlinkGuarded(path).catch(() => {})));
          job.status = 'error';
          job.error = reason;
          // `dispatchTerminalEvent` guards each call independently — a throwing
          // SSE writer (a dead client's `res.write`) can't suppress the
          // `imageGenEvents.emit` (or vice versa), and neither can re-throw out
          // of this catch, which would escape the close handler as an
          // unhandled rejection. job.status/job.error above are already correct
          // even if delivery fails partway, and `finally` below still runs the
          // job cleanup.
          dispatchTerminalEvent(
            jobId,
            () => broadcastSse(job, { type: 'error', error: reason }),
            () => imageGenEvents.emit('failed', { mode: IMAGE_GEN_MODE.LOCAL, generationId: jobId, error: reason }),
          );
        }
      } finally {
        closeJobAfterDelay(jobs, jobId);
      }
    }).catch(async err => {
      // Admission failure happens before the inner finalizer can clear the
      // process slot or release its heavy-job claim. Settle without publishing
      // or deleting gallery bytes outside the refused boundary.
      if (finalized) return;
      finalized = true;
      activeProcess = null;
      activeJob = null;
      if (watcher) { try { watcher.close(); } catch { /* ignore */ } }
      await Promise.all([releaseHeavyClaim(), removeStepwise()]);
      const reason = err?.message || String(err);
      job.status = 'error';
      job.error = reason;
      dispatchTerminalEvent(
        jobId,
        () => broadcastSse(job, { type: 'error', error: reason }),
        () => imageGenEvents.emit('failed', { mode: IMAGE_GEN_MODE.LOCAL, generationId: jobId, error: reason }),
      );
      closeJobAfterDelay(jobs, jobId);
    });
  });

  // Every real listener is on and nothing has awaited since: hand over whatever
  // the child emitted during the claim handoff so a fast-dying render still
  // reaches its terminal handlers and releases the claim.
  const earlyExit = takeEarlyExit();
  if (earlyExit) {
    console.warn(`⚠️ Image render child exited before it was wired [${shortId}]`);
    for (const { stream, chunk } of earlyExit.output || []) proc[stream].emit('data', chunk);
    if (earlyExit.type === 'error') proc.emit('error', earlyExit.error);
    else if (earlyExit.type === 'close') proc.emit('close', earlyExit.code, earlyExit.signal);
  }

  return { jobId, filename, path: `/data/images/${filename}`, generationId: jobId, mode: IMAGE_GEN_MODE.LOCAL, model: modelId, seed: actualSeed };
}

// Validate a gallery filename: PNG-only, basename only, no path separators.
// Delegates to the shared `assertSafeFilename` helper in fileUtils.js.
// Substring `..` is allowed (e.g. `my..render.png` is fine) because the
// helper only rejects the exact-string traversal cases.
// `requiredMessage` preserves the original "Invalid filename" wording for
// the missing-input case so existing client error-message expectations
// (and the previously-shipped error-middleware contract) don't shift.
export function assertGalleryFilename(filename) {
  assertSafeFilename(filename, {
    extensions: ['.png'],
    subject: 'filename',
    requiredMessage: 'Invalid filename',
  });
}

// Returns `{ path, metadata }`. `path` is the resolved sidecar location, or
// the preferred Portos location on miss — callers writing back land at the
// canonical path automatically.
export async function readImageSidecar(filename) {
  const portosSidecar = join(PATHS.images, filename.replace('.png', '.metadata.json'));
  const altSidecar = join(PATHS.images, `${filename}.metadata.json`);
  for (const path of [portosSidecar, altSidecar]) {
    const raw = await tryReadFile(path);
    if (raw != null) return { path, metadata: safeJSONParse(raw, {}) };
  }
  return { path: portosSidecar, metadata: {} };
}

// Decoder safety is independent of the upload file-size policy.
const MAX_GALLERY_UPLOAD_PIXELS = 96 * 1000 * 1000;

async function refreshImageIndex(filename) {
  await import('../mediaAssetIndex/index.js')
    .then(m => m.indexImage({ filename }))
    .catch(err => console.error(`❌ Media index image refresh failed: ${err.message}`));
}

/**
 * Persist user-uploaded image bytes (base64) into the gallery dir under
 * `data/images/` so the file rides the existing `image` peer-sync asset path
 * (a record pointing at `/data/images/<f>` ships its bytes to peers; a
 * `/api/uploads/<f>` path does not). The payload is sniffed by magic bytes —
 * the client-supplied name/extension is not trusted — and a non-image is
 * rejected with a 400, then re-encoded to **PNG** so the saved file is a
 * first-class gallery citizen: it lists in `/image-gen/gallery` and deletes via
 * `deleteImage`, both of which only manage `.png`. Returns the bare gallery
 * filename and its `/data/images/` mount path for the caller to store.
 *
 * @param {string|null} base64Data - Legacy raw base64 image bytes
 * @param {string} [tempPath] - Server-staged multipart file, preferred over base64
 * @returns {Promise<{ filename: string, path: string, metadata: object }>}
 */
export async function saveUploadedGalleryImage(base64Data, tempPath) {
  const input = tempPath || Buffer.from(base64Data, 'base64');
  let header = input;
  if (tempPath) {
    const file = await open(tempPath, 'r');
    header = Buffer.alloc(12);
    await file.read(header, 0, header.length, 0).finally(() => file.close());
  }
  if (!tempPath && input.length === 0) {
    throw new ServerError('Empty image upload', { status: 400, code: 'VALIDATION_ERROR' });
  }
  const detected = detectImageFormat(header);
  if (!detected) {
    throw new ServerError('Unsupported image format (expected PNG, JPEG, WebP, or GIF)', { status: 400, code: 'UNSUPPORTED_IMAGE' });
  }
  // Read Stable Diffusion-compatible PNG text chunks before sharp normalizes
  // the image. JPEG/WebP/GIF uploads simply produce an empty projection.
  const metadata = tempPath
    ? await extractPngGenerationMetadataFile(tempPath)
    : extractPngGenerationMetadata(input);
  // Normalize to PNG so the gallery's PNG-only list/delete paths manage it.
  // `.rotate()` with no args bakes in EXIF orientation before the metadata is
  // dropped, so a camera-JPEG portrait isn't saved sideways/upside-down.
  const filename = `upload-${randomUUID().slice(0, 8)}.png`;
  await ensureDir(PATHS.images);
  const output = join(PATHS.images, filename);
  const staging = `${output}.tmp`;
  try {
    await sharp(input, { limitInputPixels: MAX_GALLERY_UPLOAD_PIXELS }).rotate().png().toFile(staging);
    // Encoding stays outside admission. Publish the final file, metadata, and
    // derived database row together so a backup cannot split those writes.
    return await withBackupAssetPublication(async () => {
      await rename(staging, output);
      // PNG normalization strips source text chunks; keep their bounded
      // projection in the gallery sidecar for listings and later attachments.
      if (Object.keys(metadata).length > 0) {
        await atomicWrite(join(PATHS.images, filename.replace('.png', '.metadata.json')), metadata);
      }
      await refreshImageIndex(filename);
      console.log(`📥 Saved uploaded gallery image: ${filename} (PNG from ${detected.mime})`);
      return { filename, path: `/data/images/${filename}`, metadata };
    });
  } finally {
    await unlinkGuarded(staging).catch(() => {});
  }
}

export async function listGallery() {
  if (!existsSync(PATHS.images)) return [];
  // requireRegularFile:false preserves the original gallery behavior — it
  // never checked isFile(), only dropped on stat failure. listLoras /
  // listMusicLibrary do filter directories; mirroring that here would be a
  // behavior change.
  const items = await listDirectoryByExtension(PATHS.images, {
    extensions: ['.png'],
    requireRegularFile: false,
    mapEntry: async (f, _fullPath, s) => {
      const { metadata } = await readImageSidecar(f);
      return {
        filename: f,
        path: `/data/images/${f}`,
        createdAt: metadata.createdAt || s.birthtime.toISOString(),
        ...metadata,
        fileSizeBytes: s.size,
      };
    },
  });
  return items.sort((a, b) => new Date(b.createdAt) - new Date(a.createdAt));
}

export async function deleteImage(filename) {
  assertGalleryFilename(filename);
  return withBackupAssetPublication(() => sidecarEditQueue(filename, async () => {
    await trashFiles([
      join(PATHS.images, filename),
      join(PATHS.images, filename.replace(/\.png$/i, '.metadata.json')),
      join(PATHS.images, `${filename}.metadata.json`),
      join(PATHS.imageThumbnails, filename.replace(/\.png$/i, '.webp')),
    ]);
    // trashFiles verifies removal before derived records can be retired.
    await import('../mediaAssetIndex/index.js')
      .then((m) => m.unindexImage(filename))
      .catch((err) => console.error(`❌ Media index image delete hook: ${err.message}`));
    console.log(`🗑️ Trashed image: ${filename}`);
    return { ok: true };
  }));
}

// Sidecar edits are whole-file read→modify→replace cycles; atomicWrite stops a
// torn file but not two edits (prompt + visibility) reading the same copy and
// the later write dropping the earlier field. One tail per gallery filename
// covers both sidecar spellings, and the index refresh stays inside the turn.
const sidecarEditQueue = createKeyCachedQueue();

// `mutate` edits the metadata in place; returning null leaves the file as it was.
function editImageSidecar(filename, mutate) {
  // Admit before joining the queue so a cut drains every already-requested
  // edit, including one waiting for an earlier edit's index refresh.
  return withBackupAssetPublication(() => sidecarEditQueue(filename, async () => {
    const { path: sidecarPath, metadata } = await readImageSidecar(filename);
    const result = mutate(metadata);
    if (result === null) return null;
    // A stale edit queued after deletion must not recreate its sidecar/index.
    // Sidecar-only records remain editable while peer media bytes are pending.
    const present = await Promise.all([
      join(PATHS.images, filename),
      join(PATHS.images, filename.replace(/\.png$/i, '.metadata.json')),
      join(PATHS.images, `${filename}.metadata.json`),
    ].map(path => stat(path).then(() => true, error => {
      if (error.code === 'ENOENT') return false;
      throw error;
    })));
    if (!present.some(Boolean)) throw new ServerError('Image not found', { status: 404, code: 'NOT_FOUND' });
    await atomicWrite(sidecarPath, metadata);
    await refreshImageIndex(filename);
    return result;
  }));
}

export async function setImageHidden(filename, hidden) {
  assertGalleryFilename(filename);
  return editImageSidecar(filename, (metadata) => {
    metadata.hidden = !!hidden;
    return { ok: true, hidden: metadata.hidden };
  });
}

export async function updateImagePrompt(filename, prompt) {
  assertGalleryFilename(filename);
  const trimmedPrompt = typeof prompt === 'string' ? prompt.trim() : '';
  return editImageSidecar(filename, (metadata) => {
    if (trimmedPrompt) metadata.prompt = trimmedPrompt;
    else delete metadata.prompt;
    return { filename, prompt: trimmedPrompt };
  });
}

// Fill only keys the sidecar lacks, through the same edit queue as prompt and
// visibility edits so neither write drops the other. An image without a sidecar
// is left alone: a stub holding only these fields would carry no prompt, seed
// or model. Resolves true when the sidecar changed, null otherwise.
export function fillImageSidecarFields(filename, fields) {
  return editImageSidecar(filename, (metadata) => {
    if (!metadata || Object.keys(metadata).length === 0) return null;
    const missing = Object.entries(fields).filter(([key, value]) => value != null && metadata[key] == null);
    if (missing.length === 0) return null;
    Object.assign(metadata, Object.fromEntries(missing));
    return true;
  });
}

// Returns just `{ filename, name }` — clients send `filename` back in the
// generate payload's `loraFilenames` and the server resolves it against
// PATHS.loras. Avoids leaking absolute server paths into the API surface.
//
// Distinct from `services/loras.js#listLoras` which returns the rich
// Civitai-aware shape (civitai, runnerFamily, triggerWords, etc.) for the
// `/api/loras` manager UI. The two used to share the name `listLoras`;
// rename here makes the shape distinction explicit so a future caller
// can't import the wrong one and silently lose `civitai`/`runnerFamily`.
export async function listLoraFilenames() {
  await ensureDir(PATHS.loras);
  const files = await readdir(PATHS.loras).catch(() => []);
  return files.filter((f) => f.endsWith('.safetensors')).map((f) => ({
    filename: f,
    name: f.replace(/^lora-/, '').replace(/\.safetensors$/, ''),
  }));
}