qlogicagent 2.13.3 → 2.13.5

package/dist/runtime/pet/petdex-forge-service.js

@@ -0,0 +1,820 @@
+/**
+ * Petdex forge — drives the vendored OpenAI Codex Hatch-Pet Python pipeline
+ * (Apache-2.0, under vendor/hatch-pet) to produce Codex-compatible animated pet
+ * sprite atlases.
+ *
+ * The forge owns NO image-processing heuristics. Chroma-key background removal,
+ * stable-slots frame extraction, atlas composition and validation are all done
+ * by the deterministic vendored Python scripts — the same pipeline OpenAI ships
+ * for Codex `/hatch`. This module only:
+ *   1. spawns prepare_pet_run.py to lay out a run directory (prompts, layout
+ *      guides, chroma-key selection, imagegen-jobs.json),
+ *   2. fulfils each generation job by calling the provider-core media generator,
+ *   3. spawns extract / inspect / compose / validate / contact-sheet / preview,
+ *   4. reads the composed atlas back and packages it through pet-core.
+ *
+ * Prompts come exclusively from the Python prompt files (single source of
+ * truth, chroma-hex + per-state frame counts baked in) — there is no TS prompt
+ * builder path.
+ */
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { createCanvas, loadImage } from "@napi-rs/canvas";
+import { createPetdexAssetFromSpritesheet, writePetdexAssetPackage, PETDEX_ATLAS_CONTRACT } from "./petdex-asset.js";
+import { isHatchPetAvailable, runHatchPetScript } from "./hatch-pet-runner.js";
+import { PETDEX_REFERENCE_IMAGE_SIZE, buildPetdexProductionRun, petdexSourceMode, accumulatePetdexUsage, } from "@xiaozhiclaw/pet-core";
+export { PETDEX_PRODUCTION_SCHEMA, } from "@xiaozhiclaw/pet-core";
+const CANONICAL_BASE_REL = "references/canonical-base.png";
+const BASE_STYLE = "single centered full-body desktop pet character on a flat chroma-key background, readable at pet size";
+const ROW_STYLE = "one horizontal animation row strip with evenly spaced full-body frames sharing a single consistent character identity";
+// Row strips are generated at a wide, provider-accepted resolution rather than
+// the (tiny) layout-guide dimensions: image providers like Volcengine Seedream
+// enforce a minimum pixel count (~1920x1920 = 3.69M px) that a 1536x208 guide
+// strip violates. extract_strip_frames slots by frame count, independent of the
+// generated resolution, so a 4096x1024 (4:1) strip extracts cleanly.
+const ROW_STRIP_SIZE = "4096x1024";
+// Image models do not honour the requested chroma-key hex exactly (e.g. Volcengine
+// Seedream renders a deep purple-magenta ~#9413A3 instead of pure #FF00FF), so
+// keying on the configured fallback leaves the real background behind. We detect
+// the actual flat background from the generated base and key extraction on that.
+const FALLBACK_CHROMA_HEX = "#FF00FF";
+const CHROMA_KEY_THRESHOLD = "110";
+// Component-based extraction with a shared viewport: finds the actual pose blobs
+// (merging detached bits — sweat drops, antenna balls — into the nearest pose by
+// x-position) so a drifting pose is never sliced across two cells, and crops every
+// pose to ONE shared viewport so the character keeps a stable scale across the row
+// (no size popping). This needs clean flat strips with no separator lines, which
+// the layout-guide-suppression + anti-frame guard now produce; pure equal-slot
+// "slots" was a stopgap for the separator era and could halve a misplaced pose.
+const EXTRACT_METHOD = "stable-slots";
+// inspect_frames' chroma-adjacent check must stay BELOW the extraction threshold:
+// extraction already removes everything within CHROMA_KEY_THRESHOLD of the key,
+// so anything still opaque is intentionally-kept character. The default (150) is
+// above our 110 and would flag the character's own edges as "chroma residue",
+// triggering an endless false-positive repair storm.
+const INSPECT_CHROMA_ADJ_THRESHOLD = "90";
+// Some image models (e.g. Volcengine Seedream) interpret "N frames in a row" as
+// a gallery of framed pictures — drawing white borders / mats / panels around
+// each pose. Those bright frames survive chroma keying and show as bars in the
+// atlas. The vendored Codex prompts (tuned for GPT-image) don't forbid this, so
+// we append an explicit anti-frame guard the orchestrator owns.
+const GENERATION_LAYOUT_GUARD = [
+    "STRICT BACKGROUND: render one single continuous flat background of the same solid color filling the entire image edge to edge.",
+    "Do NOT draw any picture frame, framed panel, border, mat, outline, box, gallery frame, white or light margin, or divider around or between the poses.",
+    "The poses sit directly on the one seamless flat background, evenly spaced, with nothing separating them.",
+    "IDENTITY LOCK: every frame is the EXACT same character — identical species, body shape, proportions, colors, palette, face, and markings. Do not redesign, restyle, recolor, or resize the character between frames; only its pose changes.",
+    "Each pose is ONE connected solid silhouette at a consistent size. No detached parts, sweat drops, tears, dust, puffs, sparkles, speed lines, motion blur, floating effects, or drop shadows.",
+].join(" ");
+const MIRROR_DECISION_NOTE = "Leftward gait is the framewise horizontal mirror of the approved rightward row, preserving frame order and timing semantics.";
+// Vision-QA loop (Codex method): generate up to N candidates per job and keep the
+// first that a vision model accepts; if none pass, fall through with the last (the
+// deterministic validate_atlas gate still protects the contract). Default 2.
+const DEFAULT_CANDIDATES = 2;
+const MAX_QA_PROMPTS = 2; // initial prompt, then the row's retry prompt
+// ── Public API ─────────────────────────────────────────────
+export async function forgePetdexAsset(input, generateImage, options = {}) {
+    if (!(await isHatchPetAvailable())) {
+        throw new Error("Petdex forge requires the vendored Hatch-Pet pipeline (Python with Pillow). Install Python + Pillow or set QLOGICAGENT_PYTHON to a python that can `import PIL`.");
+    }
+    const usage = { billingQuantity: 0, durationMs: 0 };
+    const productionJobs = [];
+    const combinedPrompts = [];
+    const sourceMode = petdexSourceMode(input);
+    const runDir = await createRunDir();
+    const stagedRefs = await stageReferenceFiles(input);
+    try {
+        // 1. Lay out the run directory: prompts, layout guides, chroma-key, jobs.
+        await runScript("prepare_pet_run.py", [
+            "--pet-name", input.name,
+            "--display-name", input.name,
+            "--description", input.description,
+            "--pet-notes", input.prompt?.trim() || input.description,
+            "--pet-id", asciiSlug(input.id ?? input.name),
+            "--output-dir", runDir,
+            "--chroma-key", "auto",
+            ...stagedRefs.flatMap((file) => ["--reference", file]),
+        ]);
+        const manifestPath = path.join(runDir, "imagegen-jobs.json");
+        const manifest = await readJson(manifestPath);
+        // 2. Fulfil each job in manifest order. The array is dependency-ordered
+        //    (base first; idle/running-right next, then the rest), so a plain
+        //    in-order walk satisfies depends_on and gives the Codex identity+gait
+        //    check for free: base → idle → running-right are vision-QA'd first.
+        const inspectImage = options.inspectImage;
+        const candidates = Math.max(1, options.candidates ?? DEFAULT_CANDIDATES);
+        const generatedRows = [];
+        let chromaHex = FALLBACK_CHROMA_HEX;
+        let baseDataUrl;
+        for (const job of manifest.jobs) {
+            // running-left is mirror-derivable. Without vision QA we mirror it (cheap,
+            // current behaviour). With vision QA we instead generate it as a normal
+            // grounded row so each frame is independently checked — Codex only mirrors
+            // a confirmed-safe running-right, and a drifting mirror yields empty cells.
+            const isDerived = !!(job.derivation_policy?.may_derive && job.derivation_policy.may_derive_from);
+            if (isDerived && !inspectImage) {
+                await deriveRow(runDir);
+                productionJobs.push({
+                    id: `row-${job.id}`,
+                    kind: "row-strip",
+                    status: "complete",
+                    animationId: job.id,
+                    prompt: `derived: framewise-horizontal-mirror of ${job.derivation_policy.may_derive_from}`,
+                    inputImages: [],
+                    outputUrl: job.output_path,
+                });
+                continue;
+            }
+            const prompt = await fs.readFile(path.join(runDir, job.prompt_file), "utf-8");
+            const retryPrompt = job.retry_prompt_file
+                ? await fs.readFile(path.join(runDir, job.retry_prompt_file), "utf-8").catch(() => undefined)
+                : undefined;
+            combinedPrompts.push(prompt);
+            const isBase = job.kind === "base-pet";
+            const { mediaUrl, inputImages } = await selectJobImage({
+                runDir, job, prompt, retryPrompt, generateImage, inspectImage, candidates, usage, upload: options.uploadReferenceImage, baseDataUrl,
+            });
+            // The canonical base is the identity reference every row reuses; it also
+            // reveals the actual flat background colour the model rendered (which we
+            // key extraction on) and is the image vision QA compares every row against.
+            if (isBase) {
+                await fs.copyFile(path.join(runDir, job.output_path), path.join(runDir, CANONICAL_BASE_REL));
+                chromaHex = await detectChromaHex(path.join(runDir, job.output_path));
+                baseDataUrl = await fileToDataUrl(path.join(runDir, CANONICAL_BASE_REL));
+            }
+            // The vendored mirror step gates on running-right being marked complete
+            // in the manifest, so persist job status as each generation lands.
+            job.status = "complete";
+            await fs.writeFile(manifestPath, JSON.stringify(manifest, null, 2), "utf-8");
+            productionJobs.push({
+                id: isBase ? "base-reference" : `row-${job.id}`,
+                kind: isBase ? "reference" : "row-strip",
+                status: "complete",
+                ...(isBase ? {} : { animationId: job.id }),
+                prompt,
+                inputImages,
+                outputUrl: mediaUrl,
+            });
+            if (!isBase)
+                generatedRows.push(job);
+        }
+        // 3. Deterministic pipeline: extract → QA-repair → compose → validate (+ artifacts).
+        const decodedDir = path.join(runDir, "decoded");
+        const framesDir = path.join(runDir, "frames");
+        const atlasPng = path.join(runDir, "atlas.png");
+        const atlasWebp = path.join(runDir, "atlas.webp");
+        await runScript("extract_strip_frames.py", ["--decoded-dir", decodedDir, "--output-dir", framesDir, "--chroma-key", chromaHex, "--key-threshold", CHROMA_KEY_THRESHOLD, "--method", EXTRACT_METHOD]);
+        // Codex deterministic repair: regenerate only the rows inspect flags
+        // (empty/sparse frames, wrong cell size, chroma bleed) with the retry
+        // prompt, re-extract that row, and re-inspect — bounded retries per row.
+        await repairFlaggedRows({
+            runDir, decodedDir, framesDir, generatedRows, chromaHex, generateImage,
+            inspectImage, candidates, baseDataUrl, usage, upload: options.uploadReferenceImage, productionJobs,
+        });
+        const contactSheet = path.join(runDir, "qa", "contact-sheet.png");
+        await composeAndValidate(runDir, framesDir, atlasPng, atlasWebp, contactSheet);
+        // Hybrid frame-level repair: the strip pass gives temporal continuity; here
+        // each extracted frame is scored DETERMINISTICALLY (non-transparent pixel
+        // count + mean brightness vs the row median) to catch dark silhouettes,
+        // off-brightness, empty, or fragment frames cheaply (no per-frame vision
+        // call). Each flagged frame is regenerated as ONE pose (img2img on the base,
+        // vision-QA'd when a vision model is present) and spliced back into its cell,
+        // then the atlas is recomposed + re-validated. One bounded round.
+        if (baseDataUrl) {
+            await repairBadFrames({
+                runDir, framesDir, atlasPng, atlasWebp, contactSheet, generatedRows,
+                generateImage, inspectImage, candidates, usage, upload: options.uploadReferenceImage, baseDataUrl,
+            });
+        }
+        await runScriptSoft("render_animation_previews.py", ["--frames-root", framesDir, "--output-dir", path.join(runDir, "qa", "previews")]);
+        // 4. Package through pet-core (re-encodes webp, builds the Codex-aligned manifest).
+        const spritesheet = await fs.readFile(atlasWebp);
+        const asset = await createPetdexAssetFromSpritesheet({
+            id: input.id,
+            name: input.name,
+            description: input.description,
+            prompt: input.prompt,
+            spritesheet,
+            sourceKind: "forge",
+        });
+        return {
+            ...asset,
+            prompt: combinedPrompts.join("\n\n---\n\n"),
+            productionRun: buildPetdexProductionRun(sourceMode, productionJobs),
+            model: usage.model,
+            size: usage.size,
+            durationMs: usage.durationMs || undefined,
+            ...(usage.provider ? {
+                mediaUsage: {
+                    provider: usage.provider,
+                    model: usage.model ?? "unknown",
+                    billingUnit: usage.billingUnit ?? "per_call",
+                    billingQuantity: usage.billingQuantity || 1,
+                },
+            } : {}),
+        };
+    }
+    finally {
+        await cleanupDir(stagedRefs.length ? path.dirname(stagedRefs[0]) : undefined);
+        if (!keepRuns())
+            await cleanupDir(runDir);
+    }
+}
+export async function forgePetdexAssetPackage(params) {
+    const forged = await forgePetdexAsset(params.input, params.generateImage, {
+        uploadReferenceImage: params.uploadReferenceImage,
+    });
+    const assetDir = path.join(params.outputDir, forged.asset.id);
+    await fs.mkdir(assetDir, { recursive: true });
+    const manifestPath = path.join(assetDir, "pet.json");
+    const spritesheetPath = path.join(assetDir, "spritesheet.webp");
+    const validationPath = path.join(assetDir, "validation.json");
+    const productionRunPath = path.join(assetDir, "production-run.json");
+    await fs.writeFile(manifestPath, JSON.stringify(forged.asset, null, 2), "utf-8");
+    await fs.writeFile(spritesheetPath, forged.spritesheet);
+    await fs.writeFile(validationPath, JSON.stringify(forged.validation, null, 2), "utf-8");
+    await fs.writeFile(productionRunPath, JSON.stringify(forged.productionRun, null, 2), "utf-8");
+    const packagePath = await writePetdexAssetPackage({
+        asset: forged.asset,
+        spritesheet: forged.spritesheet,
+        validation: forged.validation,
+        productionRun: forged.productionRun,
+        outputDir: params.outputDir,
+        fileName: `${forged.asset.id}.petdex`,
+    });
+    return {
+        ...forged,
+        packagePath,
+        assetDir,
+        manifestPath,
+        spritesheetPath,
+        validationPath,
+        productionRunPath,
+    };
+}
+export async function readGeneratedPetdexImage(mediaUrl) {
+    if (mediaUrl.startsWith("data:")) {
+        const match = mediaUrl.match(/^data:[^;]+;base64,(.+)$/);
+        if (!match)
+            throw new Error("Generated Petdex image data URL is not base64 encoded");
+        return Buffer.from(match[1], "base64");
+    }
+    if (/^https?:\/\//i.test(mediaUrl)) {
+        const response = await fetch(mediaUrl);
+        if (!response.ok)
+            throw new Error(`Generated Petdex image download failed: ${response.status} ${response.statusText}`);
+        return Buffer.from(await response.arrayBuffer());
+    }
+    if (mediaUrl.startsWith("file://")) {
+        return fs.readFile(new URL(mediaUrl));
+    }
+    return fs.readFile(mediaUrl);
+}
+// ── Internal helpers ───────────────────────────────────────
+async function deriveRow(runDir) {
+    await runScript("derive_running_left_from_running_right.py", [
+        "--run-dir", runDir,
+        "--confirm-appropriate-mirror",
+        "--decision-note", MIRROR_DECISION_NOTE,
+        "--force",
+    ]);
+}
+/** Generate one candidate image (base or row). Does NOT write to disk. */
+async function generateCandidate(runDir, job, promptText, generateImage, usage, upload) {
+    const inputImages = await resolveJobImages(runDir, job, upload);
+    const isBase = job.kind === "base-pet";
+    // Do NOT send the layout guide to the model: providers like Seedream copy its
+    // visible slot boxes / crosslines straight into the output. Frame spacing comes
+    // from the prompt ("N evenly-spaced frames") and the explicit ROW_STRIP_SIZE;
+    // extraction divides into equal slots regardless. The base pet grounds identity.
+    const sentImages = inputImages.filter((image) => image.role !== "layout-guide");
+    const identity = sentImages.find((image) => image.role === "canonical-reference") ?? sentImages[0];
+    const result = await generateImage({
+        prompt: `${promptText}\n\n${GENERATION_LAYOUT_GUARD}`,
+        purpose: isBase ? "petdex-reference" : "petdex-row-strip",
+        ...(isBase ? {} : { animationId: job.id }),
+        style: isBase ? BASE_STYLE : ROW_STYLE,
+        size: isBase ? PETDEX_REFERENCE_IMAGE_SIZE : ROW_STRIP_SIZE,
+        imageUrl: identity?.imageUrl,
+        referenceImages: sentImages,
+        n: 1,
+        quality: "auto",
+    });
+    accumulatePetdexUsage(usage, result);
+    const mediaUrl = result.mediaUrls[0];
+    if (!mediaUrl)
+        throw new Error(`Petdex generation returned no image for job ${job.id}`);
+    return { mediaUrl, inputImages: sentImages };
+}
+async function writeDecoded(runDir, job, mediaUrl) {
+    const outputPath = path.join(runDir, job.output_path);
+    await fs.mkdir(path.dirname(outputPath), { recursive: true });
+    await fs.writeFile(outputPath, await readGeneratedPetdexImage(mediaUrl));
+}
+/**
+ * Generate a job image with the Codex vision-QA loop: up to `candidates` per
+ * prompt (initial, then the row's retry prompt), keeping the first that vision QA
+ * accepts. With no inspectImage, takes the first candidate. The chosen image is
+ * written to the decoded output path. If nothing passes, the last candidate is
+ * used — validate_atlas stays the hard contract gate.
+ */
+async function selectJobImage(ctx) {
+    const prompts = [ctx.prompt, ...(ctx.retryPrompt ? [ctx.retryPrompt] : [])].slice(0, MAX_QA_PROMPTS);
+    let fallback = null;
+    for (const promptText of prompts) {
+        for (let attempt = 0; attempt < ctx.candidates; attempt++) {
+            const candidate = await generateCandidate(ctx.runDir, ctx.job, promptText, ctx.generateImage, ctx.usage, ctx.upload);
+            if (!ctx.inspectImage) {
+                await writeDecoded(ctx.runDir, ctx.job, candidate.mediaUrl);
+                return candidate;
+            }
+            const verdict = await qaJobImage(ctx.inspectImage, ctx.job, candidate.mediaUrl, ctx.baseDataUrl);
+            if (verdict.ok) {
+                await writeDecoded(ctx.runDir, ctx.job, candidate.mediaUrl);
+                return candidate;
+            }
+            fallback = candidate;
+        }
+    }
+    const chosen = fallback ?? await generateCandidate(ctx.runDir, ctx.job, ctx.prompt, ctx.generateImage, ctx.usage, ctx.upload);
+    await writeDecoded(ctx.runDir, ctx.job, chosen.mediaUrl);
+    return chosen;
+}
+// ── Vision QA (Codex method) ───────────────────────────────
+const FRAME_COUNTS = {
+    idle: 6, "running-right": 8, "running-left": 8, waving: 4, jumping: 5, failed: 8, waiting: 6, running: 6, review: 6,
+};
+/** Lenient parse: only an explicit FAIL blocks (ambiguous output never burns regenerations). */
+function parseVerdict(text) {
+    const value = (text ?? "").trim();
+    if (/\bfail\b/i.test(value) && !/\bpass\b/i.test(value.slice(0, 8))) {
+        const match = value.match(/fail[:\s-]*(.+)/i);
+        return { ok: false, reason: (match?.[1] ?? "").trim().slice(0, 200) };
+    }
+    return { ok: true, reason: "" };
+}
+async function qaJobImage(inspectImage, job, mediaUrl, baseDataUrl) {
+    try {
+        if (job.kind === "base-pet") {
+            return parseVerdict(await inspectImage({ prompt: BASE_QA_PROMPT, imageUrls: [mediaUrl] }));
+        }
+        const frames = FRAME_COUNTS[job.id] ?? 6;
+        const imageUrls = baseDataUrl ? [mediaUrl, baseDataUrl] : [mediaUrl];
+        return parseVerdict(await inspectImage({ prompt: rowQaPrompt(job.id, frames), imageUrls }));
+    }
+    catch {
+        return { ok: true, reason: "" }; // a QA-call failure must not block generation
+    }
+}
+const BASE_QA_PROMPT = [
+    "You are a strict desktop-pet sprite reviewer. The image is a single pet character reference.",
+    "Reply PASS only if ALL hold: one centered full-body cute pet; one flat solid background; no text, scenery, picture frames, borders, drop shadows, or detached effects.",
+    'Reply with exactly "PASS" or "FAIL: <one short reason>".',
+].join(" ");
+function rowQaPrompt(state, frames) {
+    return [
+        `You are a strict sprite-sheet reviewer. Image 1 is a horizontal strip of ${frames} animation frames for a desktop pet's "${state}" animation. Image 2 is the canonical reference of the SAME pet.`,
+        "Reply PASS only if ALL hold: (1) every frame is the SAME character as the reference — same species, colors, palette, face, proportions, markings; (2) one flat solid background with NO picture frames, borders, boxes, mats, panels, dividers, or copied guide lines; (3) each pose is a complete pet, fully inside its own area, not cut off or split between cells; (4) no detached effects — no drop shadows, sparkles, dust, tears, speed lines, or text.",
+        'Reply with exactly "PASS" or "FAIL: <one short reason>".',
+    ].join(" ");
+}
+async function fileToDataUrl(filePath) {
+    const buffer = await fs.readFile(filePath);
+    const mimeType = filePath.toLowerCase().endsWith(".webp") ? "image/webp" : "image/png";
+    return `data:${mimeType};base64,${buffer.toString("base64")}`;
+}
+const MAX_ROW_REPAIRS = 2;
+/**
+ * Re-inspect extracted frames and regenerate only the rows that fail QA, using
+ * each row's retry prompt and re-extracting just that row. Mirrors the Codex
+ * "repair the smallest failing scope first" policy; bounded per row so a
+ * persistently bad row falls through to the hard validate gate rather than
+ * looping forever.
+ */
+async function repairFlaggedRows(ctx) {
+    const reviewPath = path.join(ctx.runDir, "qa", "review.json");
+    const inspect = () => runScriptSoft("inspect_frames.py", ["--frames-root", ctx.framesDir, "--json-out", reviewPath, "--chroma-adjacent-threshold", INSPECT_CHROMA_ADJ_THRESHOLD]);
+    await inspect();
+    let review = await readReview(reviewPath);
+    for (const job of ctx.generatedRows) {
+        let attempts = 0;
+        while (review && rowFailed(review, job.id) && attempts < MAX_ROW_REPAIRS) {
+            attempts++;
+            await regenerateRow(ctx, job);
+            await reextractRows(ctx, await rowsToReextract(ctx, job));
+            await inspect();
+            review = await readReview(reviewPath);
+        }
+    }
+}
+/** Regenerate one row (vision-QA loop) and update its provenance + decoded output. */
+async function regenerateRow(ctx, job) {
+    // Repairs escalate to the row's stricter retry prompt as the primary prompt.
+    const prompt = await fs.readFile(path.join(ctx.runDir, job.prompt_file), "utf-8");
+    const retryPrompt = job.retry_prompt_file
+        ? await fs.readFile(path.join(ctx.runDir, job.retry_prompt_file), "utf-8").catch(() => undefined)
+        : undefined;
+    const repairPrompt = retryPrompt ?? prompt;
+    const { mediaUrl, inputImages } = await selectJobImage({
+        runDir: ctx.runDir, job, prompt: repairPrompt, generateImage: ctx.generateImage, inspectImage: ctx.inspectImage,
+        candidates: ctx.candidates, usage: ctx.usage, upload: ctx.upload, baseDataUrl: ctx.baseDataUrl,
+    });
+    const provenance = ctx.productionJobs.find((entry) => entry.id === `row-${job.id}`);
+    if (provenance) {
+        provenance.prompt = repairPrompt;
+        provenance.outputUrl = mediaUrl;
+        provenance.inputImages = inputImages;
+    }
+}
+/** When running-right is regenerated and running-left was mirror-derived, re-mirror it. */
+async function rowsToReextract(ctx, job) {
+    if (job.id !== "running-right")
+        return job.id;
+    // running-left was mirror-derived only when there is no vision QA.
+    const leftDerived = !ctx.inspectImage && await fileExists(path.join(ctx.decodedDir, "running-left.png"));
+    if (leftDerived) {
+        await deriveRow(ctx.runDir);
+        return "running-right,running-left";
+    }
+    return "running-right";
+}
+async function reextractRows(ctx, states) {
+    await runScript("extract_strip_frames.py", ["--decoded-dir", ctx.decodedDir, "--output-dir", ctx.framesDir, "--states", states, "--chroma-key", ctx.chromaHex, "--key-threshold", CHROMA_KEY_THRESHOLD, "--method", EXTRACT_METHOD]);
+}
+async function fileExists(filePath) {
+    return fs.access(filePath).then(() => true, () => false);
+}
+/** Compose the atlas, hard-validate it, and refresh the contact sheet. */
+async function composeAndValidate(runDir, framesDir, atlasPng, atlasWebp, contactSheet) {
+    await runScript("compose_atlas.py", ["--frames-root", framesDir, "--output", atlasPng, "--webp-output", atlasWebp]);
+    // Atlas validation is the hard gate: a contract-violating atlas is never packaged.
+    await runScript("validate_atlas.py", [atlasPng, "--json-out", path.join(runDir, "qa", "validation.json")]);
+    await runScriptSoft("make_contact_sheet.py", [atlasPng, "--output", contactSheet]);
+}
+const MAX_FRAME_REPAIRS_PER_ROW = 4; // cap single-frame regenerations per row
+const SINGLE_FRAME_STYLE = "one single centered full-body desktop pet pose on a flat chroma-key background";
+const FRAME_EXTRACT_THRESHOLD = 120; // chroma distance for single-frame background removal
+// Brief per-state pose hints for single-frame regeneration (the row prompt is for
+// a whole strip; one replacement frame just needs the state's gist + identity).
+const STATE_HINTS = {
+    idle: "a calm resting pose, breathing, standing still",
+    "running-right": "a mid-stride running pose facing and moving to the right",
+    "running-left": "a mid-stride running pose facing and moving to the left",
+    waving: "raising a paw/hand/limb in a friendly wave",
+    jumping: "a mid-air playful jump",
+    failed: "a sad, deflated, slumped reaction pose",
+    waiting: "an expectant waiting pose, looking up for input",
+    running: "a focused working/thinking pose, busy but not foot-running",
+    review: "a focused inspecting pose, leaning in to review",
+};
+const MIN_FRAME_PIXELS = 400; // matches inspect_frames --min-used-pixels
+const ABSOLUTE_DARK_LUM = 45; // mean luminance below which a frame is a dark silhouette
+/**
+ * Frame-level repair (deterministic detection): score every extracted frame by
+ * non-transparent pixel count + mean brightness against the row median. Frames
+ * that are empty/fragment (too few pixels) or a dark silhouette / off-brightness
+ * (much darker than the row) are regenerated as ONE pose (img2img on the base,
+ * vision-QA'd when a vision model is present) and spliced back into the cell.
+ * No per-frame vision call — the user's "black vs blue / wrong count" defects are
+ * measurable directly, which also keeps the run fast enough for the RPC timeout.
+ */
+async function repairBadFrames(ctx) {
+    let repaired = 0;
+    for (const job of ctx.generatedRows) {
+        const frames = FRAME_COUNTS[job.id] ?? 6;
+        const stats = [];
+        for (let index = 0; index < frames; index++) {
+            stats.push(await analyzeFrame(path.join(ctx.framesDir, job.id, `${String(index).padStart(2, "0")}.png`)));
+        }
+        const medianCount = median(stats.map((s) => s.count).filter((c) => c > 0));
+        const medianLum = median(stats.map((s) => s.lum).filter((l) => l > 0));
+        let rowRepairs = 0;
+        for (let index = 0; index < frames && rowRepairs < MAX_FRAME_REPAIRS_PER_ROW; index++) {
+            const stat = stats[index];
+            const sparse = stat.count < Math.max(MIN_FRAME_PIXELS, medianCount * 0.4);
+            const dark = stat.lum < ABSOLUTE_DARK_LUM || (medianLum > 0 && stat.lum < medianLum * 0.6);
+            if (!sparse && !dark)
+                continue;
+            const single = await generateSingleFrame(ctx, job, index, frames);
+            if (!single)
+                continue;
+            await extractFrameToCell(await readGeneratedPetdexImage(single), path.join(ctx.framesDir, job.id, `${String(index).padStart(2, "0")}.png`));
+            rowRepairs++;
+            repaired++;
+        }
+    }
+    if (repaired > 0) {
+        await composeAndValidate(ctx.runDir, ctx.framesDir, ctx.atlasPng, ctx.atlasWebp, ctx.contactSheet);
+    }
+}
+/** Non-transparent pixel count + mean luminance of those pixels for one frame. */
+async function analyzeFrame(framePath) {
+    try {
+        const image = await loadImage(await fs.readFile(framePath));
+        const width = Math.max(1, image.width);
+        const height = Math.max(1, image.height);
+        const canvas = createCanvas(width, height);
+        const ctx = canvas.getContext("2d");
+        ctx.drawImage(image, 0, 0);
+        const data = ctx.getImageData(0, 0, width, height).data;
+        let count = 0;
+        let lumSum = 0;
+        for (let i = 0; i < data.length; i += 4) {
+            if ((data[i + 3] ?? 0) > 40) {
+                count++;
+                lumSum += 0.299 * (data[i] ?? 0) + 0.587 * (data[i + 1] ?? 0) + 0.114 * (data[i + 2] ?? 0);
+            }
+        }
+        return { count, lum: count ? lumSum / count : 0 };
+    }
+    catch {
+        return { count: Number.MAX_SAFE_INTEGER, lum: 255 }; // unreadable → treat as ok
+    }
+}
+function median(values) {
+    if (values.length === 0)
+        return 0;
+    const sorted = [...values].sort((a, b) => a - b);
+    const mid = Math.floor(sorted.length / 2);
+    return sorted.length % 2 ? sorted[mid] : (sorted[mid - 1] + sorted[mid]) / 2;
+}
+function frameQaPrompt(state) {
+    return [
+        `Image 1 is ONE animation frame of a desktop pet's "${state}" pose. Image 2 is the canonical reference of the SAME pet.`,
+        "Reply PASS only if image 1 shows ONE complete pet that clearly matches the reference — same species, colors, palette, BRIGHTNESS, proportions, markings; centered and fully visible.",
+        "Reply FAIL if it is a dark or black silhouette, off-colour, dimmer/brighter than the reference, cut off, empty, a fragment, or shows two pets.",
+        'Reply with exactly "PASS" or "FAIL: <one short reason>".',
+    ].join(" ");
+}
+/** Generate ONE replacement pose (img2img on the canonical base), vision-QA'd. */
+async function generateSingleFrame(ctx, job, index, frames) {
+    const prompt = [
+        `Create ONE single image of a desktop pet in the "${job.id}" animation, pose ${index + 1} of ${frames}.`,
+        "Output exactly ONE complete, centered, full-body pose of the SAME pet as the attached reference image — identical species, colors, palette, brightness, proportions, and markings.",
+        "This is a single sprite frame: NOT a strip, NOT a grid, NOT multiple poses, NOT a dark silhouette.",
+        `Pose: ${STATE_HINTS[job.id] ?? "a clear pose for this state"}.`,
+    ].join(" ");
+    let fallback = null;
+    for (let attempt = 0; attempt < ctx.candidates; attempt++) {
+        const result = await ctx.generateImage({
+            prompt: `${prompt}\n\n${GENERATION_LAYOUT_GUARD}`,
+            purpose: "petdex-reference",
+            style: SINGLE_FRAME_STYLE,
+            size: PETDEX_REFERENCE_IMAGE_SIZE,
+            imageUrl: ctx.baseDataUrl,
+            referenceImages: [{ role: "canonical-reference", imageUrl: ctx.baseDataUrl }],
+            n: 1,
+            quality: "auto",
+        });
+        accumulatePetdexUsage(ctx.usage, result);
+        const url = result.mediaUrls[0];
+        if (!url)
+            continue;
+        fallback = url;
+        if (!ctx.inspectImage)
+            return url;
+        try {
+            const verdict = parseVerdict(await ctx.inspectImage({ prompt: frameQaPrompt(job.id), imageUrls: [url, ctx.baseDataUrl] }));
+            if (verdict.ok)
+                return url;
+        }
+        catch {
+            return url; // vision-call failure → accept the candidate
+        }
+    }
+    return fallback;
+}
+/**
+ * Extract a single generated pose into one transparent 192x208 cell: detect the
+ * flat background colour from the image border, key it out, then crop-to-content
+ * and fit centred. (Single clean pose only — not the flawed multi-pose slotting.)
+ */
+async function extractFrameToCell(srcBuffer, outPath) {
+    const image = await loadImage(srcBuffer);
+    const width = Math.max(1, image.width);
+    const height = Math.max(1, image.height);
+    const canvas = createCanvas(width, height);
+    const ctx = canvas.getContext("2d");
+    ctx.drawImage(image, 0, 0);
+    const imageData = ctx.getImageData(0, 0, width, height);
+    const data = imageData.data;
+    const [kr, kg, kb] = dominantBorderColor(data, width, height);
+    for (let i = 0; i < data.length; i += 4) {
+        const dr = (data[i] ?? 0) - kr;
+        const dg = (data[i + 1] ?? 0) - kg;
+        const db = (data[i + 2] ?? 0) - kb;
+        if (Math.sqrt(dr * dr + dg * dg + db * db) <= FRAME_EXTRACT_THRESHOLD) {
+            data[i] = 0;
+            data[i + 1] = 0;
+            data[i + 2] = 0;
+            data[i + 3] = 0;
+        }
+    }
+    ctx.putImageData(imageData, 0, 0);
+    let minX = width, minY = height, maxX = -1, maxY = -1;
+    for (let y = 0; y < height; y++) {
+        for (let x = 0; x < width; x++) {
+            if ((data[(y * width + x) * 4 + 3] ?? 0) > 16) {
+                if (x < minX)
+                    minX = x;
+                if (x > maxX)
+                    maxX = x;
+                if (y < minY)
+                    minY = y;
+                if (y > maxY)
+                    maxY = y;
+            }
+        }
+    }
+    const cell = createCanvas(PETDEX_ATLAS_CONTRACT.cellWidth, PETDEX_ATLAS_CONTRACT.cellHeight);
+    const cellCtx = cell.getContext("2d");
+    if (maxX >= minX && maxY >= minY) {
+        const bw = maxX - minX + 1;
+        const bh = maxY - minY + 1;
+        const maxW = PETDEX_ATLAS_CONTRACT.cellWidth - 10;
+        const maxH = PETDEX_ATLAS_CONTRACT.cellHeight - 10;
+        const scale = Math.min(maxW / bw, maxH / bh, 1);
+        const dw = bw * scale;
+        const dh = bh * scale;
+        cellCtx.imageSmoothingEnabled = true;
+        cellCtx.imageSmoothingQuality = "high";
+        cellCtx.drawImage(canvas, minX, minY, bw, bh, (PETDEX_ATLAS_CONTRACT.cellWidth - dw) / 2, (PETDEX_ATLAS_CONTRACT.cellHeight - dh) / 2, dw, dh);
+    }
+    await fs.mkdir(path.dirname(outPath), { recursive: true });
+    await fs.writeFile(outPath, Buffer.from(cell.toBuffer("image/png")));
+}
+/** Dominant colour of an inset border ring (the flat chroma background). */
+function dominantBorderColor(data, width, height) {
+    const inset = Math.max(4, Math.floor(Math.min(width, height) * 0.02));
+    const step = Math.max(1, Math.floor(width / 200));
+    const buckets = new Map();
+    const sample = (x, y) => {
+        const idx = (y * width + x) * 4;
+        const r = data[idx] ?? 0, g = data[idx + 1] ?? 0, b = data[idx + 2] ?? 0;
+        if (r + g + b < 24)
+            return;
+        const key = ((r >> 4) << 8) | ((g >> 4) << 4) | (b >> 4);
+        const e = buckets.get(key) ?? { n: 0, r: 0, g: 0, b: 0 };
+        e.n++;
+        e.r += r;
+        e.g += g;
+        e.b += b;
+        buckets.set(key, e);
+    };
+    for (let x = inset; x < width - inset; x += step) {
+        sample(x, inset);
+        sample(x, height - 1 - inset);
+    }
+    for (let y = inset; y < height - inset; y += step) {
+        sample(inset, y);
+        sample(width - 1 - inset, y);
+    }
+    let best = null;
+    for (const e of buckets.values())
+        if (!best || e.n > best.n)
+            best = e;
+    if (!best || best.n === 0)
+        return [255, 0, 255];
+    return [Math.round(best.r / best.n), Math.round(best.g / best.n), Math.round(best.b / best.n)];
+}
+function rowFailed(review, state) {
+    const row = review.rows.find((entry) => entry.state === state);
+    return row ? row.ok === false : false;
+}
+async function readReview(reviewPath) {
+    return readJson(reviewPath).catch(() => null);
+}
+async function resolveJobImages(runDir, job, upload) {
+    const images = [];
+    for (const image of job.input_images) {
+        const absPath = path.join(runDir, image.path);
+        // canonical-base is produced after the base job; tolerate its absence on
+        // the base job itself (where it is not referenced anyway).
+        const buffer = await fs.readFile(absPath).catch(() => null);
+        if (!buffer)
+            continue;
+        const imageUrl = await toImageUrl(buffer, path.basename(absPath), upload);
+        images.push({ role: mapReferenceRole(image.role), imageUrl });
+    }
+    return images;
+}
+function mapReferenceRole(role) {
+    const lower = role.toLowerCase();
+    if (lower.includes("layout guide"))
+        return "layout-guide";
+    if (lower.includes("atlas"))
+        return "existing-atlas";
+    return "canonical-reference";
+}
+async function toImageUrl(buffer, filename, upload) {
+    const mimeType = filename.toLowerCase().endsWith(".webp") ? "image/webp" : "image/png";
+    if (upload)
+        return upload({ buffer, mimeType, filename });
+    return `data:${mimeType};base64,${buffer.toString("base64")}`;
+}
+async function stageReferenceFiles(input) {
+    const buffers = [];
+    if (input.referenceImageUrl)
+        buffers.push(await readGeneratedPetdexImage(input.referenceImageUrl));
+    // A refine run grounds identity on the existing atlas.
+    if (input.baseSpritesheet)
+        buffers.push(input.baseSpritesheet);
+    if (buffers.length === 0)
+        return [];
+    const stagingDir = await fs.mkdtemp(path.join(os.tmpdir(), "petdex-ref-"));
+    const files = [];
+    for (let index = 0; index < buffers.length; index++) {
+        const file = path.join(stagingDir, `reference-${String(index + 1).padStart(2, "0")}.png`);
+        await fs.writeFile(file, buffers[index]);
+        files.push(file);
+    }
+    return files;
+}
+async function createRunDir() {
+    const base = process.env.QLOGICAGENT_PETDEX_RUN_DIR?.trim() || os.tmpdir();
+    await fs.mkdir(base, { recursive: true });
+    return fs.mkdtemp(path.join(base, "petdex-run-"));
+}
+function keepRuns() {
+    const value = process.env.QLOGICAGENT_PETDEX_KEEP_RUNS?.trim().toLowerCase();
+    return value === "1" || value === "true";
+}
+async function cleanupDir(dir) {
+    if (!dir)
+        return;
+    await fs.rm(dir, { recursive: true, force: true }).catch(() => undefined);
+}
+async function readJson(file) {
+    return JSON.parse(await fs.readFile(file, "utf-8"));
+}
+/**
+ * Detect the flat background colour the model actually rendered, by taking the
+ * dominant colour of an inset border ring of the base image. Image models do not
+ * honour the requested chroma hex, so extraction must key on what was produced.
+ */
+async function detectChromaHex(pngPath) {
+    try {
+        const image = await loadImage(await fs.readFile(pngPath));
+        const width = Math.max(1, image.width);
+        const height = Math.max(1, image.height);
+        const canvas = createCanvas(width, height);
+        const ctx = canvas.getContext("2d");
+        ctx.drawImage(image, 0, 0);
+        const data = ctx.getImageData(0, 0, width, height).data;
+        const inset = Math.max(8, Math.floor(Math.min(width, height) * 0.02));
+        const step = Math.max(1, Math.floor(width / 240));
+        const buckets = new Map();
+        const sample = (x, y) => {
+            const idx = (y * width + x) * 4;
+            const a = data[idx + 3] ?? 0;
+            const r = data[idx] ?? 0;
+            const g = data[idx + 1] ?? 0;
+            const b = data[idx + 2] ?? 0;
+            if (a < 200)
+                return;
+            if (r + g + b < 48)
+                return; // skip near-black borders/separator lines
+            const key = ((r >> 4) << 8) | ((g >> 4) << 4) | (b >> 4);
+            const e = buckets.get(key) ?? { n: 0, r: 0, g: 0, b: 0 };
+            e.n++;
+            e.r += r;
+            e.g += g;
+            e.b += b;
+            buckets.set(key, e);
+        };
+        for (let x = inset; x < width - inset; x += step) {
+            sample(x, inset);
+            sample(x, height - 1 - inset);
+        }
+        for (let y = inset; y < height - inset; y += step) {
+            sample(inset, y);
+            sample(width - 1 - inset, y);
+        }
+        let best = null;
+        for (const e of buckets.values())
+            if (!best || e.n > best.n)
+                best = e;
+        if (!best || best.n === 0)
+            return FALLBACK_CHROMA_HEX;
+        const r = Math.round(best.r / best.n);
+        const g = Math.round(best.g / best.n);
+        const b = Math.round(best.b / best.n);
+        return `#${[r, g, b].map((v) => v.toString(16).padStart(2, "0")).join("")}`.toUpperCase();
+    }
+    catch {
+        return FALLBACK_CHROMA_HEX;
+    }
+}
+function asciiSlug(value) {
+    const slug = value.replace(/[^a-zA-Z0-9]+/g, "-").replace(/^-+|-+$/g, "").toLowerCase();
+    return slug || "petdex";
+}
+async function runScript(script, args) {
+    const result = await runHatchPetScript(script, args, { timeoutMs: 180_000 });
+    if (!result.ok) {
+        throw new Error(`Petdex pipeline step ${script} failed (exit ${result.code ?? "?"}): ${result.stderr.trim() || result.stdout.trim()}`);
+    }
+}
+async function runScriptSoft(script, args) {
+    await runHatchPetScript(script, args, { timeoutMs: 180_000 }).catch(() => undefined);
+}