fix: restore-photo colorize hang and AVIF decode failures

- Fix dispatcher pipe deadlock: drain stdout pipe in a background thread
  to prevent blocking when ONNX runtime output exceeds 64KB pipe buffer
- Add 5-minute SSE stall timeout so the UI shows an error instead of
  hanging forever when async AI processing stalls
- Guard CPU colorization: skip for images >2MP on CPU and when DDColor
  model is not installed, with clear user-facing messages
- Add AVIF decode fallback via ImageMagick for bitstream variants that
  Sharp's bundled libheif cannot decode (affects all tools)

apps/api/src/lib/format-decoders.ts

@@ -90,6 +90,31 @@ export async function decodeToSharpCompat(
   }
 }
 
+/**
+ * Last-resort decode: convert any image to PNG via ImageMagick.
+ * Used when Sharp's bundled decoders fail (e.g. AVIF 2.0 bitstreams).
+ */
+export async function decodeAnyFormat(buffer: Buffer, format: string): Promise<Buffer> {
+  const cmd = await findMagickCmd();
+  const id = randomUUID();
+  const ext = format || "img";
+  const inputPath = join(tmpdir(), `any-in-${id}.${ext}`);
+  const outputPath = join(tmpdir(), `any-out-${id}.png`);
+
+  try {
+    await writeFile(inputPath, buffer);
+    await execFileAsync(
+      cmd,
+      magickArgs(cmd, [inputPath, "-colorspace", "sRGB", `png:${outputPath}`]),
+      { timeout: 120_000 },
+    );
+    return await readFile(outputPath);
+  } finally {
+    await rm(inputPath, { force: true }).catch(() => {});
+    await rm(outputPath, { force: true }).catch(() => {});
+  }
+}
+
 // ── ImageMagick helpers ────────────────────────────────────────
 
 let cachedMagickCmd: string | null = null;

apps/api/src/routes/tool-factory.ts

@@ -13,7 +13,7 @@ import { formatZodErrors } from "../lib/errors.js";
 import { isToolInstalled } from "../lib/feature-status.js";
 import { validateImageBuffer } from "../lib/file-validation.js";
 import { sanitizeFilename } from "../lib/filename.js";
-import { decodeToSharpCompat, needsCliDecode } from "../lib/format-decoders.js";
+import { decodeAnyFormat, decodeToSharpCompat, needsCliDecode } from "../lib/format-decoders.js";
 import { decodeHeic } from "../lib/heic-converter.js";
 import type { WorkerInput, WorkerOutput } from "../lib/image-worker.js";
 import { decompressSvgz, sanitizeSvg } from "../lib/svg-sanitize.js";
@@ -244,6 +244,27 @@ export function createToolRoute<T>(app: FastifyInstance, config: ToolRouteConfig
         }
       }
 
+      // AVIF can pass metadata validation but fail pixel decode when
+      // Sharp's bundled libheif lacks support for the bitstream version.
+      // A 1x1 resize forces a minimal pixel decode to catch this early.
+      if (validation.format === "avif") {
+        try {
+          await sharp(fileBuffer).resize(1).raw().toBuffer();
+        } catch {
+          try {
+            reportProgress(10, "Decoding...");
+            fileBuffer = await decodeAnyFormat(fileBuffer, "avif");
+            const ext = filename.match(/\.[^.]+$/)?.[0];
+            if (ext) filename = `${filename.slice(0, -ext.length)}.png`;
+          } catch (fallbackErr) {
+            return reply.status(422).send({
+              error: "Failed to decode AVIF file",
+              details: fallbackErr instanceof Error ? fallbackErr.message : String(fallbackErr),
+            });
+          }
+        }
+      }
+
       reportProgress(15, "Preparing...");
 
       // Parse and validate settings

apps/api/src/routes/tools/restore-photo.ts

@@ -11,7 +11,7 @@ import { formatZodErrors } from "../../lib/errors.js";
 import { isToolInstalled } from "../../lib/feature-status.js";
 import { validateImageBuffer } from "../../lib/file-validation.js";
 import { sanitizeFilename } from "../../lib/filename.js";
-import { decodeToSharpCompat, needsCliDecode } from "../../lib/format-decoders.js";
+import { decodeAnyFormat, decodeToSharpCompat, needsCliDecode } from "../../lib/format-decoders.js";
 import { decodeHeic } from "../../lib/heic-converter.js";
 import { resolveOutputFormat } from "../../lib/output-format.js";
 import { createWorkspace } from "../../lib/workspace.js";
@@ -113,6 +113,21 @@ export function registerRestorePhoto(app: FastifyInstance) {
 
       // Auto-orient to fix EXIF rotation
       fileBuffer = await autoOrient(fileBuffer);
+
+      // AVIF can pass metadata validation but fail pixel decode when
+      // Sharp's bundled libheif lacks support for the bitstream version.
+      // Convert early (the sidecar needs PNG anyway); fall back to ImageMagick.
+      if (validation.format === "avif") {
+        try {
+          fileBuffer = await sharp(fileBuffer).png().toBuffer();
+        } catch {
+          request.log.warn(
+            { toolId: "restore-photo" },
+            "Sharp AVIF decode failed, using ImageMagick",
+          );
+          fileBuffer = await decodeAnyFormat(fileBuffer, "avif");
+        }
+      }
     } catch (err) {
       request.log.error({ err, toolId: "restore-photo" }, "Input decoding failed");
       return reply.status(422).send({