pixelkiln 0.16.0 → 0.18.0

package/dist/cli.js

@@ -123,13 +123,14 @@ async function sha256File(path25) {
     stream.on("end", () => resolve(hash.digest("hex")));
   });
 }
-function specHash(spec, styleImageHashes, providerOptionIdentity = spec.providerOptions) {
+function specHash(spec, styleImageHashes, providerOptionIdentity = spec.providerOptions, providerInputIdentity = spec.providerInputs ?? {}) {
   return sha256(
     JSON.stringify({
       // Preserve every existing PixelLab hash while making a provider switch
       // invalidate the spec. Older manifests implicitly mean pixellab.
       provider: spec.provider === "pixellab" ? void 0 : spec.provider,
       providerOptions: providerOptionIdentity && (typeof providerOptionIdentity !== "object" || Object.keys(providerOptionIdentity).length > 0) ? providerOptionIdentity : void 0,
+      providerInputs: providerInputIdentity && (typeof providerInputIdentity !== "object" || Object.keys(providerInputIdentity).length > 0) ? providerInputIdentity : void 0,
       generator: spec.generator,
       prompt: spec.prompt,
       width: spec.width,
@@ -604,6 +605,16 @@ function cacheFileName(hash, mediaType = MediaType.PNG) {
 
 // src/providers/comfyui.ts
 var DEFAULT_BASE_URL = "http://127.0.0.1:8188";
+var BUILTIN_BINDINGS = /* @__PURE__ */ new Set([
+  "prompt",
+  "width",
+  "height",
+  "batchSize",
+  "seed",
+  "sourceImage",
+  "maskImage",
+  "strength"
+]);
 var ComfyUIClient = class {
   constructor(baseUrl = process.env.COMFYUI_BASE_URL ?? DEFAULT_BASE_URL, request = fetch) {
     this.request = request;
@@ -753,6 +764,63 @@ var ComfyUIProvider = class _ComfyUIProvider {
       }
     };
   }
+  async resolveInputs(value, context) {
+    const options = parseOptions(context.providerOptions);
+    if (!options.workflow || !options.workflowSha256) {
+      throw new Error("ComfyUI provider inputs require resolved workflow options");
+    }
+    const inputs = {};
+    const identity = {};
+    for (const [name, input] of Object.entries(value)) {
+      if (BUILTIN_BINDINGS.has(name)) {
+        throw new Error(
+          `ComfyUI providerInputs.${name} is reserved; use PixelKiln's built-in ${name} field`
+        );
+      }
+      const binding = Object.hasOwn(options.bindings, name) ? options.bindings[name] : void 0;
+      if (!binding) {
+        throw new Error(
+          `ComfyUI providerInputs.${name} has no matching bindings.${name} target`
+        );
+      }
+      if (isImageBinding(options.workflow, binding)) {
+        if (typeof input !== "string") {
+          throw new Error(`ComfyUI providerInputs.${name} must be a manifest-relative PNG or JPEG path`);
+        }
+        const file = path2.resolve(context.root, input);
+        let bytes;
+        try {
+          bytes = await readFile(file);
+        } catch (error) {
+          throw new Error(
+            `ComfyUI providerInputs.${name} could not be read at ${file}: ${error instanceof Error ? error.message : String(error)}`
+          );
+        }
+        const format = inputImageFormat(bytes);
+        if (!format) {
+          throw new Error(`ComfyUI providerInputs.${name} is not a PNG or JPEG: ${file}`);
+        }
+        const hash = sha256(bytes);
+        inputs[name] = { kind: "image", path: file, sha256: hash, format };
+        identity[name] = { kind: "image", sha256: hash, format };
+      } else {
+        const current = options.workflow[binding.nodeId].inputs[binding.input];
+        if (typeof current !== "string" && typeof current !== "number" && typeof current !== "boolean") {
+          throw new Error(
+            `ComfyUI providerInputs.${name} cannot replace non-scalar ${binding.nodeId}.${binding.input}`
+          );
+        }
+        if (typeof current !== typeof input) {
+          throw new Error(
+            `ComfyUI providerInputs.${name} must be ${typeof current} to match ${binding.nodeId}.${binding.input}`
+          );
+        }
+        inputs[name] = input;
+        identity[name] = input;
+      }
+    }
+    return { inputs, identity };
+  }
   supports(generator) {
     return generator === "map";
   }
@@ -820,6 +888,20 @@ var ComfyUIProvider = class _ComfyUIProvider {
     if (spec.seed != null && options.bindings.seed) {
       setBinding(workflow, options.bindings.seed, spec.seed);
     }
+    for (const [name, input] of Object.entries(spec.providerInputs ?? {})) {
+      const binding = Object.hasOwn(options.bindings, name) ? options.bindings[name] : void 0;
+      if (!binding) throw new Error(`ComfyUI provider input "${name}" has no binding`);
+      if (isComfyImageInput(input)) {
+        const bytes = await readFile(input.path);
+        if (sha256(bytes) !== input.sha256) {
+          throw new Error(`ComfyUI provider input "${name}" changed before upload`);
+        }
+        const uploaded = await this.client.uploadImage(bytes, input.sha256, input.format);
+        setBinding(workflow, binding, uploaded);
+      } else {
+        setBinding(workflow, binding, input);
+      }
+    }
     if (spec.revision) {
       if (!spec.revision.sourceSha256 || !spec.revision.sourceFormat) {
         throw new Error("ComfyUI revision source is not ready");
@@ -854,19 +936,22 @@ var ComfyUIProvider = class _ComfyUIProvider {
       }
     }
     const promptId = await this.client.submit(workflow);
-    return {
-      jobId: encodeJob(promptId, options.outputNodeId),
+    const inputs = providerInputProvenance(spec.providerInputs);
+    const metadata = {
+      ...Object.keys(inputs).length ? { inputs } : {},
       ...spec.revision ? {
-        metadata: {
-          revision: {
-            mode: spec.revision.mode,
-            sourceAssetId: spec.revision.sourceAssetId,
-            sourceSha256: spec.revision.sourceSha256,
-            ...spec.revision.maskSha256 ? { maskSha256: spec.revision.maskSha256 } : {}
-          }
+        revision: {
+          mode: spec.revision.mode,
+          sourceAssetId: spec.revision.sourceAssetId,
+          sourceSha256: spec.revision.sourceSha256,
+          ...spec.revision.maskSha256 ? { maskSha256: spec.revision.maskSha256 } : {}
         }
       } : {}
     };
+    return {
+      jobId: encodeJob(promptId, options.outputNodeId),
+      ...Object.keys(metadata).length ? { metadata } : {}
+    };
   }
   async poll(jobId, _generator, context) {
     const { promptId, outputNodeId } = decodeJob(jobId);
@@ -941,28 +1026,10 @@ function parseOptions(value) {
     throw new Error("ComfyUI numImages must be a whole number from 1 to 16");
   }
   if (!isObject(value.bindings)) throw new Error("ComfyUI bindings must be an object");
-  const bindingKeys = /* @__PURE__ */ new Set([
-    "prompt",
-    "width",
-    "height",
-    "batchSize",
-    "seed",
-    "sourceImage",
-    "maskImage",
-    "strength"
-  ]);
-  const extraBindings = Object.keys(value.bindings).filter((key) => !bindingKeys.has(key));
-  if (extraBindings.length) throw new Error(`Unknown ComfyUI binding(s): ${extraBindings.join(", ")}`);
-  const bindings = {
-    prompt: parseBinding(value.bindings.prompt, "prompt"),
-    ...value.bindings.width == null ? {} : { width: parseBinding(value.bindings.width, "width") },
-    ...value.bindings.height == null ? {} : { height: parseBinding(value.bindings.height, "height") },
-    ...value.bindings.batchSize == null ? {} : { batchSize: parseBinding(value.bindings.batchSize, "batchSize") },
-    ...value.bindings.seed == null ? {} : { seed: parseBinding(value.bindings.seed, "seed") },
-    ...value.bindings.sourceImage == null ? {} : { sourceImage: parseBinding(value.bindings.sourceImage, "sourceImage") },
-    ...value.bindings.maskImage == null ? {} : { maskImage: parseBinding(value.bindings.maskImage, "maskImage") },
-    ...value.bindings.strength == null ? {} : { strength: parseBinding(value.bindings.strength, "strength") }
-  };
+  const bindings = Object.fromEntries(
+    Object.entries(value.bindings).map(([name, binding]) => [name, parseBinding(binding, name)])
+  );
+  if (!bindings.prompt) throw new Error("ComfyUI bindings.prompt must be an object");
   const workflow = value.workflow == null ? void 0 : parseWorkflow(value.workflow, workflowFile);
   const workflowSha256 = value.workflowSha256 == null ? void 0 : requiredString(value.workflowSha256, "workflowSha256");
   return {
@@ -1002,6 +1069,7 @@ function parseWorkflow(value, label) {
   return value;
 }
 function validateWorkflowBindings(workflow, options) {
+  const targets = /* @__PURE__ */ new Map();
   for (const [name, binding] of Object.entries(options.bindings)) {
     if (!binding) continue;
     const node = workflow[binding.nodeId];
@@ -1011,6 +1079,12 @@ function validateWorkflowBindings(workflow, options) {
         `ComfyUI ${name} binding refers to missing input "${binding.input}" on node "${binding.nodeId}"`
       );
     }
+    const target = `${binding.nodeId}.${binding.input}`;
+    const prior = targets.get(target);
+    if (prior) {
+      throw new Error(`ComfyUI bindings.${name} and bindings.${prior} target the same input ${target}`);
+    }
+    targets.set(target, name);
   }
   if (!workflow[options.outputNodeId]) {
     throw new Error(`ComfyUI outputNodeId refers to missing node "${options.outputNodeId}"`);
@@ -1048,6 +1122,7 @@ function outputImages(entry, outputNodeId) {
 }
 function comfyMetadata(spec, promptId, outputNodeId, images) {
   const options = resolvedOptions(spec);
+  const inputs = providerInputProvenance(spec.providerInputs);
   return {
     promptId,
     outputNodeId,
@@ -1055,6 +1130,7 @@ function comfyMetadata(spec, promptId, outputNodeId, images) {
     workflowFile: options.workflowFile,
     workflowSha256: options.workflowSha256,
     files: images.map((image) => ({ ...image })),
+    ...Object.keys(inputs).length ? { inputs } : {},
     ...spec.revision ? {
       revision: {
         mode: spec.revision.mode,
@@ -1066,6 +1142,41 @@ function comfyMetadata(spec, promptId, outputNodeId, images) {
     } : {}
   };
 }
+function isImageBinding(workflow, binding) {
+  const node = workflow[binding.nodeId];
+  return binding.input === "image" && (node?.class_type === "LoadImage" || node?.class_type === "LoadImageMask");
+}
+function isComfyImageInput(value) {
+  return isObject(value) && value.kind === "image" && typeof value.path === "string" && typeof value.sha256 === "string" && (value.format === "png" || value.format === "jpeg");
+}
+function providerInputProvenance(inputs) {
+  return Object.fromEntries(Object.entries(inputs ?? {}).map(([name, input]) => [
+    name,
+    isComfyImageInput(input) ? { kind: "image", sha256: input.sha256, format: input.format } : { kind: "value", value: input }
+  ]));
+}
+function inputImageFormat(bytes) {
+  if (bytes.length >= 24 && bytes.readUInt32BE(0) === 2303741511 && bytes.readUInt32BE(4) === 218765834 && bytes.toString("ascii", 12, 16) === "IHDR" && bytes.readUInt32BE(16) > 0 && bytes.readUInt32BE(20) > 0) return "png";
+  if (bytes.length < 4 || bytes[0] !== 255 || bytes[1] !== 216) return null;
+  let offset = 2;
+  while (offset + 3 < bytes.length) {
+    if (bytes[offset] !== 255) return null;
+    while (bytes[offset] === 255) offset++;
+    const marker = bytes[offset++];
+    if (marker == null || marker === 217 || marker === 218) break;
+    if (marker === 1 || marker >= 208 && marker <= 215) continue;
+    if (offset + 2 > bytes.length) return null;
+    const length = bytes.readUInt16BE(offset);
+    if (length < 2 || offset + length > bytes.length) return null;
+    const isStartOfFrame = marker >= 192 && marker <= 207 && ![196, 200, 204].includes(marker);
+    if (isStartOfFrame) {
+      if (length < 7) return null;
+      return bytes.readUInt16BE(offset + 3) > 0 && bytes.readUInt16BE(offset + 5) > 0 ? "jpeg" : null;
+    }
+    offset += length;
+  }
+  return null;
+}
 function encodeJob(promptId, outputNodeId) {
   return `${promptId}#${encodeURIComponent(outputNodeId)}`;
 }
@@ -1550,7 +1661,9 @@ var QualityProfileSchema = z2.object({
   /** Optional alpha requirement for isolated assets. */
   minTransparency: z2.number().min(0).max(1).optional(),
   /** Pixel Art Fixer revision written into the quality record. */
-  fixerRevision: z2.string().min(1).optional()
+  fixerRevision: z2.string().min(1).optional(),
+  /** Python executable containing Pixel Art Fixer, relative to the manifest unless absolute. */
+  fixerPython: z2.string().min(1).optional()
 }).strict().refine(
   (profile) => new Set(profile.palette.map((color) => color.replace(/^#/, "").toLowerCase())).size === profile.palette.length,
   { message: "quality palette colors must be unique", path: ["palette"] }
@@ -1766,7 +1879,13 @@ var AssetSchema = z2.object({
    * exactly right for a colour style. Editing the shared prompt to suit one
    * style would invalidate every other style's already-generated art.
    */
-  promptByStyle: z2.record(z2.string()).default({})
+  promptByStyle: z2.record(z2.string()).default({}),
+  /**
+   * Named per-asset values consumed by the active provider's declared
+   * bindings. Values are JSON scalars; adapters may interpret a string as a
+   * manifest-relative file when the target node accepts an uploaded input.
+   */
+  providerInputs: z2.record(z2.union([z2.string(), z2.number().finite(), z2.boolean()])).default({})
 }).strict().superRefine((asset, context) => {
   if (asset.source && asset.revision) {
     context.addIssue({
@@ -1804,6 +1923,18 @@ var LockEntrySchema = z2.object({
     maskSha256: z2.string().regex(/^[0-9a-f]{64}$/).optional(),
     strength: z2.number().min(0).max(1).optional()
   }).strict().nullable().default(null),
+  /**
+   * Output hashes owned by the previous generation while its replacement is
+   * pending. They authorize replacing only unchanged PixelKiln-owned files.
+   */
+  supersededOutputs: z2.array(
+    z2.object({
+      path: z2.string(),
+      sha256: z2.string(),
+      role: z2.string().optional(),
+      mediaType: MediaTypeSchema.optional()
+    })
+  ).optional(),
   /** Set at submit time, before the request is awaited, so a crash is recoverable. */
   jobId: z2.string().nullable().default(null),
   /** For `1dir`: the multi-candidate parent object awaiting selection. */
@@ -3197,6 +3328,7 @@ async function resolveSpecs(loaded, filter) {
       return { base64: hit.base64, width: hit.width, height: hit.height, format: hit.format };
     });
     const styleSpecs = /* @__PURE__ */ new Map();
+    const providerInputIdentities = /* @__PURE__ */ new Map();
     for (const [assetId, asset] of Object.entries(manifest.assets)) {
       if (!resolutionAssetIds.has(assetId)) continue;
       if (asset.styles.length && !asset.styles.includes(styleId)) continue;
@@ -3204,6 +3336,20 @@ async function resolveSpecs(loaded, filter) {
       if (!activeProvider.supports(generator)) {
         throw new Error(`Provider "${activeProvider.id}" does not support generator "${generator}"`);
       }
+      if (Object.keys(asset.providerInputs).length && !activeProvider.resolveInputs) {
+        throw new Error(
+          `Provider "${activeProvider.id}" does not support asset providerInputs (${styleId}/${assetId})`
+        );
+      }
+      const inputResolution = activeProvider.resolveInputs ? await activeProvider.resolveInputs(asset.providerInputs, {
+        root,
+        styleId,
+        assetId,
+        providerOptions
+      }) : { inputs: {} };
+      const providerInputs = inputResolution.inputs;
+      const providerInputIdentity = inputResolution.identity ?? providerInputs;
+      providerInputIdentities.set(assetId, providerInputIdentity);
       let width;
       let height;
       let size;
@@ -3232,6 +3378,7 @@ async function resolveSpecs(loaded, filter) {
         assetId,
         provider: activeProvider.id,
         providerOptions,
+        providerInputs,
         generator,
         prompt,
         width,
@@ -3273,7 +3420,8 @@ async function resolveSpecs(loaded, filter) {
             palette: style.quality.palette,
             minGridConfidence: style.quality.minGridConfidence,
             ...style.quality.minTransparency == null ? {} : { minTransparency: style.quality.minTransparency },
-            ...style.quality.fixerRevision ? { fixerRevision: style.quality.fixerRevision } : {}
+            ...style.quality.fixerRevision ? { fixerRevision: style.quality.fixerRevision } : {},
+            ...style.quality.fixerPython ? { fixerPython: path4.resolve(root, style.quality.fixerPython) } : {}
           }
         } : {},
         tags,
@@ -3329,7 +3477,12 @@ async function resolveSpecs(loaded, filter) {
           ...asset.revision.strength == null ? {} : { strength: asset.revision.strength }
         };
       }
-      resolved.specHash = specHash(resolved, styleImageHashes, providerOptionIdentity);
+      resolved.specHash = specHash(
+        resolved,
+        styleImageHashes,
+        providerOptionIdentity,
+        providerInputIdentities.get(assetId)
+      );
       activeProvider.validate?.(resolved, resolvedImages);
       const estimate = validateCostEstimate(activeProvider.id, activeProvider.estimate(resolved));
       resolved.cost = estimate.amount;
@@ -5075,7 +5228,9 @@ async function refineQualityProfiles(specs, lock, options = {}) {
         minGridConfidence: spec.quality.minGridConfidence,
         ...spec.quality.minTransparency == null ? {} : { minTransparency: spec.quality.minTransparency },
         fixerRevision: spec.quality.fixerRevision ?? PIXEL_ART_FIXER_REVISION,
-        fixerPython: options.fixerPython,
+        // A one-off CLI/library override wins; otherwise each style can carry
+        // the stable project-local interpreter that provides its pinned fixer.
+        fixerPython: options.fixerPython ?? spec.quality.fixerPython,
         fixerCommand: options.fixerCommand,
         fixerArgsPrefix: options.fixerArgsPrefix,
         force: options.force
@@ -5199,6 +5354,29 @@ async function anyOutputModified(entry, spec) {
   }
   return false;
 }
+function resumeCommandForStatus(status) {
+  if (status === "pending" || status === "processing") return "poll";
+  if (status === "review") return "pick";
+  if (status === "selected" || status === "download-failed") return "fetch";
+  return null;
+}
+function resumeActions(specs, lock) {
+  const grouped = /* @__PURE__ */ new Map();
+  for (const spec of specs) {
+    const key = lockKey(spec.styleId, spec.assetId);
+    const entry = lock.entries[key];
+    if (!entry || entry.specHash !== spec.specHash) continue;
+    const command = resumeCommandForStatus(entry.status);
+    if (!command) continue;
+    if (command === "poll" && !entry.jobId) continue;
+    if (command === "pick" && !entry.reviewObjectId) continue;
+    grouped.set(command, [...grouped.get(command) ?? [], key]);
+  }
+  return ["poll", "pick", "fetch"].flatMap((command) => {
+    const keys = grouped.get(command);
+    return keys?.length ? [{ command, keys }] : [];
+  });
+}
 async function buildPlan(specs, lock, opts = {}) {
   const items = [];
   for (const spec of specs) {
@@ -5234,10 +5412,20 @@ async function buildPlan(specs, lock, opts = {}) {
       reason = "prompt, size, or style changed";
     } else if (entry.status === "download-failed") {
       state = "recoverable";
-      reason = `${entry.error ?? "download failed"}; run fetch or restore (no generation cost)`;
+      const force = entry.error?.includes("pass --force") ? " --force" : "";
+      reason = `${entry.error ?? "download failed"}; run pixelkiln fetch${force} (no generation cost)`;
     } else if (entry.status === "failed") {
       state = "failed";
       reason = entry.error ?? "previous attempt failed";
+    } else if (entry.status === "selected") {
+      state = "recoverable";
+      reason = "provider output is selected; run pixelkiln fetch (no generation cost)";
+    } else if (entry.status === "pending" || entry.status === "processing") {
+      state = "in-flight";
+      reason = entry.jobId ? "awaiting processing; run pixelkiln poll" : "submission state has no job id; run pixelkiln doctor before retrying";
+    } else if (entry.status === "review") {
+      state = "in-flight";
+      reason = entry.reviewObjectId ? "awaiting review; run pixelkiln pick" : "review state has no review object id; run pixelkiln doctor";
     } else if (entry.status !== "downloaded") {
       state = "in-flight";
       reason = `awaiting ${entry.status}`;
@@ -5374,6 +5562,8 @@ async function submit(provider, loaded, items, lock, lockPath, opts = {}) {
     const since = Date.now() - lastSubmitAt;
     if (since < spacing) await sleep2(spacing - since);
     await requireRevisionReady(spec, lock);
+    const previousEntry = lock.entries[key];
+    const supersededOutputs = previousEntry?.outputs.length ? previousEntry.outputs : previousEntry?.supersededOutputs ?? [];
     upsert(lock, key, {
       styleId: spec.styleId,
       assetId: spec.assetId,
@@ -5397,6 +5587,9 @@ async function submit(provider, loaded, items, lock, lockPath, opts = {}) {
       candidateIndex: null,
       error: null,
       outputs: [],
+      // Keep the old ownership proof while new bytes are pending. Fetch may
+      // replace that file only while its hash still matches this record.
+      supersededOutputs,
       providerMetadata: {},
       sourceUrl: null,
       sourceUrls: [],
@@ -5607,22 +5800,37 @@ async function fetchAssets(provider, specs, lock, lockPath, opts = {}) {
           );
           const target = recorded ? resolveOutputPath(recorded.path, spec.root) : expectedOutputPath(spec, source.role, index, sources.length, source.mediaType);
           if (existsSync9(target)) {
-            if (!recorded) {
-              throw new Error(`refusing to overwrite untracked output ${target}`);
-            }
-            if (await sha256File(target) !== recorded.sha256) {
-              throw new Error(`refusing to overwrite modified output ${target}`);
+            const currentHash = await sha256File(target);
+            if (recorded && currentHash === recorded.sha256) {
+              if (cacheDir) {
+                await cacheMedia(
+                  cacheDir,
+                  await readFile7(target),
+                  recorded.mediaType ?? MediaType.PNG,
+                  recorded.sha256
+                );
+              }
+              outputs.push({ ...recorded, path: portableOutputPath(target, spec.root) });
+              continue;
             }
-            if (cacheDir) {
-              await cacheMedia(
-                cacheDir,
-                await readFile7(target),
-                recorded.mediaType ?? MediaType.PNG,
-                recorded.sha256
-              );
+            const superseded = (entry.supersededOutputs ?? []).find(
+              (output, oldIndex, all) => currentOutputPath(output, spec, oldIndex, all.length) === target
+            );
+            if (!opts.force) {
+              if (!recorded && superseded && currentHash === superseded.sha256) {
+              } else if (recorded || superseded) {
+                throw new Error(
+                  `refusing to overwrite modified output ${target}; pass --force to replace it`
+                );
+              } else {
+                throw new Error(
+                  `refusing to overwrite untracked output ${target}; pass --force to replace it`
+                );
+              }
             }
-            outputs.push({ ...recorded, path: portableOutputPath(target, spec.root) });
-            continue;
+            log2(
+              `  replace ${path14.relative(process.cwd(), target)}` + (opts.force ? " (--force)" : " (previous tracked generation)")
+            );
           }
           const expectedMediaType = source.mediaType ?? recorded?.mediaType ?? MediaType.PNG;
           let buf = recorded && cacheDir ? await readCachedMedia(cacheDir, recorded.sha256, expectedMediaType) : null;
@@ -5670,7 +5878,8 @@ async function fetchAssets(provider, specs, lock, lockPath, opts = {}) {
           sourceUrl: persistentSources[0]?.url ?? null,
           sourceUrls: persistentSources,
           downloadedAt: (/* @__PURE__ */ new Date()).toISOString(),
-          error: null
+          error: null,
+          supersededOutputs: []
         });
         result.downloaded++;
       } catch (err) {
@@ -5841,6 +6050,14 @@ async function doctor(loaded, specs, lock, lockPath, opts = {}) {
     unsettled ? "warning" : "ok",
     unsettled ? `${unsettled} spec(s) are not current: ` + Object.entries(counts).filter(([, n]) => n > 0).map(([state, n]) => `${n} ${state}`).join(", ") : "every resolved spec is current"
   );
+  const resumable = resumeActions(specs, lock);
+  add(
+    "next-actions",
+    resumable.length ? "warning" : "ok",
+    resumable.length ? "resume paid work without regenerating: " + resumable.map(
+      (action) => `pixelkiln ${action.command} (${action.keys.length} asset${action.keys.length === 1 ? "" : "s"})`
+    ).join(", ") : "no generation stage is waiting for poll, pick, or fetch"
+  );
   const quality = plan.items.flatMap((item) => item.quality ? [item.quality] : []);
   const qualityPending = quality.filter((item) => item.state !== "approved");
   if (quality.length) {
@@ -6578,10 +6795,15 @@ async function runPicker(provider, lock, lockPath, opts = {}) {
     onProgress: log2,
     assets: reviewAssets,
     onReady: (url) => {
-      log2(`
+      const info = { url, keys: groups.map((group) => group.key) };
+      if (opts.onReady) {
+        opts.onReady(info);
+      } else {
+        log2(`
   ${groups.length} asset(s) awaiting selection: ${url}`);
-      log2(`  (leave this running; it exits once you apply)
+        log2(`  (leave this running; it exits once you apply)
 `);
+      }
     },
     handleApply: async (body) => {
       const { selections } = body;
@@ -6683,6 +6905,7 @@ function buildManifest(name, styleId, generator, outDir, scanned) {
       file: asset.file,
       tags: [],
       styles: [],
+      providerInputs: {},
       ...generator === "map" ? { width: asset.width, height: asset.height } : asset.width === asset.height && asset.width !== commonSize ? { size: asset.width } : {}
     };
   }
@@ -7745,6 +7968,7 @@ async function runSalvage(provider, orphans, ctx, opts = {}) {
               file: rel,
               tags: ["salvaged"],
               styles: [ctx.styleId],
+              providerInputs: {},
               ...orphan.width === orphan.height ? { size: orphan.width } : { width: orphan.width, height: orphan.height }
             };
             const durableSource = shouldPersistSourceUrl(orphan.previewUrl) ? orphan.previewUrl : null;
@@ -8543,6 +8767,17 @@ async function checkQualityBaseline(baselinePath) {
 
 // src/cli.ts
 var log = (msg = "") => console.log(msg);
+function announceReviewReady(info, stdout = process.stdout, stderr = process.stderr) {
+  const stream = stdout.isTTY ? stdout : stderr;
+  const count = info.keys.length;
+  stream.write(
+    `
+  ${count} asset${count === 1 ? "" : "s"} awaiting selection: ${info.url}
+  (leave this running; it exits once you apply)
+
+`
+  );
+}
 async function provenanceFile(id, file) {
   const absolute = path24.resolve(file);
   return {
@@ -8900,7 +9135,7 @@ Options
   --max-colors <n>    audit: maximum distinct opaque colors
   --sigma <n>         audit: relative outlier cutoff (default: 1.5)
   --palette <hexes>   refine: final comma-separated #rrggbb colors (repeatable)
-  --fixer-python <path>  refine: Python with Pixel Art Fixer installed
+  --fixer-python <path>  refine: override Python with Pixel Art Fixer installed
   --fixer-revision <sha>  refine: Pixel Art Fixer revision to record
   --min-grid-confidence <level>  refine: high (default), medium, or low
   --reviewer <name>   refine approve: human reviewer recorded in provenance
@@ -8914,7 +9149,7 @@ Options
   --budget <n|provider=n>  Refuse to exceed one provider ceiling; repeat keyed budgets
                            for a mixed-provider run
   --provider <id>     Choose the account for balance/adopt/salvage/purge in a mixed manifest
-  --force             Regenerate; also rerun refinement or replace changed derived state
+  --force             Regenerate, replace a fetch destination, or rebuild managed output
   --dry-run           Never spend; doctor also skips provider connectivity
   --all               salvage --dry-run: list every unclaimed object, not just the first 30
   --json              Machine-readable output where supported, including quality checks
@@ -8997,6 +9232,17 @@ function printPlan(plan) {
     }
   }
 }
+function printResumeActions(specs, lock) {
+  const actions = resumeActions(specs, lock);
+  for (const action of actions) {
+    const shown = action.keys.slice(0, 3).join(", ");
+    const more = action.keys.length > 3 ? `, +${action.keys.length - 3} more` : "";
+    log(
+      `  next: pixelkiln ${action.command} \u2014 ${action.keys.length} asset${action.keys.length === 1 ? "" : "s"} (${shown}${more})`
+    );
+  }
+  return actions.length;
+}
 function manifestProviderIds(manifest) {
   return [...new Set(
     Object.values(manifest.styles).map((style) => style.provider ?? manifest.provider)
@@ -10395,7 +10641,10 @@ async function main() {
   ${total.completed} ready \xB7 ${total.review} awaiting selection \xB7 ${total.failed} failed`
     );
     if (total.failed || total.stillRunning) process.exitCode = 1;
-    if (args.command === "poll") return;
+    if (args.command === "poll") {
+      printResumeActions(specs, lock);
+      return;
+    }
   }
   if (args.command === "pick" || args.command === "gen") {
     const total = { selected: 0, skipped: 0 };
@@ -10404,6 +10653,7 @@ async function main() {
         port: args.port,
         open: !args.noOpen,
         onProgress: log,
+        onReady: announceReviewReady,
         keys: providerSpecsForRun.map((spec) => lockKey(spec.styleId, spec.assetId)),
         specs: providerSpecsForRun
       });
@@ -10417,7 +10667,10 @@ async function main() {
   selected ${total.selected}, left in review ${total.skipped}`);
     }
     if (args.command === "gen" && total.skipped) process.exitCode = 1;
-    if (args.command === "pick") return;
+    if (args.command === "pick") {
+      printResumeActions(specs, lock);
+      return;
+    }
   }
   if (args.command === "fetch" || args.command === "restore" || args.command === "gen") {
     log(`
@@ -10427,7 +10680,8 @@ async function main() {
       const groupProvider = providerFor(providerId);
       const res = await fetchAssets(groupProvider, providerSpecsForRun, lock, args.lock, {
         onProgress: log,
-        repair: args.command === "restore"
+        repair: args.command === "restore",
+        force: args.force
       });
       total.downloaded += res.downloaded;
       total.skipped += res.skipped;
@@ -10446,10 +10700,22 @@ async function main() {
     if (args.tag) log(`  tagged ${total.tagged} object(s) upstream`);
     await saveLock(args.lock, lock);
     log(`  lockfile written: ${args.lock}`);
+    const resumeActionCount = printResumeActions(specs, lock);
     if (args.command === "gen" && specs.some((spec) => spec.quality) && !total.failed) {
-      log(`
+      const quality = (await Promise.all(
+        specs.filter((spec) => spec.quality).map((spec) => inspectQualityProfile(spec, lock))
+      )).filter((item) => item !== null);
+      const blocked = quality.filter((item) => item.state === "blocked");
+      if (blocked.length) {
+        log(
+          `
+  ${blocked.length} quality source${blocked.length === 1 ? " is" : "s are"} not ready; ` + (resumeActionCount ? "finish the resume steps above before refining." : "run `pixelkiln plan` for the blocking reason before refining.")
+        );
+      } else {
+        log(`
   Raw provider output is ready. Run \`pixelkiln refine\` to build the configured quality output.`);
-      log(`  Packaging stays blocked until each refined PNG has a current human approval.`);
+        log(`  Packaging stays blocked until each refined PNG has a current human approval.`);
+      }
     }
     return;
   }
@@ -10463,6 +10729,7 @@ main().catch((err) => {
 });
 export {
   COMMANDS,
+  announceReviewReady,
   parseArgs
 };
 //# sourceMappingURL=cli.js.map