pixelkiln 0.32.1 → 0.34.0

package/dist/cli.js

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
 
 // src/cli.ts
-import path30 from "path";
-import { existsSync as existsSync24 } from "fs";
+import path31 from "path";
+import { existsSync as existsSync25 } from "fs";
 import { readFile as readFile25 } from "fs/promises";
 
 // src/env.ts
@@ -134,10 +134,10 @@ import { createReadStream } from "fs";
 function sha256(data) {
   return createHash("sha256").update(data).digest("hex");
 }
-async function sha256File(path31) {
+async function sha256File(path32) {
   return new Promise((resolve, reject) => {
     const hash = createHash("sha256");
-    const stream = createReadStream(path31);
+    const stream = createReadStream(path32);
     stream.on("data", (chunk2) => hash.update(chunk2));
     stream.on("error", reject);
     stream.on("end", () => resolve(hash.digest("hex")));
@@ -1612,11 +1612,11 @@ var PixelLabClient = class {
    * common than the failure mode of retrying (a duplicate object), and a
    * duplicate is visible and free to delete whereas a silent gap is neither.
    */
-  async request(path31, init, attempt = 0) {
+  async request(path32, init, attempt = 0) {
     const auth = this.apiKey.startsWith("Bearer ") ? this.apiKey : `Bearer ${this.apiKey}`;
     let res;
     try {
-      res = await fetch(`${BASE}${path31}`, {
+      res = await fetch(`${BASE}${path32}`, {
         ...init,
         signal: init?.signal ?? AbortSignal.timeout(this.timeoutMs),
         headers: {
@@ -1628,24 +1628,24 @@ var PixelLabClient = class {
     } catch (err) {
       if (attempt < MAX_RETRIES) {
         await sleep(backoffMs(attempt));
-        return this.request(path31, init, attempt + 1);
+        return this.request(path32, init, attempt + 1);
       }
       throw err;
     }
     if (!res.ok && shouldRetry(res.status) && attempt < MAX_RETRIES) {
       const waitMs = retryAfterMs(res.headers.get("retry-after")) ?? backoffMs(attempt);
       await sleep(waitMs);
-      return this.request(path31, init, attempt + 1);
+      return this.request(path32, init, attempt + 1);
     }
     const text = await res.text();
     if (!res.ok) {
-      throw new PixelLabError(`${init?.method ?? "GET"} ${path31} \u2192 ${res.status}`, res.status, text);
+      throw new PixelLabError(`${init?.method ?? "GET"} ${path32} \u2192 ${res.status}`, res.status, text);
     }
     if (!text) return {};
     try {
       return JSON.parse(text);
     } catch {
-      throw new Error(`${init?.method ?? "GET"} ${path31} returned invalid JSON`);
+      throw new Error(`${init?.method ?? "GET"} ${path32} returned invalid JSON`);
     }
   }
   async balance() {
@@ -2158,11 +2158,15 @@ var AssetSchema = z2.object({
     });
   }
 });
+var DEFAULT_HISTORY_LIMIT = 5;
+var HistoryLimitSchema = z2.number().int().min(0).max(100);
 var ManifestSchema = z2.object({
   $schema: z2.string().optional(),
   name: z2.string(),
   /** Generation backend. Existing manifests remain PixelLab by default. */
   provider: z2.string().min(1).default("pixellab"),
+  /** Replaced generations kept per asset for this project; overrides PIXELKILN_HISTORY. 0 keeps none. */
+  history: HistoryLimitSchema.optional(),
   styles: z2.record(StyleSchema),
   assets: z2.record(AssetSchema)
 }).strict();
@@ -2170,9 +2174,43 @@ var ManifestInputSchema = z2.object({
   $schema: z2.string().optional(),
   name: z2.string(),
   provider: z2.string().min(1).default("pixellab"),
+  history: HistoryLimitSchema.optional(),
   styles: z2.record(StyleInputSchema),
   assets: z2.record(AssetSchema)
 }).strict();
+var LockOutputSchema = z2.object({
+  path: z2.string(),
+  sha256: z2.string(),
+  role: z2.string().optional(),
+  mediaType: MediaTypeSchema.optional()
+});
+var LockSourceSchema = z2.object({
+  url: z2.string(),
+  role: z2.string().optional(),
+  mediaType: MediaTypeSchema.optional()
+});
+var LockHistoryEntrySchema = z2.object({
+  specHash: z2.string(),
+  generator: GeneratorSchema,
+  tileFeature: z2.string().nullable().default(null),
+  prompt: z2.string(),
+  width: z2.number().int(),
+  height: z2.number().int(),
+  jobId: z2.string().nullable().default(null),
+  objectId: z2.string().nullable().default(null),
+  candidateIndex: z2.number().int().nullable().default(null),
+  sourceUrl: z2.string().nullable().default(null),
+  sourceUrls: z2.array(LockSourceSchema).default([]),
+  outputs: z2.array(LockOutputSchema).default([]),
+  providerMetadata: z2.record(z2.record(z2.unknown())).default({}),
+  submittedAt: z2.string().nullable().default(null),
+  downloadedAt: z2.string().nullable().default(null),
+  cost: z2.number().finite().nonnegative().default(0),
+  costUnit: z2.string().min(1).default("generations"),
+  provider: z2.string().default("pixellab"),
+  /** When the replacement was submitted. */
+  retiredAt: z2.string()
+});
 var LockEntrySchema = z2.object({
   styleId: z2.string(),
   assetId: z2.string(),
@@ -2262,7 +2300,9 @@ var LockEntrySchema = z2.object({
   /** Unit for `cost`. Defaults preserve pre-unit PixelLab lockfiles. */
   costUnit: z2.string().min(1).default("generations"),
   /** Which provider produced this. Absent on entries written before providers. */
-  provider: z2.string().default("pixellab")
+  provider: z2.string().default("pixellab"),
+  /** Generations this entry replaced, newest first; see LockHistoryEntrySchema. */
+  history: z2.array(LockHistoryEntrySchema).optional()
 });
 var LockSchema = z2.object({
   version: z2.literal(2),
@@ -2488,6 +2528,7 @@ var PixelLabProvider = class _PixelLabProvider {
       if (obj.status === "failed") return { status: "failed", error: "generation failed upstream" };
       return { status: "processing" };
     } catch (err) {
+      if (err instanceof PixelLabError && err.status === 423) return { status: "processing" };
       if (!(err instanceof PixelLabError) || err.status !== 404) throw err;
       const survivor = await this.client.getObject(jobId).catch(() => null);
       const url = firstUrl(survivor?.rotation_urls) ?? survivor?.preview_url ?? null;
@@ -2628,9 +2669,9 @@ var RetroDiffusionClient = class {
     }
     return balance;
   }
-  async call(path31, init = {}) {
+  async call(path32, init = {}) {
     if (!this.token) throw new Error("RD_API_KEY is not set");
-    const response = await this.request(`${this.baseUrl}${path31}`, {
+    const response = await this.request(`${this.baseUrl}${path32}`, {
       ...init,
       headers: {
         "Content-Type": "application/json",
@@ -6174,313 +6215,54 @@ function summarize(plan) {
   return counts;
 }
 
-// src/pipeline/submit.ts
-var IN_FLIGHT_POLL_MS = 5e3;
-var sleep2 = (ms) => new Promise((r) => setTimeout(r, ms));
-async function submit(provider, loaded, items, lock, lockPath, opts = {}) {
-  const limits = provider.rateLimit?.() ?? DEFAULT_RATE_LIMIT;
-  const maxInFlight = opts.maxInFlight ?? limits.maxInFlight;
-  const spacing = opts.spacingMs ?? limits.spacingMs;
-  const slotPollMs = opts.slotPollMs ?? IN_FLIGHT_POLL_MS;
-  const slotTimeoutMs = opts.slotTimeoutMs ?? 15 * 60 * 1e3;
-  const log2 = opts.onProgress ?? (() => {
-  });
-  const estimates = new Map(items.map((item) => [
-    item.key,
-    validateCostEstimate(provider.id, provider.estimate(item.spec))
-  ]));
-  const units = new Set([...estimates.values()].map((estimate) => estimate.unit));
-  if (units.size > 1) {
-    throw new Error(`Provider "${provider.id}" returned mixed cost units for one submission batch`);
-  }
-  const unit = units.values().next().value ?? "free";
-  if (opts.budget != null) {
-    const cost = [...estimates.values()].reduce((sum, estimate) => sum + estimate.amount, 0);
-    if (cost > opts.budget) {
-      throw new Error(
-        `This run would spend ${formatCost(unit, cost)} but the budget is ${formatCost(unit, opts.budget)}. Narrow it with --only/--style, or raise --budget.`
-      );
-    }
-  }
-  const styleImages = /* @__PURE__ */ new Map();
-  for (const styleId of new Set(items.map((i) => i.spec.styleId))) {
-    styleImages.set(styleId, await resolveStyleImages(loaded, styleId));
-  }
-  let submitted = 0;
-  let failed = 0;
-  let spent = 0;
-  let lastSubmitAt = 0;
-  const inFlight = /* @__PURE__ */ new Map();
-  let lastSlotError = null;
-  async function pruneInFlight() {
-    for (const [id, spec] of [...inFlight]) {
-      try {
-        const state = await provider.poll(id, spec.generator, { spec, tileFeature: spec.tileFeature });
-        if (state.status !== "processing") inFlight.delete(id);
-        lastSlotError = null;
-      } catch (err) {
-        lastSlotError = err instanceof Error ? err.message : String(err);
-      }
-    }
+// src/pipeline/history.ts
+import { existsSync as existsSync11 } from "fs";
+import path15 from "path";
+
+// src/pipeline/fetch.ts
+import { existsSync as existsSync10, readFileSync as readFileSync4 } from "fs";
+import { mkdir as mkdir3, readFile as readFile7, rename as rename3, rm as rm4, writeFile as writeFile3 } from "fs/promises";
+import path14 from "path";
+
+// src/source-url.ts
+var SENSITIVE_QUERY_KEYS = /* @__PURE__ */ new Set([
+  "access_token",
+  "apikey",
+  "api_key",
+  "auth",
+  "authorization",
+  "awsaccesskeyid",
+  "googleaccessid",
+  "key",
+  "sig"
+]);
+function isSensitiveSourceUrl(value) {
+  let parsed;
+  try {
+    parsed = new URL(value);
+  } catch {
+    return false;
   }
-  async function waitForSlot() {
-    const started = Date.now();
-    while (inFlight.size >= maxInFlight) {
-      if (Date.now() - started >= slotTimeoutMs) {
-        throw new Error(
-          `Timed out waiting for a generation slot` + (lastSlotError ? `; last poll error: ${lastSlotError}` : "")
-        );
-      }
-      await sleep2(slotPollMs);
-      await pruneInFlight();
-    }
+  if (parsed.username || parsed.password) return true;
+  for (const key of parsed.searchParams.keys()) {
+    const normalized = key.toLowerCase();
+    if (SENSITIVE_QUERY_KEYS.has(normalized) || normalized.includes("credential") || normalized.includes("signature") || normalized.includes("security-token") || normalized.includes("token")) return true;
   }
-  for (const { spec, key } of items) {
-    const estimate = estimates.get(key);
-    await waitForSlot();
-    const since = Date.now() - lastSubmitAt;
-    if (since < spacing) await sleep2(spacing - since);
-    await requireRevisionReady(spec, lock);
-    const previousEntry = lock.entries[key];
-    const resumesCheckpoint = Boolean(
-      previousEntry?.specHash === spec.specHash && previousEntry.provider === provider.id && previousEntry.generator === spec.generator && previousEntry.submissionComplete === false && previousEntry.jobId
-    );
-    const previousJobId = resumesCheckpoint ? previousEntry.jobId : void 0;
-    const previousMetadata = resumesCheckpoint ? previousEntry.providerMetadata[provider.id] : void 0;
-    const supersededOutputs = previousEntry?.outputs.length ? previousEntry.outputs : previousEntry?.supersededOutputs ?? [];
-    upsert(lock, key, {
-      styleId: spec.styleId,
-      assetId: spec.assetId,
-      specHash: spec.specHash,
-      generator: spec.generator,
-      tileFeature: spec.tileFeature ?? null,
-      prompt: spec.prompt,
-      width: spec.width,
-      height: spec.height,
-      revision: spec.revision ? {
-        mode: spec.revision.mode,
-        sourceAssetId: spec.revision.sourceAssetId,
-        sourceSha256: spec.revision.sourceSha256,
-        ...spec.revision.maskSha256 ? { maskSha256: spec.revision.maskSha256 } : {},
-        ...spec.revision.strength == null ? {} : { strength: spec.revision.strength }
-      } : null,
-      status: "pending",
-      jobId: previousJobId ?? null,
-      ...previousJobId ? { submissionComplete: false } : { submissionComplete: void 0 },
-      objectId: null,
-      reviewObjectId: null,
-      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: resumesCheckpoint ? previousEntry.providerMetadata : {},
-      sourceUrl: null,
-      sourceUrls: [],
-      submittedAt: resumesCheckpoint ? previousEntry.submittedAt : (/* @__PURE__ */ new Date()).toISOString(),
-      cost: estimate.amount,
-      costUnit: estimate.unit,
-      // Persist routing before the request starts. If the process stops while
-      // the provider is accepting work, a resumed run must not fall back to
-      // PixelLab (the legacy lock default) for another provider's entry.
-      provider: provider.id,
-      downloadedAt: null
-    });
-    await saveLock(lockPath, lock);
-    lastSubmitAt = Date.now();
-    try {
-      const refs = styleImages.get(spec.styleId) ?? [];
-      const { jobId, metadata } = await provider.submit(spec, refs, {
-        ...previousJobId ? { previousJobId } : {},
-        ...previousMetadata ? { previousMetadata } : {},
-        checkpoint: async (checkpoint) => {
-          if (!checkpoint.jobId) throw new Error("Provider checkpoint returned an empty job id");
-          const entry = lock.entries[key];
-          upsert(lock, key, {
-            jobId: checkpoint.jobId,
-            submissionComplete: checkpoint.complete,
-            reviewObjectId: checkpoint.complete && (spec.generator === "frames" || estimate.candidates > 1 && !spec.tileFeature) ? checkpoint.jobId : null,
-            status: checkpoint.complete ? "processing" : "pending",
-            error: null,
-            providerMetadata: checkpoint.metadata ? {
-              ...entry.providerMetadata,
-              [provider.id]: {
-                ...entry.providerMetadata[provider.id],
-                ...checkpoint.metadata
-              }
-            } : entry.providerMetadata
-          });
-          await saveLock(lockPath, lock);
-        }
-      });
-      upsert(lock, key, {
-        jobId,
-        submissionComplete: true,
-        // A multi-candidate generator routes through review; record the parent
-        // so `pick` knows where to look.
-        reviewObjectId: spec.generator === "frames" || estimate.candidates > 1 && !spec.tileFeature ? jobId : null,
-        status: "processing",
-        providerMetadata: metadata ? { ...lock.entries[key].providerMetadata, [provider.id]: metadata } : lock.entries[key].providerMetadata
-      });
-      inFlight.set(jobId, spec);
-      submitted++;
-      spent += estimate.amount;
-      log2(
-        `  ${key} \u2192 ${jobId}  (${spec.width}x${spec.height}` + (estimate.candidates > 1 ? `, ${estimate.candidates} ${spec.tileFeature ? "outputs" : "candidates"}` : "") + `, ${estimate.amount})`
-      );
-    } catch (err) {
-      const message6 = err instanceof Error ? err.message : String(err);
-      const entry = lock.entries[key];
-      if (entry.jobId && entry.submissionComplete === true) {
-        upsert(lock, key, { status: "processing", error: null });
-        inFlight.set(entry.jobId, spec);
-        submitted++;
-        spent += estimate.amount;
-        log2(`  ${key} \u2192 ${entry.jobId}  (recovered from completed checkpoint)`);
-      } else {
-        failed++;
-        upsert(lock, key, {
-          status: "failed",
-          error: message6,
-          cost: entry.jobId ? estimate.amount : 0
-        });
-        log2(`  FAILED ${key}: ${message6}`);
-      }
-    }
-    await saveLock(lockPath, lock);
+  return false;
+}
+function shouldPersistSourceUrl(value) {
+  let parsed;
+  try {
+    parsed = new URL(value);
+  } catch {
+    return true;
   }
-  return { submitted, failed, spent, unit };
+  if (parsed.protocol === "data:" || parsed.protocol === "file:") return false;
+  return !isSensitiveSourceUrl(value);
 }
 
-// src/pipeline/poll.ts
-var sleep3 = (ms) => new Promise((r) => setTimeout(r, ms));
-async function poll(provider, lock, lockPath, opts = {}) {
-  const interval = opts.intervalMs ?? 5e3;
-  const timeout = opts.timeoutMs ?? 15 * 60 * 1e3;
-  const log2 = opts.onProgress ?? (() => {
-  });
-  const started = Date.now();
-  const specByKey = new Map((opts.specs ?? []).map((s) => [lockKey(s.styleId, s.assetId), s]));
-  const selectedKeys = opts.specs ? new Set(specByKey.keys()) : null;
-  const result = { review: 0, completed: 0, failed: 0, stillRunning: 0 };
-  const incompleteSubmissions = Object.entries(lock.entries).filter(
-    ([key, entry]) => entry.provider === provider.id && (!selectedKeys || selectedKeys.has(key)) && entry.jobId && entry.submissionComplete === false && (entry.status === "pending" || entry.status === "processing")
-  );
-  for (const [key] of incompleteSubmissions) {
-    log2(`  incomplete submission ${key}; rerun \`pixelkiln submit\` to resume`);
-  }
-  result.stillRunning = incompleteSubmissions.length;
-  const pending = () => Object.entries(lock.entries).filter(
-    ([key, e]) => e.provider === provider.id && (!selectedKeys || selectedKeys.has(key)) && e.jobId && e.submissionComplete !== false && (e.status === "pending" || e.status === "processing")
-  );
-  while (pending().length > 0) {
-    if (Date.now() - started > timeout) {
-      result.stillRunning += pending().length;
-      log2(`  timed out with ${result.stillRunning} job(s) still running \u2014 re-run \`poll\` to resume`);
-      break;
-    }
-    for (const [key, entry] of pending()) {
-      try {
-        const currentSpec = specByKey.get(key);
-        const state = await provider.poll(entry.jobId, entry.generator, {
-          tileFeature: entry.tileFeature ?? currentSpec?.tileFeature,
-          spec: currentSpec
-        });
-        if (state.status === "review" || state.status === "review-set") {
-          upsert(lock, key, {
-            status: "review",
-            reviewObjectId: entry.jobId,
-            providerMetadata: state.metadata ? {
-              ...entry.providerMetadata,
-              [provider.id]: {
-                ...entry.providerMetadata[provider.id],
-                ...state.metadata
-              }
-            } : entry.providerMetadata
-          });
-          result.review++;
-          log2(
-            state.status === "review-set" ? `  review  ${key} (${state.frameUrls.length} ordered frames)` : `  review  ${key} (${state.candidateUrls.length} candidates)`
-          );
-        } else if (state.status === "ready") {
-          const sourceUrls = state.sources?.length ? state.sources : state.sourceUrl ? [{ url: state.sourceUrl }] : [];
-          upsert(lock, key, {
-            status: "selected",
-            objectId: state.objectId,
-            sourceUrl: sourceUrls[0]?.url ?? null,
-            sourceUrls,
-            providerMetadata: state.metadata ? {
-              ...entry.providerMetadata,
-              [provider.id]: {
-                ...entry.providerMetadata[provider.id],
-                ...state.metadata
-              }
-            } : entry.providerMetadata,
-            error: null
-          });
-          result.completed++;
-          log2(`  ready   ${key}`);
-        } else if (state.status === "failed") {
-          upsert(lock, key, { status: "failed", error: state.error });
-          result.failed++;
-          log2(`  FAILED  ${key}: ${state.error}`);
-        }
-      } catch (err) {
-        log2(`  error polling ${key}: ${err instanceof Error ? err.message : String(err)}`);
-      }
-    }
-    await saveLock(lockPath, lock);
-    if (pending().length > 0) await sleep3(interval);
-  }
-  await saveLock(lockPath, lock);
-  return result;
-}
-
-// src/pipeline/fetch.ts
-import { existsSync as existsSync10, readFileSync as readFileSync4 } from "fs";
-import { mkdir as mkdir3, readFile as readFile7, rename as rename3, rm as rm4, writeFile as writeFile3 } from "fs/promises";
-import path14 from "path";
-
-// src/source-url.ts
-var SENSITIVE_QUERY_KEYS = /* @__PURE__ */ new Set([
-  "access_token",
-  "apikey",
-  "api_key",
-  "auth",
-  "authorization",
-  "awsaccesskeyid",
-  "googleaccessid",
-  "key",
-  "sig"
-]);
-function isSensitiveSourceUrl(value) {
-  let parsed;
-  try {
-    parsed = new URL(value);
-  } catch {
-    return false;
-  }
-  if (parsed.username || parsed.password) return true;
-  for (const key of parsed.searchParams.keys()) {
-    const normalized = key.toLowerCase();
-    if (SENSITIVE_QUERY_KEYS.has(normalized) || normalized.includes("credential") || normalized.includes("signature") || normalized.includes("security-token") || normalized.includes("token")) return true;
-  }
-  return false;
-}
-function shouldPersistSourceUrl(value) {
-  let parsed;
-  try {
-    parsed = new URL(value);
-  } catch {
-    return true;
-  }
-  if (parsed.protocol === "data:" || parsed.protocol === "file:") return false;
-  return !isSensitiveSourceUrl(value);
-}
-
-// src/pipeline/fetch.ts
-async function fetchAssets(provider, specs, lock, lockPath, opts = {}) {
+// src/pipeline/fetch.ts
+async function fetchAssets(provider, specs, lock, lockPath, opts = {}) {
   const log2 = opts.onProgress ?? (() => {
   });
   const result = { downloaded: 0, skipped: 0, failed: 0, ...opts.refresh ? { unchanged: 0 } : {} };
@@ -6498,7 +6280,9 @@ async function fetchAssets(provider, specs, lock, lockPath, opts = {}) {
     return e.outputs.some((output) => {
       const file = resolveOutputPath(output.path, spec.root);
       if (!existsSync10(file)) return true;
-      return Boolean(opts.force) && sha256(readFileSync4(file)) !== output.sha256;
+      const current = sha256(readFileSync4(file));
+      if (current === output.sha256) return false;
+      return Boolean(opts.force) || (e.supersededOutputs ?? []).some((old) => old.sha256 === current);
     });
   });
   const concurrency = Math.min(Math.max(1, opts.concurrency ?? 8), Math.max(1, pending.length));
@@ -6568,7 +6352,7 @@ async function fetchAssets(provider, specs, lock, lockPath, opts = {}) {
                 (output, oldIndex, all) => currentOutputPath(output, spec, oldIndex, all.length) === target
               );
               if (!opts.force) {
-                if (!recorded && superseded && currentHash === superseded.sha256) {
+                if (superseded && currentHash === superseded.sha256) {
                 } else if (recorded || superseded) {
                   throw new Error(
                     `refusing to overwrite modified output ${target}; pass --force to replace it`
@@ -6642,79 +6426,476 @@ async function fetchAssets(provider, specs, lock, lockPath, opts = {}) {
       } catch (err) {
         const message6 = err instanceof Error ? err.message : String(err);
         upsert(lock, key, {
-          status: "download-failed",
-          outputs: mergeOutputs(entry.outputs, outputs),
-          error: `download failed: ${message6}`
+          status: "download-failed",
+          outputs: mergeOutputs(entry.outputs, outputs),
+          error: `download failed: ${message6}`
+        });
+        result.failed++;
+        log2(`  FAILED  ${key}: ${message6}`);
+      }
+      await saveLock(lockPath, lock);
+    }
+  }
+  await Promise.all(Array.from({ length: concurrency }, worker));
+  await saveLock(lockPath, lock);
+  return result;
+}
+async function readCachedMedia(cacheDir, hash, mediaType) {
+  const file = path14.join(cacheDir, cacheFileName(hash, mediaType));
+  if (!existsSync10(file)) return null;
+  try {
+    const buf = await readFile7(file);
+    if (sha256(buf) !== hash) return null;
+    validateMedia(buf, mediaType);
+    return buf;
+  } catch {
+    return null;
+  }
+}
+async function cacheMedia(cacheDir, buf, mediaType, knownHash) {
+  const hash = knownHash ?? sha256(buf);
+  validateMedia(buf, mediaType);
+  const file = path14.join(cacheDir, cacheFileName(hash, mediaType));
+  if (await readCachedMedia(cacheDir, hash, mediaType)) return;
+  await mkdir3(cacheDir, { recursive: true });
+  const tmp = `${file}.${process.pid}.${Math.random().toString(36).slice(2)}.tmp`;
+  await writeFile3(tmp, buf);
+  try {
+    await rename3(tmp, file);
+  } catch (err) {
+    if (!existsSync10(file)) throw err;
+  } finally {
+    await rm4(tmp, { force: true });
+  }
+}
+function mergeOutputs(previous, current) {
+  const merged = /* @__PURE__ */ new Map();
+  for (const output of [...previous, ...current]) {
+    merged.set(output.role ? `role:${output.role}` : `path:${output.path}`, output);
+  }
+  return [...merged.values()];
+}
+async function pushTags(provider, specs, lock, opts = {}) {
+  const log2 = opts.onProgress ?? (() => {
+  });
+  const specByKey = new Map(specs.map((s) => [lockKey(s.styleId, s.assetId), s]));
+  let tagged = 0;
+  for (const [key, entry] of Object.entries(lock.entries)) {
+    const spec = specByKey.get(key);
+    if (!spec || entry.provider !== provider.id || !entry.objectId) continue;
+    if (entry.generator === "pixflux") continue;
+    if (!provider.setTags) return tagged;
+    try {
+      await provider.setTags(entry.objectId, spec.tags);
+      tagged++;
+    } catch (err) {
+      log2(`  tag failed ${key}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+  }
+  return tagged;
+}
+
+// src/pipeline/history.ts
+var HISTORY_ENV = "PIXELKILN_HISTORY";
+function historyLimit(manifest, env = process.env) {
+  if (manifest?.history !== void 0) return manifest.history;
+  const raw = env[HISTORY_ENV]?.trim();
+  if (raw === void 0 || raw === "") return DEFAULT_HISTORY_LIMIT;
+  const value = Number(raw);
+  if (!Number.isInteger(value) || value < 0 || value > 100) {
+    throw new Error(`${HISTORY_ENV} must be a whole number from 0 to 100, got "${raw}"`);
+  }
+  return value;
+}
+function retireGeneration(entry, retiredAt) {
+  return {
+    specHash: entry.specHash,
+    generator: entry.generator,
+    tileFeature: entry.tileFeature,
+    prompt: entry.prompt,
+    width: entry.width,
+    height: entry.height,
+    jobId: entry.jobId,
+    objectId: entry.objectId,
+    candidateIndex: entry.candidateIndex,
+    sourceUrl: entry.sourceUrl,
+    sourceUrls: entry.sourceUrls,
+    outputs: entry.outputs,
+    providerMetadata: entry.providerMetadata,
+    submittedAt: entry.submittedAt,
+    downloadedAt: entry.downloadedAt,
+    cost: entry.cost,
+    costUnit: entry.costUnit,
+    provider: entry.provider,
+    retiredAt
+  };
+}
+function historyAfterReplacing(previous, limit, retiredAt) {
+  if (!previous) return void 0;
+  const kept = previous.history ?? [];
+  const outgoing = previous.status === "downloaded" && previous.outputs.length ? [retireGeneration(previous, retiredAt)] : [];
+  const history = [...outgoing, ...kept].slice(0, limit);
+  return history.length ? history : void 0;
+}
+function referencedHashes(lock) {
+  const hashes = /* @__PURE__ */ new Set();
+  for (const entry of Object.values(lock.entries)) {
+    for (const output of entry.outputs) hashes.add(output.sha256);
+    for (const generation of entry.history ?? []) for (const output of generation.outputs) hashes.add(output.sha256);
+  }
+  return hashes;
+}
+function pickHistory(entry, selector) {
+  const history = entry.history ?? [];
+  if (!history.length) throw new Error(`${entry.styleId}/${entry.assetId} has no previous generations recorded`);
+  if (typeof selector === "number" || /^\d{1,3}$/.test(selector)) {
+    const index = Number(selector);
+    const generation = history[index - 1];
+    if (!generation) throw new Error(`${entry.styleId}/${entry.assetId} keeps ${history.length} previous generation(s); there is no #${index}`);
+    return { index, generation };
+  }
+  const prefix = selector.toLowerCase();
+  const matches = history.map((generation, i) => ({ index: i + 1, generation })).filter(({ generation }) => generation.outputs.some((output) => output.sha256.startsWith(prefix)));
+  if (matches.length !== 1) {
+    throw new Error(
+      matches.length ? `"${selector}" matches ${matches.length} previous generations of ${entry.styleId}/${entry.assetId}; give more of the hash` : `no previous generation of ${entry.styleId}/${entry.assetId} has an output hash starting with "${selector}"`
+    );
+  }
+  return matches[0];
+}
+async function revertGeneration(provider, spec, lock, lockPath, opts) {
+  const key = lockKey(spec.styleId, spec.assetId);
+  const entry = lock.entries[key];
+  if (!entry) throw new Error(`${key} is not in the lockfile`);
+  if (entry.status !== "downloaded") {
+    throw new Error(`${key} is ${entry.status}; finish or fetch the current generation before restoring an older one`);
+  }
+  const { index, generation } = pickHistory(entry, opts.generation);
+  if (generation.provider !== provider.id) {
+    throw new Error(`${key}'s previous generation #${index} came from ${generation.provider}, not ${provider.id}`);
+  }
+  for (let i = 0; i < entry.outputs.length; i++) {
+    const file = currentEntryOutputPath(entry, spec, i);
+    if (!existsSync11(file)) continue;
+    if (await sha256File(file) !== entry.outputs[i].sha256 && !opts.force) {
+      throw new Error(
+        `${path15.relative(process.cwd(), file)} was changed after download; keep it with pixelkiln edit, or pass --force to replace it`
+      );
+    }
+  }
+  const now = (/* @__PURE__ */ new Date()).toISOString();
+  const remaining = (entry.history ?? []).filter((_, i) => i !== index - 1);
+  const history = [retireGeneration(entry, now), ...remaining];
+  upsert(lock, key, {
+    specHash: generation.specHash,
+    generator: generation.generator,
+    tileFeature: generation.tileFeature,
+    prompt: generation.prompt,
+    width: generation.width,
+    height: generation.height,
+    jobId: generation.jobId,
+    objectId: generation.objectId,
+    candidateIndex: generation.candidateIndex,
+    reviewObjectId: null,
+    status: "downloaded",
+    error: null,
+    sourceUrl: generation.sourceUrl,
+    sourceUrls: generation.sourceUrls,
+    outputs: generation.outputs,
+    // The files on disk are the outgoing generation's; that record authorizes
+    // replacing them without --force, exactly as after a regeneration.
+    supersededOutputs: entry.outputs,
+    providerMetadata: generation.providerMetadata,
+    submittedAt: generation.submittedAt,
+    downloadedAt: generation.downloadedAt,
+    cost: generation.cost,
+    costUnit: generation.costUnit,
+    provider: generation.provider,
+    history
+  });
+  await saveLock(lockPath, lock);
+  const result = await fetchAssets(provider, [spec], lock, lockPath, {
+    onProgress: opts.onProgress,
+    repair: true,
+    force: opts.force,
+    cacheDir: opts.cacheDir
+  });
+  if (result.failed) {
+    throw new Error(`the previous generation's bytes could not be written back; run pixelkiln restore --only ${spec.assetId} --style ${spec.styleId} once the provider is reachable`);
+  }
+  return { restored: generation, index, downloaded: result.downloaded };
+}
+
+// src/pipeline/submit.ts
+var IN_FLIGHT_POLL_MS = 5e3;
+var sleep2 = (ms) => new Promise((r) => setTimeout(r, ms));
+async function submit(provider, loaded, items, lock, lockPath, opts = {}) {
+  const limits = provider.rateLimit?.() ?? DEFAULT_RATE_LIMIT;
+  const maxInFlight = opts.maxInFlight ?? limits.maxInFlight;
+  const spacing = opts.spacingMs ?? limits.spacingMs;
+  const slotPollMs = opts.slotPollMs ?? IN_FLIGHT_POLL_MS;
+  const slotTimeoutMs = opts.slotTimeoutMs ?? 15 * 60 * 1e3;
+  const log2 = opts.onProgress ?? (() => {
+  });
+  const estimates = new Map(items.map((item) => [
+    item.key,
+    validateCostEstimate(provider.id, provider.estimate(item.spec))
+  ]));
+  const units = new Set([...estimates.values()].map((estimate) => estimate.unit));
+  if (units.size > 1) {
+    throw new Error(`Provider "${provider.id}" returned mixed cost units for one submission batch`);
+  }
+  const unit = units.values().next().value ?? "free";
+  if (opts.budget != null) {
+    const cost = [...estimates.values()].reduce((sum, estimate) => sum + estimate.amount, 0);
+    if (cost > opts.budget) {
+      throw new Error(
+        `This run would spend ${formatCost(unit, cost)} but the budget is ${formatCost(unit, opts.budget)}. Narrow it with --only/--style, or raise --budget.`
+      );
+    }
+  }
+  const styleImages = /* @__PURE__ */ new Map();
+  for (const styleId of new Set(items.map((i) => i.spec.styleId))) {
+    styleImages.set(styleId, await resolveStyleImages(loaded, styleId));
+  }
+  let submitted = 0;
+  let failed = 0;
+  let spent = 0;
+  let lastSubmitAt = 0;
+  const inFlight = /* @__PURE__ */ new Map();
+  let lastSlotError = null;
+  async function pruneInFlight() {
+    for (const [id, spec] of [...inFlight]) {
+      try {
+        const state = await provider.poll(id, spec.generator, { spec, tileFeature: spec.tileFeature });
+        if (state.status !== "processing") inFlight.delete(id);
+        lastSlotError = null;
+      } catch (err) {
+        lastSlotError = err instanceof Error ? err.message : String(err);
+      }
+    }
+  }
+  async function waitForSlot() {
+    const started = Date.now();
+    while (inFlight.size >= maxInFlight) {
+      if (Date.now() - started >= slotTimeoutMs) {
+        throw new Error(
+          `Timed out waiting for a generation slot` + (lastSlotError ? `; last poll error: ${lastSlotError}` : "")
+        );
+      }
+      await sleep2(slotPollMs);
+      await pruneInFlight();
+    }
+  }
+  for (const { spec, key } of items) {
+    const estimate = estimates.get(key);
+    await waitForSlot();
+    const since = Date.now() - lastSubmitAt;
+    if (since < spacing) await sleep2(spacing - since);
+    await requireRevisionReady(spec, lock);
+    const previousEntry = lock.entries[key];
+    const resumesCheckpoint = Boolean(
+      previousEntry?.specHash === spec.specHash && previousEntry.provider === provider.id && previousEntry.generator === spec.generator && previousEntry.submissionComplete === false && previousEntry.jobId
+    );
+    const previousJobId = resumesCheckpoint ? previousEntry.jobId : void 0;
+    const previousMetadata = resumesCheckpoint ? previousEntry.providerMetadata[provider.id] : void 0;
+    const supersededOutputs = previousEntry?.outputs.length ? previousEntry.outputs : previousEntry?.supersededOutputs ?? [];
+    const submittedAt = resumesCheckpoint ? previousEntry.submittedAt : (/* @__PURE__ */ new Date()).toISOString();
+    const history = historyAfterReplacing(previousEntry, historyLimit(loaded.manifest), submittedAt ?? (/* @__PURE__ */ new Date()).toISOString());
+    upsert(lock, key, {
+      styleId: spec.styleId,
+      assetId: spec.assetId,
+      specHash: spec.specHash,
+      generator: spec.generator,
+      tileFeature: spec.tileFeature ?? null,
+      prompt: spec.prompt,
+      width: spec.width,
+      height: spec.height,
+      revision: spec.revision ? {
+        mode: spec.revision.mode,
+        sourceAssetId: spec.revision.sourceAssetId,
+        sourceSha256: spec.revision.sourceSha256,
+        ...spec.revision.maskSha256 ? { maskSha256: spec.revision.maskSha256 } : {},
+        ...spec.revision.strength == null ? {} : { strength: spec.revision.strength }
+      } : null,
+      status: "pending",
+      jobId: previousJobId ?? null,
+      ...previousJobId ? { submissionComplete: false } : { submissionComplete: void 0 },
+      objectId: null,
+      reviewObjectId: null,
+      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: resumesCheckpoint ? previousEntry.providerMetadata : {},
+      sourceUrl: null,
+      sourceUrls: [],
+      submittedAt,
+      history,
+      cost: estimate.amount,
+      costUnit: estimate.unit,
+      // Persist routing before the request starts. If the process stops while
+      // the provider is accepting work, a resumed run must not fall back to
+      // PixelLab (the legacy lock default) for another provider's entry.
+      provider: provider.id,
+      downloadedAt: null
+    });
+    await saveLock(lockPath, lock);
+    lastSubmitAt = Date.now();
+    try {
+      const refs = styleImages.get(spec.styleId) ?? [];
+      const { jobId, metadata } = await provider.submit(spec, refs, {
+        ...previousJobId ? { previousJobId } : {},
+        ...previousMetadata ? { previousMetadata } : {},
+        checkpoint: async (checkpoint) => {
+          if (!checkpoint.jobId) throw new Error("Provider checkpoint returned an empty job id");
+          const entry = lock.entries[key];
+          upsert(lock, key, {
+            jobId: checkpoint.jobId,
+            submissionComplete: checkpoint.complete,
+            reviewObjectId: checkpoint.complete && (spec.generator === "frames" || estimate.candidates > 1 && !spec.tileFeature) ? checkpoint.jobId : null,
+            status: checkpoint.complete ? "processing" : "pending",
+            error: null,
+            providerMetadata: checkpoint.metadata ? {
+              ...entry.providerMetadata,
+              [provider.id]: {
+                ...entry.providerMetadata[provider.id],
+                ...checkpoint.metadata
+              }
+            } : entry.providerMetadata
+          });
+          await saveLock(lockPath, lock);
+        }
+      });
+      upsert(lock, key, {
+        jobId,
+        submissionComplete: true,
+        // A multi-candidate generator routes through review; record the parent
+        // so `pick` knows where to look.
+        reviewObjectId: spec.generator === "frames" || estimate.candidates > 1 && !spec.tileFeature ? jobId : null,
+        status: "processing",
+        providerMetadata: metadata ? { ...lock.entries[key].providerMetadata, [provider.id]: metadata } : lock.entries[key].providerMetadata
+      });
+      inFlight.set(jobId, spec);
+      submitted++;
+      spent += estimate.amount;
+      log2(
+        `  ${key} \u2192 ${jobId}  (${spec.width}x${spec.height}` + (estimate.candidates > 1 ? `, ${estimate.candidates} ${spec.tileFeature ? "outputs" : "candidates"}` : "") + `, ${estimate.amount})`
+      );
+    } catch (err) {
+      const message6 = err instanceof Error ? err.message : String(err);
+      const entry = lock.entries[key];
+      if (entry.jobId && entry.submissionComplete === true) {
+        upsert(lock, key, { status: "processing", error: null });
+        inFlight.set(entry.jobId, spec);
+        submitted++;
+        spent += estimate.amount;
+        log2(`  ${key} \u2192 ${entry.jobId}  (recovered from completed checkpoint)`);
+      } else {
+        failed++;
+        upsert(lock, key, {
+          status: "failed",
+          error: message6,
+          cost: entry.jobId ? estimate.amount : 0
         });
-        result.failed++;
-        log2(`  FAILED  ${key}: ${message6}`);
+        log2(`  FAILED ${key}: ${message6}`);
       }
-      await saveLock(lockPath, lock);
     }
+    await saveLock(lockPath, lock);
   }
-  await Promise.all(Array.from({ length: concurrency }, worker));
-  await saveLock(lockPath, lock);
-  return result;
-}
-async function readCachedMedia(cacheDir, hash, mediaType) {
-  const file = path14.join(cacheDir, cacheFileName(hash, mediaType));
-  if (!existsSync10(file)) return null;
-  try {
-    const buf = await readFile7(file);
-    if (sha256(buf) !== hash) return null;
-    validateMedia(buf, mediaType);
-    return buf;
-  } catch {
-    return null;
-  }
-}
-async function cacheMedia(cacheDir, buf, mediaType, knownHash) {
-  const hash = knownHash ?? sha256(buf);
-  validateMedia(buf, mediaType);
-  const file = path14.join(cacheDir, cacheFileName(hash, mediaType));
-  if (await readCachedMedia(cacheDir, hash, mediaType)) return;
-  await mkdir3(cacheDir, { recursive: true });
-  const tmp = `${file}.${process.pid}.${Math.random().toString(36).slice(2)}.tmp`;
-  await writeFile3(tmp, buf);
-  try {
-    await rename3(tmp, file);
-  } catch (err) {
-    if (!existsSync10(file)) throw err;
-  } finally {
-    await rm4(tmp, { force: true });
-  }
-}
-function mergeOutputs(previous, current) {
-  const merged = /* @__PURE__ */ new Map();
-  for (const output of [...previous, ...current]) {
-    merged.set(output.role ? `role:${output.role}` : `path:${output.path}`, output);
-  }
-  return [...merged.values()];
+  return { submitted, failed, spent, unit };
 }
-async function pushTags(provider, specs, lock, opts = {}) {
+
+// src/pipeline/poll.ts
+var sleep3 = (ms) => new Promise((r) => setTimeout(r, ms));
+async function poll(provider, lock, lockPath, opts = {}) {
+  const interval = opts.intervalMs ?? 5e3;
+  const timeout = opts.timeoutMs ?? 15 * 60 * 1e3;
   const log2 = opts.onProgress ?? (() => {
   });
-  const specByKey = new Map(specs.map((s) => [lockKey(s.styleId, s.assetId), s]));
-  let tagged = 0;
-  for (const [key, entry] of Object.entries(lock.entries)) {
-    const spec = specByKey.get(key);
-    if (!spec || entry.provider !== provider.id || !entry.objectId) continue;
-    if (entry.generator === "pixflux") continue;
-    if (!provider.setTags) return tagged;
-    try {
-      await provider.setTags(entry.objectId, spec.tags);
-      tagged++;
-    } catch (err) {
-      log2(`  tag failed ${key}: ${err instanceof Error ? err.message : String(err)}`);
+  const started = Date.now();
+  const specByKey = new Map((opts.specs ?? []).map((s) => [lockKey(s.styleId, s.assetId), s]));
+  const selectedKeys = opts.specs ? new Set(specByKey.keys()) : null;
+  const result = { review: 0, completed: 0, failed: 0, stillRunning: 0 };
+  const incompleteSubmissions = Object.entries(lock.entries).filter(
+    ([key, entry]) => entry.provider === provider.id && (!selectedKeys || selectedKeys.has(key)) && entry.jobId && entry.submissionComplete === false && (entry.status === "pending" || entry.status === "processing")
+  );
+  for (const [key] of incompleteSubmissions) {
+    log2(`  incomplete submission ${key}; rerun \`pixelkiln submit\` to resume`);
+  }
+  result.stillRunning = incompleteSubmissions.length;
+  const pending = () => Object.entries(lock.entries).filter(
+    ([key, e]) => e.provider === provider.id && (!selectedKeys || selectedKeys.has(key)) && e.jobId && e.submissionComplete !== false && (e.status === "pending" || e.status === "processing")
+  );
+  while (pending().length > 0) {
+    if (Date.now() - started > timeout) {
+      result.stillRunning += pending().length;
+      log2(`  timed out with ${result.stillRunning} job(s) still running \u2014 re-run \`poll\` to resume`);
+      break;
+    }
+    for (const [key, entry] of pending()) {
+      try {
+        const currentSpec = specByKey.get(key);
+        const state = await provider.poll(entry.jobId, entry.generator, {
+          tileFeature: entry.tileFeature ?? currentSpec?.tileFeature,
+          spec: currentSpec
+        });
+        if (state.status === "review" || state.status === "review-set") {
+          upsert(lock, key, {
+            status: "review",
+            reviewObjectId: entry.jobId,
+            providerMetadata: state.metadata ? {
+              ...entry.providerMetadata,
+              [provider.id]: {
+                ...entry.providerMetadata[provider.id],
+                ...state.metadata
+              }
+            } : entry.providerMetadata
+          });
+          result.review++;
+          log2(
+            state.status === "review-set" ? `  review  ${key} (${state.frameUrls.length} ordered frames)` : `  review  ${key} (${state.candidateUrls.length} candidates)`
+          );
+        } else if (state.status === "ready") {
+          const sourceUrls = state.sources?.length ? state.sources : state.sourceUrl ? [{ url: state.sourceUrl }] : [];
+          upsert(lock, key, {
+            status: "selected",
+            objectId: state.objectId,
+            sourceUrl: sourceUrls[0]?.url ?? null,
+            sourceUrls,
+            providerMetadata: state.metadata ? {
+              ...entry.providerMetadata,
+              [provider.id]: {
+                ...entry.providerMetadata[provider.id],
+                ...state.metadata
+              }
+            } : entry.providerMetadata,
+            error: null
+          });
+          result.completed++;
+          log2(`  ready   ${key}`);
+        } else if (state.status === "failed") {
+          upsert(lock, key, { status: "failed", error: state.error });
+          result.failed++;
+          log2(`  FAILED  ${key}: ${state.error}`);
+        }
+      } catch (err) {
+        log2(`  error polling ${key}: ${err instanceof Error ? err.message : String(err)}`);
+      }
     }
+    await saveLock(lockPath, lock);
+    if (pending().length > 0) await sleep3(interval);
   }
-  return tagged;
+  await saveLock(lockPath, lock);
+  return result;
 }
 
 // src/pipeline/doctor.ts
-import { constants, existsSync as existsSync11 } from "fs";
+import { constants, existsSync as existsSync12 } from "fs";
 import { access, stat as stat2 } from "fs/promises";
-import path15 from "path";
+import path16 from "path";
 async function doctor(loaded, specs, lock, lockPath, opts = {}) {
   const checks = [];
   const add = (id, level, message6) => checks.push({ id, level, message: message6 });
@@ -6725,8 +6906,8 @@ async function doctor(loaded, specs, lock, lockPath, opts = {}) {
   );
   add("lock", "ok", `${Object.keys(lock.entries).length} valid v2 lock entr(ies)`);
   const dirs = [...new Set(specs.flatMap((spec) => [
-    path15.dirname(spec.outFile),
-    ...spec.quality ? [path15.dirname(spec.quality.outFile)] : []
+    path16.dirname(spec.outFile),
+    ...spec.quality ? [path16.dirname(spec.quality.outFile)] : []
   ]))];
   const unwritable = [];
   for (const dir of dirs) {
@@ -6749,7 +6930,7 @@ async function doctor(loaded, specs, lock, lockPath, opts = {}) {
     for (let index = 0; index < entry.outputs.length; index++) {
       const output = entry.outputs[index];
       const spec = specByKey.get(key);
-      const absolute = spec ? currentEntryOutputPath(entry, spec, index) : resolveOutputPath(output.path, path15.dirname(lockPath));
+      const absolute = spec ? currentEntryOutputPath(entry, spec, index) : resolveOutputPath(output.path, path16.dirname(lockPath));
       const owner = outputOwners.get(absolute);
       if (owner && owner !== key) duplicateOutputs.push(`${output.path} (${owner}, ${key})`);
       outputOwners.set(absolute, key);
@@ -6764,7 +6945,7 @@ async function doctor(loaded, specs, lock, lockPath, opts = {}) {
   } else {
     add("lock-outputs", "ok", `${outputOwners.size} recorded output path(s) are uniquely owned`);
   }
-  const cacheDir = path15.join(path15.dirname(lockPath), ".pixelkiln", "cache");
+  const cacheDir = path16.join(path16.dirname(lockPath), ".pixelkiln", "cache");
   const stranded = [];
   const invalidState = [];
   const staleMapUrls = [];
@@ -6780,11 +6961,11 @@ async function doctor(loaded, specs, lock, lockPath, opts = {}) {
     const hasSource = Boolean(entry.sourceUrl || entry.sourceUrls?.length);
     let hasCache = false;
     for (const output of entry.outputs) {
-      const cached = path15.join(
+      const cached = path16.join(
         cacheDir,
         cacheFileName(output.sha256, output.mediaType ?? MediaType.PNG)
       );
-      if (existsSync11(cached) && await sha256File(cached) === output.sha256) {
+      if (existsSync12(cached) && await sha256File(cached) === output.sha256) {
         hasCache = true;
         break;
       }
@@ -6880,20 +7061,20 @@ async function nearestExistingDirectory(start) {
       if ((await stat2(current)).isDirectory()) return current;
     } catch {
     }
-    const parent = path15.dirname(current);
+    const parent = path16.dirname(current);
     if (parent === current) return current;
     current = parent;
   }
 }
 
 // src/pipeline/adopt.ts
-import { existsSync as existsSync13 } from "fs";
+import { existsSync as existsSync14 } from "fs";
 import { readFile as readFile9, writeFile as writeFile5 } from "fs/promises";
-import path16 from "path";
+import path17 from "path";
 
 // src/cache.ts
 import { mkdir as mkdir4, readFile as readFile8, rename as rename4, rm as rm5, writeFile as writeFile4 } from "fs/promises";
-import { existsSync as existsSync12 } from "fs";
+import { existsSync as existsSync13 } from "fs";
 import pathModule from "path";
 import { z as z3 } from "zod";
 var HashCacheSchema = z3.object({
@@ -6908,10 +7089,10 @@ function isSha256Hash(value) {
 function parseCache(value) {
   return HashCacheSchema.parse(value);
 }
-async function loadCache(path31) {
-  if (!existsSync12(path31)) return { version: 1, hashes: {} };
+async function loadCache(path32) {
+  if (!existsSync13(path32)) return { version: 1, hashes: {} };
   try {
-    const parsed = HashCacheSchema.safeParse(JSON.parse(await readFile8(path31, "utf8")));
+    const parsed = HashCacheSchema.safeParse(JSON.parse(await readFile8(path32, "utf8")));
     if (!parsed.success) return { version: 1, hashes: {} };
     return {
       version: 1,
@@ -6923,18 +7104,18 @@ async function loadCache(path31) {
     return { version: 1, hashes: {} };
   }
 }
-async function saveCache(path31, cache) {
+async function saveCache(path32, cache) {
   const sorted = {};
   for (const key of Object.keys(cache.hashes).sort()) {
     const hash = cache.hashes[key];
     if (!isSha256Hash(hash)) throw new Error(`Refusing to cache invalid SHA-256 for ${key}`);
     sorted[key] = hash;
   }
-  await mkdir4(pathModule.dirname(pathModule.resolve(path31)), { recursive: true });
-  const tmp = `${path31}.${process.pid}.${Math.random().toString(36).slice(2)}.tmp`;
+  await mkdir4(pathModule.dirname(pathModule.resolve(path32)), { recursive: true });
+  const tmp = `${path32}.${process.pid}.${Math.random().toString(36).slice(2)}.tmp`;
   try {
     await writeFile4(tmp, JSON.stringify({ version: 1, hashes: sorted }, null, 2) + "\n");
-    await rename4(tmp, path31);
+    await rename4(tmp, path32);
   } finally {
     await rm5(tmp, { force: true });
   }
@@ -6965,7 +7146,7 @@ async function adopt(provider, specs, lock, lockPath, opts = {}) {
   const localByHash = /* @__PURE__ */ new Map();
   const unmatchedLocal = [];
   for (const spec of specs) {
-    if (!existsSync13(spec.outFile)) {
+    if (!existsSync14(spec.outFile)) {
       unmatchedLocal.push(`${spec.styleId}/${spec.assetId} (no file at ${spec.outFile})`);
       continue;
     }
@@ -7122,13 +7303,13 @@ function formatUnmatchedRemote(objects, limit = 15) {
 }
 
 // src/pick/server.ts
-import { existsSync as existsSync15 } from "fs";
+import { existsSync as existsSync16 } from "fs";
 import { readFile as readFile12 } from "fs/promises";
 
 // src/pipeline/init.ts
 import { readdir, readFile as readFile10, writeFile as writeFile6 } from "fs/promises";
-import { existsSync as existsSync14 } from "fs";
-import path17 from "path";
+import { existsSync as existsSync15 } from "fs";
+import path18 from "path";
 function pngSize(buf) {
   if (buf.length < 24) return null;
   const isPng = buf.readUInt32BE(0) === 2303741511 && buf.readUInt32BE(4) === 218765834;
@@ -7142,7 +7323,7 @@ function slugify(value) {
 async function walk(dir, exclude) {
   const out = [];
   for (const entry of await readdir(dir, { withFileTypes: true })) {
-    const full = path17.join(dir, entry.name);
+    const full = path18.join(dir, entry.name);
     if (exclude.some((x) => full.includes(x))) continue;
     if (entry.isDirectory()) out.push(...await walk(full, exclude));
     else if (entry.name.toLowerCase().endsWith(".png")) out.push(full);
@@ -7161,9 +7342,9 @@ async function scanAssets(root, opts = {}) {
       skipped.push(`${file} (not a readable PNG)`);
       continue;
     }
-    const rel = path17.relative(root, file);
-    const category = path17.dirname(rel) === "." ? "" : path17.dirname(rel);
-    let id = slugify(path17.basename(rel));
+    const rel = path18.relative(root, file);
+    const category = path18.dirname(rel) === "." ? "" : path18.dirname(rel);
+    let id = slugify(path18.basename(rel));
     if (seen.has(id)) {
       const n = seen.get(id) + 1;
       seen.set(id, n);
@@ -7220,7 +7401,7 @@ function mode(values) {
   return [...counts.entries()].sort((a, b) => b[1] - a[1])[0]?.[0] ?? 64;
 }
 async function writeManifestFile(target, manifest) {
-  if (existsSync14(target)) {
+  if (existsSync15(target)) {
     throw new Error(`${target} already exists \u2014 refusing to overwrite an existing manifest.`);
   }
   await writeFile6(target, JSON.stringify(manifest, null, 2) + "\n");
@@ -7706,7 +7887,7 @@ async function currentArt(entry, spec) {
   const previous = primaryOutput({ ...entry, outputs: entry.supersededOutputs });
   if (!previous) return null;
   const file = resolveOutputPath(previous.path, spec.root);
-  if (!existsSync15(file)) return null;
+  if (!existsSync16(file)) return null;
   const contentType = previous.mediaType ?? mediaTypeFromExtension(file);
   if (!contentType) return null;
   let width = entry.width;
@@ -7877,14 +8058,14 @@ async function runPicker(provider, lock, lockPath, opts = {}) {
 
 // src/gallery/snapshot.ts
 import { createHash as createHash3 } from "crypto";
-import { existsSync as existsSync18 } from "fs";
+import { existsSync as existsSync19 } from "fs";
 import { readFile as readFile16, stat as stat3 } from "fs/promises";
-import path22 from "path";
+import path23 from "path";
 
 // src/workspace.ts
 import { mkdir as mkdir5, readFile as readFile13, rename as rename5, rm as rm6, writeFile as writeFile7 } from "fs/promises";
-import { existsSync as existsSync16 } from "fs";
-import path18 from "path";
+import { existsSync as existsSync17 } from "fs";
+import path19 from "path";
 import { z as z4 } from "zod";
 var WorkspaceProjectSchema = z4.object({
   id: z4.string().min(1),
@@ -7909,7 +8090,7 @@ ${parsed.error.issues.slice(0, 5).map((i) => `  ${i.path.join(".")}: ${i.message
   );
 }
 async function loadWorkspace(workspacePath) {
-  if (!existsSync16(workspacePath)) return { version: 1, projects: [] };
+  if (!existsSync17(workspacePath)) return { version: 1, projects: [] };
   let raw;
   try {
     raw = JSON.parse(await readFile13(workspacePath, "utf8"));
@@ -7926,7 +8107,7 @@ async function saveWorkspace(workspacePath, ws) {
     version: 1,
     projects: [...ws.projects].sort((a, b) => a.id.localeCompare(b.id))
   };
-  await mkdir5(path18.dirname(path18.resolve(workspacePath)), { recursive: true });
+  await mkdir5(path19.dirname(path19.resolve(workspacePath)), { recursive: true });
   const tmp = `${workspacePath}.${process.pid}.${Math.random().toString(36).slice(2)}.tmp`;
   try {
     await writeFile7(tmp, JSON.stringify(sorted, null, 2) + "\n");
@@ -7936,12 +8117,12 @@ async function saveWorkspace(workspacePath, ws) {
   }
 }
 function toPortablePath(dir, absolute) {
-  return path18.relative(dir, absolute).split(path18.sep).join("/");
+  return path19.relative(dir, absolute).split(path19.sep).join("/");
 }
 function resolveProject(dir, project) {
   return {
-    manifestPath: path18.resolve(dir, project.manifest.split("/").join(path18.sep)),
-    lockPath: path18.resolve(dir, project.lock.split("/").join(path18.sep))
+    manifestPath: path19.resolve(dir, project.manifest.split("/").join(path19.sep)),
+    lockPath: path19.resolve(dir, project.lock.split("/").join(path19.sep))
   };
 }
 function validateWorkspace(ws, dir) {
@@ -7954,21 +8135,21 @@ function validateWorkspace(ws, dir) {
     const { manifestPath, lockPath } = resolveProject(dir, project);
     lockOwners.set(lockPath, [...lockOwners.get(lockPath) ?? [], project.id]);
     manifestOwners.set(manifestPath, [...manifestOwners.get(manifestPath) ?? [], project.id]);
-    if (path18.isAbsolute(project.manifest) || path18.isAbsolute(project.lock)) {
+    if (path19.isAbsolute(project.manifest) || path19.isAbsolute(project.lock)) {
       diagnostics.push({
         id: "absolute-path",
         level: "warning",
         message: `project "${project.id}" stores an absolute path \u2014 the catalog will not resolve correctly if this tree is cloned or moved elsewhere`
       });
     }
-    if (!existsSync16(manifestPath)) {
+    if (!existsSync17(manifestPath)) {
       diagnostics.push({
         id: "missing-manifest",
         level: "error",
         message: `project "${project.id}" manifest not found: ${manifestPath}`
       });
     }
-    if (!existsSync16(lockPath)) {
+    if (!existsSync17(lockPath)) {
       diagnostics.push({
         id: "missing-lock",
         level: "error",
@@ -8015,12 +8196,12 @@ function validateWorkspace(ws, dir) {
 }
 
 // src/gallery/edit.ts
-import path21 from "path";
+import path22 from "path";
 import { z as z7 } from "zod";
 
 // src/manifest-edit.ts
 import { readFile as readFile14, rename as rename6, rm as rm7, writeFile as writeFile8 } from "fs/promises";
-import path19 from "path";
+import path20 from "path";
 import { z as z5 } from "zod";
 var HexSha = z5.string().regex(/^[0-9a-f]{64}$/);
 var AssetPatchSchema = z5.object({
@@ -8232,7 +8413,7 @@ function applyEdit(raw, edit) {
   }
 }
 async function applyManifestEdit(manifestPath, edit) {
-  const absolute = path19.resolve(manifestPath);
+  const absolute = path20.resolve(manifestPath);
   const original = await readFile14(absolute, "utf8");
   const before = sha256(original);
   if (before !== edit.expectedSha256) throw new ManifestDriftError(absolute);
@@ -8247,9 +8428,9 @@ async function applyManifestEdit(manifestPath, edit) {
   applyEdit(raw, edit);
   const next = serializeLike(original, raw);
   if (next === original) return { manifestPath: absolute, sha256: before, changed: false };
-  const tmp = path19.join(
-    path19.dirname(absolute),
-    `.${path19.basename(absolute)}.${process.pid}.${Math.random().toString(36).slice(2)}.tmp`
+  const tmp = path20.join(
+    path20.dirname(absolute),
+    `.${path20.basename(absolute)}.${process.pid}.${Math.random().toString(36).slice(2)}.tmp`
   );
   try {
     await writeFile8(tmp, next);
@@ -8269,18 +8450,18 @@ async function applyManifestEdit(manifestPath, edit) {
 
 // src/pipeline/hand-edit.ts
 import { spawn as spawn2 } from "child_process";
-import { existsSync as existsSync17 } from "fs";
+import { existsSync as existsSync18 } from "fs";
 import { copyFile, mkdir as mkdir6, readFile as readFile15, rename as rename7, rm as rm8, writeFile as writeFile9 } from "fs/promises";
-import path20 from "path";
+import path21 from "path";
 import { z as z6 } from "zod";
 var HAND_EDIT_DIR = "edits";
 function handEditPath(loaded, spec) {
   const style = loaded.manifest.styles[spec.styleId];
-  const outDir = path20.resolve(loaded.root, style?.outDir ?? ".");
-  const relative = path20.relative(outDir, spec.outFile);
-  const inside = relative && !relative.startsWith("..") && !path20.isAbsolute(relative);
-  const file = inside ? relative : path20.basename(spec.outFile);
-  return path20.join(outDir, HAND_EDIT_DIR, file.replace(/\.gif$/i, ".png"));
+  const outDir = path21.resolve(loaded.root, style?.outDir ?? ".");
+  const relative = path21.relative(outDir, spec.outFile);
+  const inside = relative && !relative.startsWith("..") && !path21.isAbsolute(relative);
+  const file = inside ? relative : path21.basename(spec.outFile);
+  return path21.join(outDir, HAND_EDIT_DIR, file.replace(/\.gif$/i, ".png"));
 }
 function handEditBases(spec, lock) {
   const entry = lock.entries[lockKey(spec.styleId, spec.assetId)];
@@ -8293,10 +8474,10 @@ function handEditBases(spec, lock) {
     }));
     if (members.some((member) => member.mediaType && member.mediaType !== "image/png")) return null;
     if (entry.outputs.length === 1 && !primaryOutput(entry)) return null;
-    if (!members.every((member) => existsSync17(member.path))) return null;
+    if (!members.every((member) => existsSync18(member.path))) return null;
     return members.map(({ role, path: file }) => ({ role, path: file }));
   }
-  return existsSync17(spec.outFile) ? [{ role: null, path: spec.outFile }] : null;
+  return existsSync18(spec.outFile) ? [{ role: null, path: spec.outFile }] : null;
 }
 function handEditMembers(loaded, spec, lock, editPath) {
   const entry = lock.entries[lockKey(spec.styleId, spec.assetId)];
@@ -8322,18 +8503,18 @@ async function startHandEdit(loaded, lock, spec, opts = {}) {
       `${spec.styleId}/${spec.assetId} declares ${spec.source}, one committed file placed for the whole set; clear that source (pixelkiln edit detach) to hand-edit the members one by one`
     );
   }
-  const existing = spec.source ? path20.resolve(loaded.root, spec.source) : null;
+  const existing = spec.source ? path21.resolve(loaded.root, spec.source) : null;
   const editPath = existing ?? handEditPath(loaded, spec);
   const members = handEditMembers(loaded, spec, lock, editPath);
   let created = false;
   for (const member of members) {
-    if (existsSync17(member.path)) continue;
+    if (existsSync18(member.path)) continue;
     if (!member.base) {
       throw new ManifestEditError(
         `${spec.styleId}/${spec.assetId} has no generated PNG on disk to start from; generate or restore it first`
       );
     }
-    await mkdir6(path20.dirname(member.path), { recursive: true });
+    await mkdir6(path21.dirname(member.path), { recursive: true });
     await copyFile(member.base, member.path);
     created = true;
   }
@@ -8471,7 +8652,7 @@ async function saveHandEdit(loaded, lock, spec, input) {
     editor: input.editor,
     protocol: input.protocol,
     savedAt: (input.now ?? /* @__PURE__ */ new Date()).toISOString(),
-    project: projectPath ? path20.basename(projectPath) : null,
+    project: projectPath ? path21.basename(projectPath) : null,
     outputs: incoming.map((frame, index) => ({
       role: frame.role,
       basedOn: basedOnHash(entry, index),
@@ -8606,7 +8787,7 @@ function createGalleryEditHandler(opts) {
     }
     const result = await applyManifestEdit(manifestPath, parsed.data);
     if (result.changed) {
-      const relative = path21.relative(process.cwd(), result.manifestPath);
+      const relative = path22.relative(process.cwd(), result.manifestPath);
       const shown = !relative || relative.startsWith("..") ? result.manifestPath : relative;
       const subject = parsed.data.action === "patch-style" ? `style ${parsed.data.styleId}` : parsed.data.action === "set-source" || parsed.data.action === "clear-source" ? `${parsed.data.styleId}/${parsed.data.assetId} source` : parsed.data.assetId;
       log2(`  manifest edited: ${parsed.data.action === "add-asset" ? "added" : "changed"} ${subject} in ${shown}`);
@@ -8618,7 +8799,7 @@ function createGalleryEditHandler(opts) {
 // src/gallery/snapshot.ts
 var PROJECT_FILE_TYPE = "application/octet-stream";
 function galleryMediaId(absolutePath) {
-  return createHash3("sha256").update(path22.resolve(absolutePath)).digest("hex").slice(0, 24);
+  return createHash3("sha256").update(path23.resolve(absolutePath)).digest("hex").slice(0, 24);
 }
 function galleryMediaRoute(id) {
   return `/media/${id}`;
@@ -8633,6 +8814,38 @@ function matchesFilter(filter, styleId, assetId) {
   if (filter?.assets?.length && !filter.assets.includes(assetId)) return false;
   return true;
 }
+function describeHistory(media, entry, cacheDir) {
+  return (entry.history ?? []).map((generation, i) => {
+    const outputs = generation.outputs.map((output) => {
+      const mediaType = output.mediaType ?? MediaType.PNG;
+      const file = path23.join(cacheDir, cacheFileName(output.sha256, mediaType));
+      let url = null;
+      if (existsSync19(file)) {
+        const id = galleryMediaId(file);
+        media.set(id, { path: file, contentType: mediaType });
+        url = `${galleryMediaRoute(id)}?v=${output.sha256.slice(0, 24)}`;
+      }
+      return { role: output.role ?? null, sha256: output.sha256, path: output.path, url };
+    });
+    return {
+      index: i + 1,
+      objectId: generation.objectId,
+      jobId: generation.jobId,
+      prompt: generation.prompt,
+      promptDiffers: generation.prompt !== entry.prompt,
+      width: generation.width,
+      height: generation.height,
+      cost: generation.cost,
+      costUnit: generation.costUnit,
+      submittedAt: generation.submittedAt,
+      downloadedAt: generation.downloadedAt,
+      retiredAt: generation.retiredAt,
+      outputs,
+      cached: outputs.length > 0 && outputs.every((output) => output.url !== null),
+      upstreamUrl: generation.provider === "pixellab" ? pixelLabObjectUrl(generation.generator, generation.objectId) : null
+    };
+  });
+}
 var MAX_COMPARED_BYTES = 8 * 1024 * 1024;
 async function samePixels(a, b) {
   try {
@@ -8689,10 +8902,10 @@ async function describeOutput(media, root, absolutePath, recorded = {}) {
 async function describeQuality(media, root, inspection) {
   const outputPaths = inspection.outputs ?? [inspection.output];
   const outputs = await Promise.all(
-    outputPaths.map((file) => describeOutput(media, root, path22.resolve(root, file)))
+    outputPaths.map((file) => describeOutput(media, root, path23.resolve(root, file)))
   );
-  const recordPath = path22.resolve(root, inspection.record);
-  const recordExists = existsSync18(recordPath);
+  const recordPath = path23.resolve(root, inspection.record);
+  const recordExists = existsSync19(recordPath);
   let options = null;
   let check = null;
   if (recordExists) {
@@ -8711,7 +8924,7 @@ async function describeQuality(media, root, inspection) {
   return {
     state: inspection.state,
     reason: inspection.reason,
-    output: portableOutputPath(path22.resolve(root, inspection.output), root),
+    output: portableOutputPath(path23.resolve(root, inspection.output), root),
     record: portableOutputPath(recordPath, root),
     recordExists,
     outputs,
@@ -8750,6 +8963,7 @@ async function buildGallerySnapshot(opts) {
   const items = [];
   const manifestText = await readFile16(loaded.path, "utf8");
   const manifestSha256 = sha256(manifestText);
+  const cacheDir = path23.resolve(path23.dirname(opts.lockPath), ".pixelkiln", "cache");
   let rawStyles = {};
   try {
     const raw = JSON.parse(manifestText);
@@ -8773,12 +8987,12 @@ async function buildGallerySnapshot(opts) {
         )
       );
       if (spec.source) {
-        const editPath = path22.resolve(root, spec.source);
+        const editPath = path23.resolve(root, spec.source);
         const memberCount = sourceIsStem(spec.source, entry, root) ? entry.outputs.length : 1;
         const editShas = await Promise.all(
           Array.from({ length: memberCount }, async (_, index) => {
             const file = sourceOutputPath(spec.source, entry, index, root);
-            return { file, sha256: existsSync18(file) ? await sha256File(file) : null };
+            return { file, sha256: existsSync19(file) ? await sha256File(file) : null };
           })
         );
         edits = await Promise.all(editShas.map(({ file, sha256: editSha }) => describeOutput(media, root, file, { sha256: editSha })));
@@ -8786,7 +9000,7 @@ async function buildGallerySnapshot(opts) {
         const companion = await readHandEditCompanion(editPath);
         if (companion) {
           const projectPath = handEditProjectPath(editPath);
-          const project = companion.project && existsSync18(projectPath) ? await fileInfo(projectPath) : null;
+          const project = companion.project && existsSync19(projectPath) ? await fileInfo(projectPath) : null;
           let projectUrl = null;
           if (project) {
             const id = galleryMediaId(projectPath);
@@ -8822,8 +9036,8 @@ async function buildGallerySnapshot(opts) {
         editStatus = edits.some((member) => !member.exists) ? "missing" : editChanged.every((changed) => !changed) ? "same" : regenerated ? "regenerated-since" : "edited";
       }
     } else if (spec.source) {
-      outputs = [await describeOutput(media, root, path22.resolve(root, spec.source))];
-    } else if (!entry && existsSync18(spec.outFile)) {
+      outputs = [await describeOutput(media, root, path23.resolve(root, spec.source))];
+    } else if (!entry && existsSync19(spec.outFile)) {
       outputs = [await describeOutput(media, root, spec.outFile)];
     } else {
       outputs = [];
@@ -8874,6 +9088,7 @@ async function buildGallerySnapshot(opts) {
       editMeta,
       upstreamUrl: entry?.provider === "pixellab" ? pixelLabObjectUrl(entry.generator, entry.objectId) : null,
       refreshable: Boolean(entry && entry.status === "downloaded" && entry.outputs.length && (entry.sourceUrls?.length || entry.sourceUrl)),
+      history: entry ? describeHistory(media, entry, cacheDir) : [],
       tags: spec.tags,
       category: asset?.category ?? null
     });
@@ -8933,6 +9148,7 @@ async function buildGallerySnapshot(opts) {
       editMeta: null,
       upstreamUrl: entry.provider === "pixellab" ? pixelLabObjectUrl(entry.generator, entry.objectId) : null,
       refreshable: false,
+      history: describeHistory(media, entry, cacheDir),
       tags: [],
       category: null
     });
@@ -9000,11 +9216,12 @@ async function buildGallerySnapshot(opts) {
       id: loaded.manifest.name,
       name: loaded.manifest.name,
       manifest: loaded.path,
-      lock: path22.resolve(opts.lockPath),
+      lock: path23.resolve(opts.lockPath),
       root,
       provider: loaded.manifest.provider,
       account: null,
       manifestSha256,
+      historyLimit: historyLimit(loaded.manifest),
       entries: Object.keys(lock.entries).length,
       items: items.length,
       spendByUnit: spendByUnit(lock),
@@ -9025,7 +9242,7 @@ async function buildGallerySnapshot(opts) {
   return { snapshot, media };
 }
 async function buildWorkspaceGallerySnapshot(opts) {
-  const dir = path22.dirname(path22.resolve(opts.workspacePath));
+  const dir = path23.dirname(path23.resolve(opts.workspacePath));
   const media = /* @__PURE__ */ new Map();
   const projects = [];
   const items = [];
@@ -9068,11 +9285,12 @@ async function buildWorkspaceGallerySnapshot(opts) {
         id: project.id,
         name: loaded.manifest.name,
         manifest: manifestPath,
-        lock: path22.resolve(lockPath),
+        lock: path23.resolve(lockPath),
         root: loaded.root,
         provider: loaded.manifest.provider,
         account: project.account ?? null,
         manifestSha256: manifestSha256 ?? sha256(await readFile16(manifestPath, "utf8")),
+        historyLimit: historyLimit(loaded.manifest),
         entries: Object.keys(lock.entries).length,
         items: projectItems.length,
         spendByUnit: spendByUnit(lock),
@@ -9083,11 +9301,12 @@ async function buildWorkspaceGallerySnapshot(opts) {
         id: project.id,
         name: project.id,
         manifest: manifestPath,
-        lock: path22.resolve(lockPath),
-        root: path22.dirname(manifestPath),
+        lock: path23.resolve(lockPath),
+        root: path23.dirname(manifestPath),
         provider: project.provider,
         account: project.account ?? null,
         manifestSha256: null,
+        historyLimit: 0,
         entries: 0,
         items: 0,
         spendByUnit: {},
@@ -9110,7 +9329,7 @@ async function buildWorkspaceGallerySnapshot(opts) {
       version: 1,
       generatedAt: (opts.now ?? (() => /* @__PURE__ */ new Date()))().toISOString(),
       project: null,
-      workspace: { path: path22.resolve(opts.workspacePath), dir, projects },
+      workspace: { path: path23.resolve(opts.workspacePath), dir, projects },
       filter,
       totals: {
         entries: projects.reduce((sum, project) => sum + project.entries, 0),
@@ -9431,6 +9650,31 @@ function renderGallery(snapshot, opts = {}) {
     background-size:12px 12px; background-position:0 0,6px 6px; display:grid; place-items:center; padding:8px; min-height:96px; }
   .pair figure img { image-rendering:pixelated; display:block; max-width:100%; }
   .pair figcaption { font:11px/1.4 var(--mono); color:var(--dim); background:var(--panel); padding:2px 6px; margin-top:6px; }
+  .versions { display:grid; gap:8px; margin:8px 0 4px; }
+  .version { display:grid; grid-template-columns:auto 1fr auto; gap:6px 12px; align-items:center; border:1px solid var(--line);
+    background:var(--panel-deep); padding:8px 10px; font-size:12.5px; }
+  .version .thumb { width:64px; height:64px; display:grid; place-items:center; background-image:var(--checker); border:1px solid var(--line); }
+  .version .thumb img { image-rendering:pixelated; max-width:64px; max-height:64px; }
+  .version .thumb span { font:10.5px var(--mono); color:var(--dim); text-align:center; padding:4px; }
+  .version .facts { display:grid; gap:2px; min-width:0; }
+  .version .facts b { font:650 12px/1.4 var(--mono); }
+  .version .facts .prompt { color:var(--dim); white-space:nowrap; overflow:hidden; text-overflow:ellipsis; }
+  .version .facts .prompt.differs { color:var(--warn); }
+  .version .facts .meta { color:var(--dim); font-size:12px; }
+  .version .acts { display:grid; gap:6px; justify-items:end; }
+  .version .acts button { padding:3px 9px; font-size:12px; white-space:nowrap; }
+  .dot.busy { background:var(--cool); animation: pulse 1.2s ease-in-out infinite; }
+  @keyframes pulse { 0%, 100% { opacity:1; } 50% { opacity:.25; } }
+  @media (prefers-reduced-motion: reduce) { .dot.busy { animation:none; } }
+  .card .busy-badge { position:absolute; left:6px; bottom:6px; display:inline-flex; align-items:center; gap:5px;
+    background:var(--panel); color:var(--cool); border:1px solid var(--cool); padding:2px 7px; font:650 10.5px/1.4 var(--mono); }
+  .drawer .job-strip { display:grid; grid-template-columns:auto 1fr; gap:4px 12px; align-items:baseline; margin-top:10px;
+    padding:10px 12px; border:1px solid var(--cool); background:color-mix(in srgb, var(--cool) 8%, var(--panel-deep)); font-size:12.5px; }
+  .drawer .job-strip .ph { display:inline-flex; align-items:center; gap:6px; font:650 12px/1.4 var(--mono); color:var(--cool); white-space:nowrap; }
+  .drawer .job-strip .last { color:var(--dim); overflow:hidden; text-overflow:ellipsis; white-space:nowrap; min-width:0; }
+  .drawer .job-strip .what { grid-column:1 / -1; color:var(--text); }
+  .drawer .job-strip .acts { grid-column:1 / -1; display:flex; gap:6px; }
+  .drawer .job-strip .acts button { padding:3px 9px; font-size:12px; }
   .card .pen { position:absolute; right:6px; top:6px; background:var(--panel); color:var(--accent-soft); border:1px solid var(--accent);
     font:700 11px/1 var(--mono); padding:3px 5px; }
   .hand-actions { display:flex; gap:8px; flex-wrap:wrap; margin-top:8px; }
@@ -9589,6 +9833,11 @@ const splitTags = (value) => value.split(',').map((t) => t.trim()).filter(Boolea
 
 const ACTIVE_PHASES = new Set(['queued', 'submitting', 'polling', 'fetching', 'review']);
 const PHASE_TONE = { queued: 'cool', submitting: 'cool', polling: 'cool', fetching: 'cool', review: 'warn', done: 'ok', failed: 'bad' };
+// The job still working on this record, if any: what the drawer and its card
+// show while a regeneration, restore, or pull is in flight.
+const activeJobFor = (item) => GEN.jobs.find((job) => ACTIVE_PHASES.has(job.phase) && job.project === item.project && job.keys.includes(item.key)) || null;
+const JOB_VERB = { generate: 'regenerating', resume: 'resuming', refresh: 'pulling upstream changes for', restore: 'restoring', revert: 'bringing back a previous generation of' };
+const PHASE_TEXT = { queued: 'queued', submitting: 'submitting to the provider', polling: 'waiting for the provider to finish', fetching: 'downloading the result', review: 'candidates are ready to review' };
 const remainingBudget = (provider) => {
   const keyed = GEN.budget.byProvider[provider];
   const ceiling = keyed !== undefined ? keyed : GEN.budget.amount;
@@ -9618,10 +9867,34 @@ async function pollJobs() {
   renderHeader();
   let changed = false;
   for (const job of GEN.jobs) {
-    if (!ACTIVE_PHASES.has(job.phase) && !ui.settled.has(job.id)) { ui.settled.add(job.id); changed = true; }
+    if (!ACTIVE_PHASES.has(job.phase) && !ui.settled.has(job.id)) {
+      ui.settled.add(job.id); changed = true;
+      // The open record hears how its job ended, where the strip was.
+      const open = ui.open && snap.items.find((i) => i.id === ui.open);
+      if (open && job.project === open.project && job.keys.includes(open.key)) {
+        ui.notice = { id: open.id, text: job.phase === 'failed'
+          ? (JOB_VERB[job.mode] || job.mode).replace(/ing$/, 'ing') + ' this asset failed: ' + (job.error || 'see the log above')
+          : job.mode === 'generate' ? 'Regenerated. The new result is on disk and recorded as this generation.'
+          : job.mode === 'restore' ? 'Restored. The recorded bytes are back on disk.'
+          : job.mode === 'revert' ? 'Brought back generation #' + job.revert + '. The one it replaced is now #1 in the list below.'
+          : job.mode === 'refresh' ? (job.counts.downloaded ? 'Pulled the upstream change; the lockfile records the new bytes.' : 'Nothing changed upstream; the file was left alone.')
+          : 'Done.' };
+      }
+    }
     if (job.phase === 'review' && !ui.settled.has(job.id + ':review')) { ui.settled.add(job.id + ':review'); changed = true; }
   }
   if (changed) refresh();
+  else {
+    // A job in flight: keep the open record's strip and the card badges honest without a full re-render.
+    if (ui.open && !$('dialog-host').childNodes.length) renderDrawer();
+    for (const c of document.querySelectorAll('.card')) {
+      const item = snap.items.find((i) => i.id === c.dataset.key);
+      const job = item && activeJobFor(item);
+      const badge = c.querySelector('.busy-badge');
+      if (job && !badge) c.replaceWith(card(item));
+      else if (!job && badge) badge.remove();
+    }
+  }
   const active = GEN.jobs.some((job) => ACTIVE_PHASES.has(job.phase) && job.phase !== 'review');
   clearTimeout(jobsTimer);
   if (active) jobsTimer = setTimeout(pollJobs, 2000);
@@ -9635,7 +9908,7 @@ function renderJobs() {
     const row = el('div', 'job');
     const ph = el('span', 'ph');
     ph.append(el('i', 'dot ' + PHASE_TONE[job.phase]), document.createTextNode(job.phase));
-    const what = (job.mode === 'refresh' ? 'pull upstream for ' : job.mode === 'restore' ? 'restore ' : job.mode === 'resume' ? 'resume ' : 'generate ') + job.keys.length + (job.keys.length === 1 ? ' asset' : ' assets') +
+    const what = (job.mode === 'refresh' ? 'pull upstream for ' : job.mode === 'restore' ? 'restore ' : job.mode === 'revert' ? 'bring back generation #' + job.revert + ' of ' : job.mode === 'resume' ? 'resume ' : 'generate ') + job.keys.length + (job.keys.length === 1 ? ' asset' : ' assets') +
       (job.project ? ' in ' + job.project : '');
     const last = el('span', 'last', what + (job.messages.length ? ' \u2014 ' + job.messages[job.messages.length - 1].trim() : ''));
     last.title = job.keys.join('\\n');
@@ -9760,15 +10033,16 @@ function budgetLine() {
 
 // The confirm step: what will be sent, what it is estimated to cost, and what
 // this session may still spend. Mirrors gen's "Spend \u2026 on N asset(s)?" prompt.
-function generateDialog(items, { project = null, force = false, resume = false, refresh = false, restore = false } = {}) {
+function generateDialog(items, { project = null, force = false, resume = false, refresh = false, restore = false, revert = null, generation = null } = {}) {
   const host = $('dialog-host');
   host.textContent = '';
   const wrap = el('div', 'dialog');
   const form = el('form');
   const noun = items.length + (items.length === 1 ? ' asset' : ' assets');
-  const free = resume || refresh || restore;
+  const free = resume || refresh || restore || revert !== null;
   const replacing = items.filter((i) => i.state === 'orphaned' && i.outputs.every((o) => o.exists) || i.state === 'untracked');
   form.append(el('h3', null, refresh ? 'Pull upstream changes for ' + noun
+    : revert !== null ? 'Bring back generation #' + revert + ' of ' + items[0].key
     : restore ? 'Restore ' + noun
     : resume ? 'Resume ' + noun
     : (force ? 'Regenerate ' : 'Generate ') + noun));
@@ -9790,6 +10064,10 @@ function generateDialog(items, { project = null, force = false, resume = false,
   const sum = el('div', 'sum');
   if (refresh) {
     sum.append(el('div', null, 'Re-downloads each object from the provider and replaces the local file only when the object changed upstream \u2014 for example after editing it in the provider\u2019s own editor. Unchanged objects are left alone; a file you changed locally is refused. Nothing is submitted.'));
+  } else if (revert !== null) {
+    sum.append(el('div', null, 'The current generation moves into this asset\u2019s history and generation #' + revert + ' becomes current again: its object, hashes, and cost are recorded as this generation, and its bytes are written back ' +
+      (generation && generation.cached ? 'from the local cache.' : 'by re-downloading them from the provider.') + ' Nothing is generated; nothing upstream changes. Undo it from the same list.'));
+    if (generation && generation.promptDiffers) sum.append(el('div', 'warn', 'That generation was made with a different prompt than the current one; the record will show it as stale until the manifest matches or it is regenerated.'));
   } else if (restore) {
     sum.append(el('div', null, 'Puts the recorded bytes back on disk from the local cache or the provider object. Nothing is generated or submitted.'));
     if (force && replacing.length) sum.append(el('div', 'warn', 'The file on disk was changed after PixelKiln wrote it. Restoring discards that change. To keep it instead, cancel and use Edit by hand or Edit in browser first: the edit is copied beside the generated file, and the record stays intact.'));
@@ -9811,7 +10089,7 @@ function generateDialog(items, { project = null, force = false, resume = false,
   }
   form.append(sum);
   const actions = el('div', 'actions');
-  const go = el('button', 'primary', refresh ? 'Pull changes' : restore ? (force && replacing.length ? 'Restore and discard my change' : 'Restore') : resume ? 'Resume' : force && replacing.length ? 'Generate and replace' : 'Generate');
+  const go = el('button', 'primary', refresh ? 'Pull changes' : revert !== null ? 'Bring it back' : restore ? (force && replacing.length ? 'Restore and discard my change' : 'Restore') : resume ? 'Resume' : force && replacing.length ? 'Generate and replace' : 'Generate');
   go.type = 'submit';
   const cancel = el('button', null, 'Cancel'); cancel.type = 'button'; cancel.onclick = () => { host.textContent = ''; };
   const msg = el('span', 'msg');
@@ -9827,6 +10105,7 @@ function generateDialog(items, { project = null, force = false, resume = false,
       if (resume) body.resume = true;
       if (refresh) body.refresh = true;
       if (restore) body.restore = true;
+      if (revert !== null) body.revert = revert;
       const job = await postGenerate(body);
       host.textContent = '';
       GEN.jobs.unshift(job);
@@ -10270,6 +10549,13 @@ function card(item) {
   if (item.editStatus === 'edited' || item.editStatus === 'regenerated-since') {
     const pen = el('span', 'pen', '\u270E'); pen.title = 'hand-edited'; cell.append(pen);
   }
+  const job = activeJobFor(item);
+  if (job) {
+    const badge = el('span', 'busy-badge');
+    badge.append(el('i', 'dot busy'), document.createTextNode(job.phase === 'review' ? 'review' : job.mode === 'generate' ? 'generating' : job.mode));
+    badge.title = (JOB_VERB[job.mode] || job.mode) + ' this asset \u2014 ' + (PHASE_TEXT[job.phase] || job.phase);
+    cell.append(badge);
+  }
   c.append(cell, body);
   c.onclick = (e) => { if (e.shiftKey) toggleCompare(item.id); else openItem(item.id); };
   return c;
@@ -10450,6 +10736,54 @@ function candidatesControl(style) {
   return wrap;
 }
 
+// The generations this one replaced: what the lockfile still remembers, with
+// thumbnails from the content cache while the bytes are there, and a way back.
+function historySection(item) {
+  const limit = projectOf(item)?.historyLimit;
+  if (!item.history.length && !(limit > 0 && item.status === 'downloaded')) return null;
+  const s = el('section', 'meta');
+  s.append(el('h3', null, item.history.length ? 'Previous generations (' + item.history.length + ')' : 'Previous generations'));
+  if (!item.history.length) {
+    s.append(el('div', 'state-dim', 'None yet. A regeneration keeps the generation it replaces \u2014 up to ' + limit + ' per asset (PIXELKILN_HISTORY, or the manifest\u2019s history) \u2014 so it can be brought back from here.'));
+    return s;
+  }
+  const list = el('div', 'versions');
+  const job = GENERATION ? activeJobFor(item) : null;
+  for (const g of item.history) {
+    const v = el('div', 'version');
+    const thumb = el('div', 'thumb');
+    const first = g.outputs[0];
+    if (first && first.url) { const img = el('img'); img.src = first.url; img.alt = 'generation #' + g.index; thumb.append(img); }
+    else thumb.append(el('span', null, g.cached ? '' : 'not cached'));
+    const facts = el('div', 'facts');
+    const head = el('div');
+    head.append(el('b', null, '#' + g.index), document.createTextNode(' \xB7 ' + fmtWhen(g.downloadedAt || g.submittedAt) + ' \xB7 ' + fmtCost(g.costUnit, g.cost) +
+      (g.outputs.length > 1 ? ' \xB7 ' + g.outputs.length + ' files' : '')));
+    facts.append(head);
+    const prompt = el('div', 'prompt' + (g.promptDiffers ? ' differs' : ''), (g.promptDiffers ? 'prompt: ' : 'same prompt: ') + g.prompt);
+    prompt.title = g.prompt;
+    facts.append(prompt);
+    const meta = el('div', 'meta');
+    meta.append(document.createTextNode((first ? first.sha256.slice(0, 12) + '\u2026' : '') + (g.cached ? ' \xB7 bytes cached locally' : ' \xB7 not in the local cache; a restore re-downloads it')));
+    if (g.upstreamUrl) { const a = el('a', null, 'open in ' + item.provider + ' \u2197'); a.href = g.upstreamUrl; a.target = '_blank'; a.rel = 'noopener'; meta.append(document.createTextNode(' \xB7 '), a); }
+    facts.append(meta);
+    const acts = el('div', 'acts');
+    if (GENERATION) {
+      const b = el('button', null, 'Restore this one \xB7 no cost'); b.type = 'button';
+      b.disabled = !!job;
+      b.title = job ? 'Wait for the running job to finish' : 'The current generation moves into history; this one becomes current and its bytes are written back';
+      b.onclick = () => generateDialog([item], { project: item.project, revert: String(g.index), generation: g });
+      acts.append(b);
+    }
+    v.append(thumb, facts, acts);
+    list.append(v);
+  }
+  s.append(list);
+  s.append(el('div', 'state-dim', 'Keeping up to ' + limit + ' per asset; a restore moves the current generation into this list, so it can be undone the same way.' +
+    (GENERATION ? '' : ' Restoring needs the gallery started with --budget (any amount; nothing is spent).')));
+  return s;
+}
+
 function upstreamSection(item) {
   if (!item.upstreamUrl && !(GENERATION && item.refreshable)) return null;
   const s = el('section', 'meta');
@@ -10476,6 +10810,30 @@ function upstreamSection(item) {
   return s;
 }
 
+// What a job is doing to this record right now. The record's state line still
+// says what is on disk; this says what is about to replace it.
+function jobStrip(item, job) {
+  const strip = el('div', 'job-strip');
+  const ph = el('span', 'ph');
+  ph.append(el('i', 'dot busy'), document.createTextNode(job.phase));
+  const last = el('span', 'last', job.messages.length ? job.messages[job.messages.length - 1].trim() : '');
+  last.title = job.messages.join('\\n');
+  const what = el('span', 'what', (JOB_VERB[job.mode] || job.mode) + ' this asset \u2014 ' + (PHASE_TEXT[job.phase] || job.phase) +
+    (job.mode === 'generate' && job.phase !== 'review' ? '. The current file stays until the new result is downloaded.' : '.'));
+  strip.append(ph, last, what);
+  const acts = el('div', 'acts');
+  if (job.phase === 'review' && job.review.includes(item.key)) {
+    const b = el('button', 'primary', 'Review candidates'); b.type = 'button'; b.onclick = () => openReview(job.id);
+    acts.append(b);
+  }
+  const logBtn = el('button', null, ui.logs.has(job.id) ? 'Hide log' : 'Log'); logBtn.type = 'button';
+  logBtn.onclick = () => { ui.logs.has(job.id) ? ui.logs.delete(job.id) : ui.logs.add(job.id); renderDrawer(); };
+  acts.append(logBtn);
+  strip.append(acts);
+  if (ui.logs.has(job.id)) { const pre = el('pre', null, job.messages.join('\\n')); pre.style.gridColumn = '1 / -1'; strip.append(pre); }
+  return strip;
+}
+
 function generateActions(item) {
   const row = el('div', 'gen');
   if (!GENERATION || !item.declared || item.currentSpecHash === null) return row;
@@ -11183,7 +11541,9 @@ function renderDrawer() {
   body.append(previewHost);
   if (ui.notice && ui.notice.id === item.id) body.append(el('div', 'notice', ui.notice.text));
   body.append(stateNode(item.state, item.reason));
-  if (GENERATION) body.append(generateActions(item));
+  const job = GENERATION ? activeJobFor(item) : null;
+  if (job) body.append(jobStrip(item, job));
+  else if (GENERATION) body.append(generateActions(item));
   // Writes are opt-in flags on the command line; say so where the buttons would be.
   if ((!EDITABLE || !GENERATION) && item.declared) {
     const missing = [];
@@ -11248,6 +11608,8 @@ function renderDrawer() {
   if (hand) body.append(hand);
   const upstream = upstreamSection(item);
   if (upstream) body.append(upstream);
+  const versions = historySection(item);
+  if (versions) body.append(versions);
 
   if (item.revision || item.revisionParentKey) {
     const { s, dl } = section('Lineage');
@@ -11794,10 +12156,15 @@ var GenerateRequestSchema = z8.object({
   /** Re-download downloaded outputs and replace files whose object changed upstream. */
   refresh: z8.boolean().optional(),
   /** Put recorded outputs back on disk from the cache or the provider, without generating. */
-  restore: z8.boolean().optional()
-}).strict().refine((request) => [request.resume, request.refresh, request.restore].filter(Boolean).length <= 1, {
-  message: "resume, refresh, and restore are exclusive"
-});
+  restore: z8.boolean().optional(),
+  /**
+   * Bring a replaced generation back: 1-based position in the record's
+   * history (newest first) or an output hash prefix. One key at a time.
+   */
+  revert: z8.string().min(1).max(64).optional()
+}).strict().refine((request) => [request.resume, request.refresh, request.restore, request.revert !== void 0].filter(Boolean).length <= 1, {
+  message: "resume, refresh, restore, and revert are exclusive"
+}).refine((request) => request.revert === void 0 || request.keys.length === 1, { message: "revert takes one key" });
 var GenerateRequestError = class extends Error {
   constructor(message6, status = 400) {
     super(message6);
@@ -11928,6 +12295,22 @@ function createGenerateHandlers(opts) {
         await restore(job, ctx, specs);
         return;
       }
+      if (job.mode === "revert") {
+        job.phase = "fetching";
+        const spec = specs[0];
+        const entry = ctx.lock.entries[lockKey(spec.styleId, spec.assetId)];
+        const provider = opts.providerFor(job.project ?? void 0, entry.provider);
+        const result = await revertGeneration(provider, spec, ctx.lock, ctx.lockPath, {
+          generation: job.revert,
+          force: job.force,
+          onProgress: (line) => say(job, line)
+        });
+        job.counts.downloaded += result.downloaded;
+        say(job, `restored generation #${result.index}${result.restored.objectId ? ` (${result.restored.objectId})` : ""}; the replaced one is now #1 in its history`);
+        job.phase = "done";
+        job.finishedAt = now().toISOString();
+        return;
+      }
       if (job.mode === "generate") {
         job.phase = "submitting";
         for (const group of groups) {
@@ -11998,8 +12381,13 @@ function createGenerateHandlers(opts) {
           }
         }
       }
+      if (request.revert !== void 0) {
+        const entry = ctx.lock.entries[request.keys[0]];
+        if (!entry?.history?.length) throw new GenerateRequestError(`"${request.keys[0]}" has no previous generation recorded`);
+        if (entry.status !== "downloaded") throw new GenerateRequestError(`"${request.keys[0]}" is ${entry.status}; finish or fetch the current generation first`);
+      }
       let groups = [];
-      if (!request.resume && !request.refresh && !request.restore) {
+      if (!request.resume && !request.refresh && !request.restore && request.revert === void 0) {
         const plan = await buildPlan(specs, ctx.lock, { force: request.force });
         if (!plan.actionable.length) {
           const reasons = plan.items.map((item) => `${item.key}: ${item.state} \u2014 ${item.reason}`).slice(0, 5);
@@ -12019,8 +12407,9 @@ function createGenerateHandlers(opts) {
         id: randomBytes2(8).toString("hex"),
         project: request.project ?? null,
         keys: request.keys,
-        mode: request.refresh ? "refresh" : request.resume ? "resume" : request.restore ? "restore" : "generate",
+        mode: request.refresh ? "refresh" : request.resume ? "resume" : request.restore ? "restore" : request.revert !== void 0 ? "revert" : "generate",
         force: Boolean(request.force),
+        revert: request.revert ?? null,
         phase: "queued",
         startedAt: now().toISOString(),
         finishedAt: null,
@@ -12032,7 +12421,7 @@ function createGenerateHandlers(opts) {
       };
       jobs.set(job.id, job);
       contexts.set(job.id, ctx);
-      say(job, request.refresh ? `checking ${request.keys.length} asset(s) upstream at no cost` : request.restore ? `restoring ${request.keys.length} asset(s) at no cost${request.force ? " (replacing modified files)" : ""}` : request.resume ? `resuming ${request.keys.length} asset(s) at no cost` : `generating ${groups.reduce((n, g) => n + g.actionable.length, 0)} asset(s): ` + groups.map((g) => `${g.provider} ${formatCost(g.costUnit, g.cost)}`).join("; "));
+      say(job, request.refresh ? `checking ${request.keys.length} asset(s) upstream at no cost` : request.restore ? `restoring ${request.keys.length} asset(s) at no cost${request.force ? " (replacing modified files)" : ""}` : request.revert !== void 0 ? `bringing back generation ${request.revert} of ${request.keys[0]} at no cost` : request.resume ? `resuming ${request.keys.length} asset(s) at no cost` : `generating ${groups.reduce((n, g) => n + g.actionable.length, 0)} asset(s): ` + groups.map((g) => `${g.provider} ${formatCost(g.costUnit, g.cost)}`).join("; "));
       void run(job, ctx, specs, groups);
       return job;
     },
@@ -12083,14 +12472,14 @@ function createGenerateHandlers(opts) {
 
 // src/gallery/editor.ts
 import { readFile as readFile19 } from "fs/promises";
-import path24 from "path";
+import path25 from "path";
 
 // src/editor/install.ts
 import { createHash as createHash4 } from "crypto";
-import { existsSync as existsSync19 } from "fs";
+import { existsSync as existsSync20 } from "fs";
 import { mkdir as mkdir7, readFile as readFile18, rename as rename8, rm as rm9, stat as stat4, writeFile as writeFile10 } from "fs/promises";
 import os2 from "os";
-import path23 from "path";
+import path24 from "path";
 
 // tools/pixelorama-bridge/pin.json
 var pin_default = {
@@ -12154,15 +12543,15 @@ var EditorInstallError = class extends Error {
 };
 function editorToolsRoot() {
   const override = process.env.PIXELKILN_TOOLS_DIR?.trim();
-  if (override) return path23.resolve(override);
-  if (process.platform === "darwin") return path23.join(os2.homedir(), "Library", "Caches", "pixelkiln", "tools");
+  if (override) return path24.resolve(override);
+  if (process.platform === "darwin") return path24.join(os2.homedir(), "Library", "Caches", "pixelkiln", "tools");
   if (process.platform === "win32") {
-    return path23.join(process.env.LOCALAPPDATA ?? path23.join(os2.homedir(), "AppData", "Local"), "pixelkiln", "tools");
+    return path24.join(process.env.LOCALAPPDATA ?? path24.join(os2.homedir(), "AppData", "Local"), "pixelkiln", "tools");
   }
-  return path23.join(process.env.XDG_CACHE_HOME ?? path23.join(os2.homedir(), ".cache"), "pixelkiln", "tools");
+  return path24.join(process.env.XDG_CACHE_HOME ?? path24.join(os2.homedir(), ".cache"), "pixelkiln", "tools");
 }
 function editorDir(pin = EDITOR_PIN, root = editorToolsRoot()) {
-  return path23.join(root, "pixelorama", pin.release ?? "unpublished");
+  return path24.join(root, "pixelorama", pin.release ?? "unpublished");
 }
 function editorBaseUrl(pin = EDITOR_PIN) {
   const override = process.env.PIXELKILN_EDITOR_URL?.trim();
@@ -12185,8 +12574,8 @@ async function editorStatus(opts = {}) {
   let totalBytes = 0;
   for (const [name, expected] of Object.entries(pin.files)) {
     totalBytes += expected.bytes;
-    const file = path23.join(dir, name);
-    const info = existsSync19(file) ? await stat4(file).catch(() => null) : null;
+    const file = path24.join(dir, name);
+    const info = existsSync20(file) ? await stat4(file).catch(() => null) : null;
     if (info && info.size === expected.bytes && await sha256Of(file) === expected.sha256) {
       installedBytes += expected.bytes;
     } else {
@@ -12243,7 +12632,7 @@ async function installEditor(opts = {}) {
     if (digest2 !== expected.sha256) {
       throw new EditorInstallError(`${name}: sha256 ${digest2.slice(0, 12)}\u2026 does not match the pinned ${expected.sha256.slice(0, 12)}\u2026`, name);
     }
-    const final = path23.join(dir, name);
+    const final = path24.join(dir, name);
     const tmp = `${final}.${process.pid}.part`;
     try {
       await writeFile10(tmp, bytes);
@@ -12289,7 +12678,7 @@ var EDITOR_CONTENT_TYPES = {
   ".json": "application/json; charset=utf-8"
 };
 function editorContentType(name) {
-  return EDITOR_CONTENT_TYPES[path23.extname(name).toLowerCase()] ?? null;
+  return EDITOR_CONTENT_TYPES[path24.extname(name).toLowerCase()] ?? null;
 }
 
 // src/gallery/editor.ts
@@ -12365,7 +12754,7 @@ function createGalleryEditorHandlers(opts = {}) {
       if (!status.installed) return null;
       let bytes;
       try {
-        bytes = await readFile19(path24.join(dir, name));
+        bytes = await readFile19(path25.join(dir, name));
       } catch {
         verified = null;
         return null;
@@ -12381,15 +12770,15 @@ function createGalleryEditorHandlers(opts = {}) {
 
 // src/pipeline/salvage.ts
 import { readFile as readFile20 } from "fs/promises";
-import { existsSync as existsSync20 } from "fs";
-import path25 from "path";
+import { existsSync as existsSync21 } from "fs";
+import path26 from "path";
 function providerClaimId(provider, objectId) {
   return `${encodeURIComponent(provider)}:${encodeURIComponent(objectId)}`;
 }
 async function loadClaims(lockPaths, opts = {}) {
   const claimed = /* @__PURE__ */ new Set();
   for (const p of lockPaths) {
-    if (!existsSync20(p)) throw new Error(`Claim lockfile not found: ${p}`);
+    if (!existsSync21(p)) throw new Error(`Claim lockfile not found: ${p}`);
     let parsed;
     try {
       parsed = parseLock(JSON.parse(await readFile20(p, "utf8")));
@@ -12440,20 +12829,20 @@ function matchStyleByPattern(prompt, manifest) {
   return null;
 }
 async function loadSiblingManifests(ownManifestPath, workspaceManifestPaths, claimPaths) {
-  const own = path25.resolve(ownManifestPath);
+  const own = path26.resolve(ownManifestPath);
   const siblingManifestPaths = [
     .../* @__PURE__ */ new Set([
       ...workspaceManifestPaths,
-      ...claimPaths.map((c) => path25.join(path25.dirname(path25.resolve(c)), "pixelkiln.manifest.json"))
+      ...claimPaths.map((c) => path26.join(path26.dirname(path26.resolve(c)), "pixelkiln.manifest.json"))
     ])
   ];
   const siblings = [];
   for (const siblingManifestPath of siblingManifestPaths) {
-    if (path25.resolve(siblingManifestPath) === own) continue;
-    if (!existsSync20(siblingManifestPath)) continue;
+    if (path26.resolve(siblingManifestPath) === own) continue;
+    if (!existsSync21(siblingManifestPath)) continue;
     try {
       const { manifest } = await loadManifest(siblingManifestPath);
-      siblings.push({ label: path25.basename(path25.dirname(siblingManifestPath)), manifest });
+      siblings.push({ label: path26.basename(path26.dirname(siblingManifestPath)), manifest });
     } catch {
     }
   }
@@ -12672,18 +13061,16 @@ async function workspaceStatus(ws, dir) {
 }
 
 // src/pipeline/cache-health.ts
-import { existsSync as existsSync21 } from "fs";
+import { existsSync as existsSync22 } from "fs";
 import { readFile as readFile21, readdir as readdir2, rm as rm10 } from "fs/promises";
-import path26 from "path";
+import path27 from "path";
 async function inspectCaches(lock, lockPath, options = {}) {
-  if (options.prune && !existsSync21(lockPath)) {
-    throw new Error(`Refusing to prune without an existing lockfile at ${path26.resolve(lockPath)}`);
+  if (options.prune && !existsSync22(lockPath)) {
+    throw new Error(`Refusing to prune without an existing lockfile at ${path27.resolve(lockPath)}`);
   }
-  const contentDir = path26.resolve(path26.dirname(lockPath), ".pixelkiln", "cache");
-  const remotePath = path26.resolve(cachePathFor(lockPath));
-  const referenced = new Set(
-    Object.values(lock.entries).flatMap((entry) => entry.outputs.map((output) => output.sha256))
-  );
+  const contentDir = path27.resolve(path27.dirname(lockPath), ".pixelkiln", "cache");
+  const remotePath = path27.resolve(cachePathFor(lockPath));
+  const referenced = referencedHashes(lock);
   let content = await inspectContentCache(contentDir, referenced);
   let remoteHashes = await inspectRemoteHashCache(remotePath);
   const removed = { contentFiles: 0, remoteHashEntries: 0, resetRemoteHashCache: false };
@@ -12694,7 +13081,7 @@ async function inspectCaches(lock, lockPath, options = {}) {
     ]);
     for (const name of names) {
       try {
-        await rm10(path26.join(contentDir, name), { force: true });
+        await rm10(path27.join(contentDir, name), { force: true });
         removed.contentFiles++;
       } catch {
       }
@@ -12721,7 +13108,7 @@ async function inspectCaches(lock, lockPath, options = {}) {
 async function inspectContentCache(contentDir, referenced) {
   const report = {
     path: contentDir,
-    exists: existsSync21(contentDir),
+    exists: existsSync22(contentDir),
     files: 0,
     bytes: 0,
     valid: 0,
@@ -12742,7 +13129,7 @@ async function inspectContentCache(contentDir, referenced) {
       continue;
     }
     report.files++;
-    const file = path26.join(contentDir, entry.name);
+    const file = path27.join(contentDir, entry.name);
     const mediaType = mediaTypeFromExtension(entry.name);
     const expected = mediaType ? entry.name.slice(0, -4) : "";
     let bytes;
@@ -12785,7 +13172,7 @@ async function inspectContentCache(contentDir, referenced) {
 async function inspectRemoteHashCache(remotePath) {
   const report = {
     path: remotePath,
-    exists: existsSync21(remotePath),
+    exists: existsSync22(remotePath),
     entries: 0,
     valid: 0,
     invalidIds: [],
@@ -13069,7 +13456,7 @@ function isRecord2(value) {
 
 // src/pick/salvage-server.ts
 import { mkdir as mkdir8, writeFile as writeFile11, readFile as readFile22 } from "fs/promises";
-import path27 from "path";
+import path28 from "path";
 
 // src/pick/salvage-sheet.ts
 var escapeHtml3 = (s) => s.replace(/[&<>"']/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[c]);
@@ -13234,7 +13621,7 @@ async function runSalvage(provider, orphans, ctx, opts = {}) {
   });
   const html = renderSalvageSheet(orphans, {
     styleId: ctx.styleId,
-    importDir: path27.relative(process.cwd(), ctx.importDir) || "."
+    importDir: path28.relative(process.cwd(), ctx.importDir) || "."
   });
   const byId = new Map(orphans.map((o) => [o.id, o]));
   const existingTags = new Map(orphans.map((o) => [o.id, o.tags]));
@@ -13263,9 +13650,9 @@ async function runSalvage(provider, orphans, ctx, opts = {}) {
             if (!buf.subarray(0, 8).equals(PNG_SIGNATURE2)) throw new Error("not a PNG");
             decodePng(buf);
             const assetId = idFromPrompt(orphan.prompt, taken);
-            const rel = path27.join("_salvaged", `${assetId}.png`);
-            const outFile = path27.resolve(ctx.importDir, rel);
-            await mkdir8(path27.dirname(outFile), { recursive: true });
+            const rel = path28.join("_salvaged", `${assetId}.png`);
+            const outFile = path28.resolve(ctx.importDir, rel);
+            await mkdir8(path28.dirname(outFile), { recursive: true });
             await writeFile11(outFile, buf);
             ctx.manifest.assets[assetId] = {
               prompt: orphan.prompt,
@@ -13298,7 +13685,7 @@ async function runSalvage(provider, orphans, ctx, opts = {}) {
               sourceUrl: durableSource,
               sourceUrls: durableSource ? [{ url: durableSource }] : [],
               outputs: [{
-                path: portableOutputPath(outFile, path27.dirname(ctx.manifestPath)),
+                path: portableOutputPath(outFile, path28.dirname(ctx.manifestPath)),
                 sha256: sha256(buf)
               }],
               submittedAt: orphan.createdAt,
@@ -13332,8 +13719,8 @@ async function runSalvage(provider, orphans, ctx, opts = {}) {
 }
 
 // src/recipes.ts
-import path28 from "path";
-import { existsSync as existsSync22 } from "fs";
+import path29 from "path";
+import { existsSync as existsSync23 } from "fs";
 import { readdir as readdir3, readFile as readFile23 } from "fs/promises";
 import { fileURLToPath } from "url";
 import { z as z9 } from "zod";
@@ -13343,7 +13730,7 @@ var VERSION_RE = /^\d+\.\d+\.\d+$/;
 var RECIPE_FILE = "pixelkiln.recipe.json";
 var RECIPE_DIR_TOKEN = "{{recipeDir}}";
 var PortablePathSchema = z9.string().min(1).refine((value) => {
-  if (value.includes("\\") || path28.posix.isAbsolute(value)) return false;
+  if (value.includes("\\") || path29.posix.isAbsolute(value)) return false;
   const parts = value.split("/");
   return !parts.includes("") && !parts.includes(".") && !parts.includes("..");
 }, "expected a portable relative path without '.', '..', or backslashes");
@@ -13519,7 +13906,7 @@ function message4(error) {
   return error instanceof Error ? error.message : String(error);
 }
 async function readRecipeFile(recipePath, bundled) {
-  const absolute = path28.resolve(recipePath);
+  const absolute = path29.resolve(recipePath);
   let raw;
   try {
     raw = JSON.parse(await readFile23(absolute, "utf8"));
@@ -13533,13 +13920,13 @@ async function readRecipeFile(recipePath, bundled) {
 ` + parsed.error.issues.map((issue) => `  ${issue.path.join(".") || "$"}: ${issue.message}`).join("\n")
     );
   }
-  return { recipe: parsed.data, path: absolute, dir: path28.dirname(absolute), bundled };
+  return { recipe: parsed.data, path: absolute, dir: path29.dirname(absolute), bundled };
 }
 async function walkRecipeFiles(root) {
-  if (!existsSync22(root)) return [];
+  if (!existsSync23(root)) return [];
   const out = [];
   for (const entry of await readdir3(root, { withFileTypes: true })) {
-    const resolved = path28.join(root, entry.name);
+    const resolved = path29.join(root, entry.name);
     if (entry.isDirectory()) out.push(...await walkRecipeFiles(resolved));
     else if (entry.isFile() && entry.name === RECIPE_FILE) out.push(resolved);
   }
@@ -13550,7 +13937,7 @@ function bundledRecipeRoot() {
 }
 async function listBundledRecipes(root = bundledRecipeRoot()) {
   const recipes = await Promise.all(
-    (await walkRecipeFiles(path28.resolve(root))).map((file) => readRecipeFile(file, true))
+    (await walkRecipeFiles(path29.resolve(root))).map((file) => readRecipeFile(file, true))
   );
   return recipes.sort(
     (a, b) => a.recipe.id.localeCompare(b.recipe.id) || compareVersions(b.recipe.version, a.recipe.version)
@@ -13573,9 +13960,9 @@ function parseSelector(selector) {
   return { id: match[1], version: match[2] };
 }
 async function resolveRecipe(target, bundledRoot = bundledRecipeRoot()) {
-  const local = path28.resolve(target);
-  if (existsSync22(local)) {
-    const recipePath = path28.basename(local) === RECIPE_FILE ? local : path28.join(local, RECIPE_FILE);
+  const local = path29.resolve(target);
+  if (existsSync23(local)) {
+    const recipePath = path29.basename(local) === RECIPE_FILE ? local : path29.join(local, RECIPE_FILE);
     return readRecipeFile(recipePath, false);
   }
   if (target.startsWith(".") || target.startsWith("/") || target.includes("\\")) {
@@ -13589,8 +13976,8 @@ async function resolveRecipe(target, bundledRoot = bundledRecipeRoot()) {
   return matches[0];
 }
 async function verifyFile(root, file) {
-  const absolute = path28.resolve(root, ...file.path.split("/"));
-  if (!existsSync22(absolute)) {
+  const absolute = path29.resolve(root, ...file.path.split("/"));
+  if (!existsSync23(absolute)) {
     return { path: file.path, expectedSha256: file.sha256, actualSha256: null, status: "missing" };
   }
   const actualSha256 = await sha256File(absolute);
@@ -13605,7 +13992,7 @@ async function verifyRecipe(target, options = {}) {
   const loaded = await resolveRecipe(target, options.bundledRoot);
   const actualIntegrity = recipeDigest(loaded.recipe);
   const files = await Promise.all(loaded.recipe.files.map((file) => verifyFile(loaded.dir, file)));
-  const modelRoot = options.modelRoot ? path28.resolve(options.modelRoot) : null;
+  const modelRoot = options.modelRoot ? path29.resolve(options.modelRoot) : null;
   const models = modelRoot ? await Promise.all(loaded.recipe.models.map(async (model) => ({
     ...await verifyFile(modelRoot, model),
     source: model.source,
@@ -13639,7 +14026,7 @@ async function verifyRecipe(target, options = {}) {
   };
 }
 function renderStyle(style, destination, cwd) {
-  const portableDir = path28.relative(cwd, destination).split(path28.sep).join("/") || ".";
+  const portableDir = path29.relative(cwd, destination).split(path29.sep).join("/") || ".";
   const replace = (value) => {
     if (typeof value === "string") return value.replaceAll(RECIPE_DIR_TOKEN, portableDir);
     if (Array.isArray(value)) return value.map(replace);
@@ -13651,24 +14038,24 @@ function renderStyle(style, destination, cwd) {
   return replace(style);
 }
 async function installRecipe(target, options = {}) {
-  const cwd = path28.resolve(options.cwd ?? process.cwd());
+  const cwd = path29.resolve(options.cwd ?? process.cwd());
   const loaded = await resolveRecipe(target, options.bundledRoot);
   const verification = await verifyRecipe(loaded.path);
   if (!verification.ok) {
     throw new Error(`Recipe ${loaded.recipe.id}@${loaded.recipe.version} failed integrity verification.`);
   }
-  const destination = options.out ? path28.resolve(cwd, options.out) : path28.join(cwd, "pixelkiln-recipes", ...loaded.recipe.id.split("/"), loaded.recipe.version);
+  const destination = options.out ? path29.resolve(cwd, options.out) : path29.join(cwd, "pixelkiln-recipes", ...loaded.recipe.id.split("/"), loaded.recipe.version);
   const sources = [
     { path: RECIPE_FILE, source: loaded.path },
-    ...loaded.recipe.files.map((file) => ({ path: file.path, source: path28.join(loaded.dir, ...file.path.split("/")) }))
+    ...loaded.recipe.files.map((file) => ({ path: file.path, source: path29.join(loaded.dir, ...file.path.split("/")) }))
   ];
   const files = await Promise.all(sources.map(async (file) => ({
-    path: path28.join(destination, ...file.path.split("/")),
+    path: path29.join(destination, ...file.path.split("/")),
     data: await readFile23(file.source)
   })));
   if (!options.force) {
     for (const file of files) {
-      if (!existsSync22(file.path)) continue;
+      if (!existsSync23(file.path)) continue;
       const current = await readFile23(file.path);
       if (!current.equals(file.data)) {
         throw new Error(
@@ -13692,15 +14079,15 @@ async function installRecipe(target, options = {}) {
 }
 
 // src/pipeline/quality-regression.ts
-import path29 from "path";
-import { existsSync as existsSync23 } from "fs";
+import path30 from "path";
+import { existsSync as existsSync24 } from "fs";
 import { readFile as readFile24 } from "fs/promises";
 import { z as z10 } from "zod";
 var SHA256_RE2 = /^[0-9a-f]{64}$/;
 var HEX_RE = /^#[0-9a-f]{6}$/;
 var MAX_REDMEAN_DISTANCE = 765;
 var QualityPathSchema = z10.string().min(1).refine(
-  (value) => !path29.posix.isAbsolute(value) && !value.includes("\\"),
+  (value) => !path30.posix.isAbsolute(value) && !value.includes("\\"),
   "expected a portable relative path"
 );
 var DEFAULT_QUALITY_TOLERANCES = {
@@ -13847,7 +14234,7 @@ function measureDecodedImageQuality(png, digest2) {
   };
 }
 async function measureImageQuality(file) {
-  const absolute = path29.resolve(file);
+  const absolute = path30.resolve(file);
   let bytes;
   try {
     bytes = await readFile24(absolute);
@@ -13869,11 +14256,11 @@ function resolveQualityInputs(raw, inputsFilePath) {
   }
   const ids = parsed.data.map((entry) => entry.id);
   if (new Set(ids).size !== ids.length) throw new Error("--inputs contains a duplicate quality case id.");
-  const root = path29.dirname(path29.resolve(inputsFilePath));
+  const root = path30.dirname(path30.resolve(inputsFilePath));
   return parsed.data.map((entry) => ({
     id: entry.id,
-    file: path29.resolve(root, entry.path),
-    ...entry.record ? { record: path29.resolve(root, entry.record) } : {},
+    file: path30.resolve(root, entry.path),
+    ...entry.record ? { record: path30.resolve(root, entry.record) } : {},
     tolerances: QualityToleranceSchema.parse({
       ...DEFAULT_QUALITY_TOLERANCES,
       ...entry.tolerances
@@ -13881,7 +14268,7 @@ function resolveQualityInputs(raw, inputsFilePath) {
   }));
 }
 function portableRelative2(from, to) {
-  return path29.relative(from, path29.resolve(to)).split(path29.sep).join("/") || ".";
+  return path30.relative(from, path30.resolve(to)).split(path30.sep).join("/") || ".";
 }
 async function verifyRecordForImage(recordPath, imagePath) {
   const verification = await verifyArtifactBundle(recordPath);
@@ -13896,20 +14283,20 @@ async function verifyRecordForImage(recordPath, imagePath) {
   if (record.kind !== "refine" || options === null || typeof options !== "object" || options.schema !== "pixelkiln-quality") {
     throw new Error(`Quality record ${recordPath} is not a PixelKiln refinement record.`);
   }
-  const outputs = record.outputs.map((output) => path29.resolve(path29.dirname(recordPath), output.path));
-  if (!outputs.includes(path29.resolve(imagePath))) {
+  const outputs = record.outputs.map((output) => path30.resolve(path30.dirname(recordPath), output.path));
+  if (!outputs.includes(path30.resolve(imagePath))) {
     throw new Error(`Quality record ${recordPath} does not own ${imagePath}.`);
   }
 }
 async function snapshotQualityBaseline(inputs, baselinePath, options = {}) {
   if (!inputs.length) throw new Error("Cannot snapshot an empty quality baseline.");
-  const absolute = path29.resolve(baselinePath);
+  const absolute = path30.resolve(baselinePath);
   for (const input of inputs) {
-    if (path29.resolve(input.file) === absolute || input.record && path29.resolve(input.record) === absolute) {
+    if (path30.resolve(input.file) === absolute || input.record && path30.resolve(input.record) === absolute) {
       throw new Error(`Quality baseline output would overwrite an input: ${absolute}.`);
     }
   }
-  const root = path29.dirname(absolute);
+  const root = path30.dirname(absolute);
   const cases = [];
   for (const input of [...inputs].sort((a, b) => a.id.localeCompare(b.id))) {
     const expected = await measureImageQuality(input.file);
@@ -13936,7 +14323,7 @@ async function snapshotQualityBaseline(inputs, baselinePath, options = {}) {
     cases
   });
   const data = Buffer.from(JSON.stringify(baseline, null, 2) + "\n");
-  if (existsSync23(absolute) && !options.force) {
+  if (existsSync24(absolute) && !options.force) {
     const current = await readFile24(absolute);
     if (!current.equals(data)) {
       throw new Error(`Quality baseline already exists with different content: ${absolute}. Pass --force to replace it.`);
@@ -13946,7 +14333,7 @@ async function snapshotQualityBaseline(inputs, baselinePath, options = {}) {
   return { baseline, path: absolute, changed: result.changed.length > 0 };
 }
 async function readQualityBaseline(baselinePath) {
-  const absolute = path29.resolve(baselinePath);
+  const absolute = path30.resolve(baselinePath);
   let raw;
   try {
     raw = JSON.parse(await readFile24(absolute, "utf8"));
@@ -14019,12 +14406,12 @@ function regressionViolations(expected, actual, tolerances) {
   return { violations, warnings };
 }
 async function checkQualityBaseline(baselinePath) {
-  const absolute = path29.resolve(baselinePath);
+  const absolute = path30.resolve(baselinePath);
   const baseline = await readQualityBaseline(absolute);
-  const root = path29.dirname(absolute);
+  const root = path30.dirname(absolute);
   const cases = [];
   for (const entry of baseline.cases) {
-    const file = path29.resolve(root, entry.file);
+    const file = path30.resolve(root, entry.file);
     let actual = null;
     const violations = [];
     const warnings = [];
@@ -14037,7 +14424,7 @@ async function checkQualityBaseline(baselinePath) {
       violations.push(message5(error));
     }
     if (entry.record) {
-      const recordPath = path29.resolve(root, entry.record.path);
+      const recordPath = path30.resolve(root, entry.record.path);
       try {
         const recordHash = await sha256File(recordPath);
         if (recordHash !== entry.record.sha256) violations.push("quality record hash changed");
@@ -14123,13 +14510,13 @@ async function runGallery(initial, reload, args, access2) {
   };
   const loadProject = async (project) => {
     const ctx = await access2.loadProject(project);
-    const dir = path30.dirname(ctx.loaded.path);
+    const dir = path31.dirname(ctx.loaded.path);
     const declared = readEnvFiles(dir);
     const credentialNames = new Set(availableProviders().flatMap((id) => providerCredentialEnvs(providerFactory(id))));
     for (const [name, value] of Object.entries(declared)) {
       if (credentialNames.has(name) && name in process.env && process.env[name] !== value) {
         throw new Error(
-          `${path30.relative(process.cwd(), dir) || "."} sets ${name} to a different value than the one this gallery already loaded; run a separate gallery for that project so its work uses its own account.`
+          `${path31.relative(process.cwd(), dir) || "."} sets ${name} to a different value than the one this gallery already loaded; run a separate gallery for that project so its work uses its own account.`
         );
       }
     }
@@ -14173,11 +14560,11 @@ async function runGallery(initial, reload, args, access2) {
   log("\n  gallery closed");
 }
 async function provenanceFile(id, file) {
-  const absolute = path30.resolve(file);
+  const absolute = path31.resolve(file);
   return {
     id,
     path: absolute,
-    sha256: existsSync24(absolute) ? await sha256File(absolute) : null,
+    sha256: existsSync25(absolute) ? await sha256File(absolute) : null,
     included: true
   };
 }
@@ -14211,7 +14598,8 @@ var VALUE_FLAGS = [
   "--min-grid-confidence",
   "--reviewer",
   "--note",
-  "--model-root"
+  "--model-root",
+  "--generation"
 ];
 var BOOL_FLAGS = [
   "--force",
@@ -14256,6 +14644,7 @@ var COMMANDS = [
   "gallery",
   "edit",
   "tools",
+  "history",
   "quality",
   "refine",
   "recipe",
@@ -14465,7 +14854,7 @@ function parseArgs(argv) {
   return {
     command,
     manifest,
-    lock: get("--lock") ?? path30.join(path30.dirname(path30.resolve(manifest)), "pixelkiln.lock.json"),
+    lock: get("--lock") ?? path31.join(path31.dirname(path31.resolve(manifest)), "pixelkiln.lock.json"),
     explicitLock: get("--lock"),
     styles: list("--style"),
     assets: list("--only"),
@@ -14507,6 +14896,7 @@ function parseArgs(argv) {
     reviewer: get("--reviewer"),
     note: get("--note"),
     modelRoot: get("--model-root"),
+    generation: get("--generation"),
     subcommand,
     workspace: get("--workspace"),
     target,
@@ -14566,7 +14956,9 @@ Commands
   poll      Advance in-flight jobs to their settled state.
   pick      Open the contact sheet to choose among candidates.
   fetch     Download selected objects to their manifest paths.
-  restore   Re-download missing generated files without generating new art.
+  restore   Re-download missing generated files without generating new art;
+            --generation <n|hash> brings a previous generation back instead.
+  history   List the generations each asset has replaced and can restore.
   adopt     Match existing account objects to files already in the repo.
   accept    Keep existing art after a style reword \u2014 re-baseline, do not regenerate.
   salvage   Triage account objects no lockfile claims. Recovers usable art.
@@ -14620,6 +15012,7 @@ Options
   --reviewer <name>   refine approve: human reviewer recorded in provenance
   --note <text>       refine approve: optional review note
   --model-root <dir>  recipe verify: also hash required local model files
+  --generation <n|hash>  restore: the previous generation to bring back (1 = newest)
   --prune             cache: remove invalid/unreferenced local cache data
   --manifest <path>   Default: pixelkiln.manifest.json
   --lock <path>       Default: pixelkiln.lock.json beside the manifest
@@ -14817,10 +15210,10 @@ async function confirm(question, auto) {
   return answer === "y" || answer === "yes";
 }
 async function requireCompleteWorkspaceClaims(workspacePath) {
-  if (!existsSync24(workspacePath)) {
+  if (!existsSync25(workspacePath)) {
     throw new Error(`Workspace catalog not found: ${workspacePath}`);
   }
-  const dir = path30.dirname(path30.resolve(workspacePath));
+  const dir = path31.dirname(path31.resolve(workspacePath));
   const ws = await loadWorkspace(workspacePath);
   const diagnostics = validateWorkspace(ws, dir);
   const errors = diagnostics.filter((d) => d.level === "error");
@@ -14856,15 +15249,15 @@ async function main() {
       if (!args.out) throw new Error("quality snapshot needs --out <pixelkiln.quality.json>.");
       let raw;
       try {
-        raw = JSON.parse(await readFile25(path30.resolve(args.inputs), "utf8"));
+        raw = JSON.parse(await readFile25(path31.resolve(args.inputs), "utf8"));
       } catch (error) {
         throw new Error(
-          `Could not read quality inputs ${path30.resolve(args.inputs)}: ${error instanceof Error ? error.message : String(error)}`,
+          `Could not read quality inputs ${path31.resolve(args.inputs)}: ${error instanceof Error ? error.message : String(error)}`,
           { cause: error }
         );
       }
       const inputs = resolveQualityInputs(raw, args.inputs);
-      if (path30.resolve(args.inputs) === path30.resolve(args.out)) {
+      if (path31.resolve(args.inputs) === path31.resolve(args.out)) {
         throw new Error("quality snapshot --out must not overwrite its --inputs file.");
       }
       const result = await snapshotQualityBaseline(inputs, args.out, { force: args.force });
@@ -14877,7 +15270,7 @@ async function main() {
         }, null, 2));
       } else {
         log(
-          `  ${result.changed ? "wrote" : "unchanged"} ${path30.relative(process.cwd(), result.path)} (${result.baseline.cases.length} case(s))`
+          `  ${result.changed ? "wrote" : "unchanged"} ${path31.relative(process.cwd(), result.path)} (${result.baseline.cases.length} case(s))`
         );
         log(`  Review the tolerances, commit the baseline, then run quality check in CI.`);
       }
@@ -14972,14 +15365,14 @@ async function main() {
         }, null, 2));
       } else {
         log(`  installed ${result.recipe.id}@${result.recipe.version}`);
-        log(`  ${path30.relative(process.cwd(), result.destination) || "."}`);
+        log(`  ${path31.relative(process.cwd(), result.destination) || "."}`);
         log(`
   Add this entry under your manifest's styles object:`);
         log(JSON.stringify({ [result.styleId]: result.style }, null, 2));
         if (result.recipe.models.length) {
           log(`
   Models are not downloaded automatically. Verify them with:`);
-          log(`  pixelkiln recipe verify ${path30.relative(process.cwd(), result.destination)} --model-root <ComfyUI/models>`);
+          log(`  pixelkiln recipe verify ${path31.relative(process.cwd(), result.destination)} --model-root <ComfyUI/models>`);
         }
       }
       return;
@@ -15013,12 +15406,12 @@ async function main() {
           `  recovered ${result2.detection.columns}x${result2.detection.rows} native grid (${result2.detection.confidence}: ${result2.detection.consensus})`
         );
         log(`  enforced ${result2.palette.length}-color palette without dithering`);
-        log(`  wrote ${path30.relative(process.cwd(), result2.output)}`);
-        log(`  quality record: ${path30.relative(process.cwd(), result2.record)}`);
+        log(`  wrote ${path31.relative(process.cwd(), result2.output)}`);
+        log(`  quality record: ${path31.relative(process.cwd(), result2.record)}`);
         log(`
   Automated checks passed. Human 1\xD7 review is still required:`);
         log(
-          `    pixelkiln refine approve --from ${path30.relative(process.cwd(), result2.record)} --reviewer "Your Name"`
+          `    pixelkiln refine approve --from ${path31.relative(process.cwd(), result2.record)} --reviewer "Your Name"`
         );
       }
       return;
@@ -15046,7 +15439,7 @@ async function main() {
       if (args.json) log(JSON.stringify(result2, null, 2));
       else {
         log(
-          result2.options.frameSet ? `  approved ${result2.outputs.length} frames in ${path30.relative(process.cwd(), result2.record)} by ${args.reviewer.trim()}` : `  approved ${path30.relative(process.cwd(), result2.output)} by ${args.reviewer.trim()}`
+          result2.options.frameSet ? `  approved ${result2.outputs.length} frames in ${path31.relative(process.cwd(), result2.record)} by ${args.reviewer.trim()}` : `  approved ${path31.relative(process.cwd(), result2.output)} by ${args.reviewer.trim()}`
         );
       }
       return;
@@ -15055,14 +15448,14 @@ async function main() {
     if (args.json) {
       log(JSON.stringify(result, null, 2));
     } else {
-      log(`  ${result.safe ? "release-ready" : "not release-ready"}: ${path30.relative(process.cwd(), result.output || result.record)}`);
+      log(`  ${result.safe ? "release-ready" : "not release-ready"}: ${path31.relative(process.cwd(), result.output || result.record)}`);
       for (const reason of result.reasons) log(`    ${reason}`);
     }
     if (!result.safe) process.exitCode = 1;
     return;
   }
   if (args.command === "balance") {
-    loadEnvFiles(path30.dirname(path30.resolve(args.manifest)));
+    loadEnvFiles(path31.dirname(path31.resolve(args.manifest)));
     loadEnvFiles(process.cwd());
     const loaded2 = await loadManifest(args.manifest);
     const selectedProvider = accountProviderId(loaded2.manifest, args.provider, "balance");
@@ -15075,31 +15468,31 @@ async function main() {
   }
   if (args.command === "init") {
     if (!args.from) throw new Error("init needs --from <dir> pointing at your existing PNGs.");
-    const root = path30.resolve(args.from);
-    if (!existsSync24(root)) throw new Error(`No directory at ${root}`);
+    const root = path31.resolve(args.from);
+    if (!existsSync25(root)) throw new Error(`No directory at ${root}`);
     const generator = args.generator ?? "map";
     if (generator !== "1dir" && generator !== "map") {
       throw new Error(`--generator must be "1dir" or "map", got "${args.generator}".`);
     }
-    const target = path30.resolve(args.out ?? "pixelkiln.manifest.json");
+    const target = path31.resolve(args.out ?? "pixelkiln.manifest.json");
     const { assets, skipped } = await scanAssets(root, { exclude: args.exclude });
     if (!assets.length) throw new Error(`No PNGs found under ${root}`);
     const manifest = buildManifest(
-      args.name ?? path30.basename(path30.dirname(target)),
+      args.name ?? path31.basename(path31.dirname(target)),
       args.styles[0] ?? "base",
       generator,
-      path30.relative(path30.dirname(target), root) || ".",
+      path31.relative(path31.dirname(target), root) || ".",
       assets
     );
     await writeManifestFile(target, manifest);
-    log(`  scanned ${assets.length} PNG(s) under ${path30.relative(process.cwd(), root)}`);
+    log(`  scanned ${assets.length} PNG(s) under ${path31.relative(process.cwd(), root)}`);
     if (skipped.length) log(`  skipped ${skipped.length} unreadable file(s)`);
-    log(`  wrote ${path30.relative(process.cwd(), target)}`);
+    log(`  wrote ${path31.relative(process.cwd(), target)}`);
     log(`
   Prompts are intentionally empty. To recover the real ones from your`);
     log(`  PixelLab account instead of inventing them:`);
     log(`
-    pixelkiln adopt --manifest ${path30.relative(process.cwd(), target)} --write-prompts
+    pixelkiln adopt --manifest ${path31.relative(process.cwd(), target)} --write-prompts
 `);
     return;
   }
@@ -15147,10 +15540,10 @@ async function main() {
     if (args.primaryOnly || args.outputRoles.length) {
       throw new Error("--primary-only and --output-role require manifest-driven pack");
     }
-    const raw = JSON.parse(await readFile25(path30.resolve(args.inputs), "utf8"));
+    const raw = JSON.parse(await readFile25(path31.resolve(args.inputs), "utf8"));
     const inputs = resolvePackInputs(raw, args.inputs);
     const { png, atlas, skipped, sources } = packSprites(inputs, { columns: args.columns });
-    const base = path30.resolve(args.out.replace(/\.png$/, ""));
+    const base = path31.resolve(args.out.replace(/\.png$/, ""));
     const outputs = [
       { path: `${base}.png`, data: png },
       { path: `${base}.json`, data: JSON.stringify(atlas, null, 2) + "\n" }
@@ -15163,17 +15556,17 @@ async function main() {
     log(
       `  ${atlas.frames.length} sprite(s), ${atlas.sheet.width}x${atlas.sheet.height} in ${atlas.columns} column(s) \u2014 ${(png.length / 1024).toFixed(1)} KB`
     );
-    log(`    ${path30.relative(process.cwd(), base)}.png + .json + .pixelkiln.json`);
+    log(`    ${path31.relative(process.cwd(), base)}.png + .json + .pixelkiln.json`);
     for (const s of skipped) log(`    skipped ${s.id}: ${s.reason}`);
     return;
   }
   if (args.command === "workspace") {
-    const workspacePath = path30.resolve(args.workspace ?? "pixelkiln.workspace.json");
-    const dir = path30.dirname(workspacePath);
+    const workspacePath = path31.resolve(args.workspace ?? "pixelkiln.workspace.json");
+    const dir = path31.dirname(workspacePath);
     if (args.subcommand === "add") {
-      const manifestPath = path30.resolve(args.target);
+      const manifestPath = path31.resolve(args.target);
       const loadedTarget = await loadManifest(manifestPath);
-      const lockPath = args.explicitLock ? path30.resolve(args.explicitLock) : path30.join(path30.dirname(manifestPath), "pixelkiln.lock.json");
+      const lockPath = args.explicitLock ? path31.resolve(args.explicitLock) : path31.join(path31.dirname(manifestPath), "pixelkiln.lock.json");
       const ws = await loadWorkspace(workspacePath);
       const id = args.name ?? loadedTarget.manifest.name;
       if (ws.projects.some((p) => p.id === id)) {
@@ -15193,10 +15586,10 @@ async function main() {
         ...args.account ? { account: args.account } : {}
       };
       await saveWorkspace(workspacePath, { version: 1, projects: [...ws.projects, project] });
-      log(`  registered "${id}" in ${path30.relative(process.cwd(), workspacePath)}`);
+      log(`  registered "${id}" in ${path31.relative(process.cwd(), workspacePath)}`);
       log(`    manifest: ${project.manifest}`);
       log(`    lock:     ${project.lock}`);
-      if (!existsSync24(lockPath)) {
+      if (!existsSync25(lockPath)) {
         log(
           `  warning: no lockfile there yet \u2014 this project contributes no claims until one is generated`
         );
@@ -15205,7 +15598,7 @@ async function main() {
     }
     if (args.subcommand === "remove") {
       const ws = await loadWorkspace(workspacePath);
-      const resolvedTarget = path30.resolve(args.target);
+      const resolvedTarget = path31.resolve(args.target);
       const match = ws.projects.find(
         (p) => p.id === args.target || resolveProject(dir, p).manifestPath === resolvedTarget
       );
@@ -15216,11 +15609,11 @@ async function main() {
         version: 1,
         projects: ws.projects.filter((p) => p !== match)
       });
-      log(`  removed "${match.id}" from ${path30.relative(process.cwd(), workspacePath)}`);
+      log(`  removed "${match.id}" from ${path31.relative(process.cwd(), workspacePath)}`);
       return;
     }
     if (args.subcommand === "list") {
-      if (!existsSync24(workspacePath)) {
+      if (!existsSync25(workspacePath)) {
         throw new Error(`Workspace catalog not found: ${workspacePath}`);
       }
       const ws = await loadWorkspace(workspacePath);
@@ -15228,9 +15621,9 @@ async function main() {
       if (args.json) {
         log(JSON.stringify({ version: 1, workspace: workspacePath, projects: ws.projects, diagnostics }, null, 2));
       } else if (!ws.projects.length) {
-        log(`  no projects registered in ${path30.relative(process.cwd(), workspacePath)}`);
+        log(`  no projects registered in ${path31.relative(process.cwd(), workspacePath)}`);
       } else {
-        log(`  ${ws.projects.length} project(s) in ${path30.relative(process.cwd(), workspacePath)}:`);
+        log(`  ${ws.projects.length} project(s) in ${path31.relative(process.cwd(), workspacePath)}:`);
         for (const p of ws.projects) {
           log(`    ${p.id.padEnd(24)} ${p.manifest.padEnd(40)} (${p.provider}${p.account ? `, ${p.account}` : ""})`);
         }
@@ -15240,7 +15633,7 @@ async function main() {
       return;
     }
     if (args.subcommand === "status") {
-      if (!existsSync24(workspacePath)) {
+      if (!existsSync25(workspacePath)) {
         throw new Error(`Workspace catalog not found: ${workspacePath}`);
       }
       const ws = await loadWorkspace(workspacePath);
@@ -15248,7 +15641,7 @@ async function main() {
       if (args.json) {
         log(JSON.stringify({ ...report, workspace: workspacePath }, null, 2));
       } else {
-        log(`  workspace: ${path30.relative(process.cwd(), workspacePath)}`);
+        log(`  workspace: ${path31.relative(process.cwd(), workspacePath)}`);
         for (const p of report.projects) {
           if (p.error) {
             log(`
@@ -15295,8 +15688,8 @@ async function main() {
     }
   }
   if (args.command === "gallery" && args.workspace) {
-    const workspacePath = path30.resolve(args.workspace);
-    if (!existsSync24(workspacePath)) {
+    const workspacePath = path31.resolve(args.workspace);
+    if (!existsSync25(workspacePath)) {
       throw new Error(`Workspace catalog not found: ${workspacePath}`);
     }
     const filter = { styles: args.styles, assets: args.assets };
@@ -15316,7 +15709,7 @@ async function main() {
     const registered = async (projectId) => {
       const project = (await loadWorkspace(workspacePath)).projects.find((candidate) => candidate.id === projectId);
       if (!projectId || !project) throw new Error(`unknown workspace project "${projectId ?? ""}"`);
-      return resolveProject(path30.dirname(workspacePath), project);
+      return resolveProject(path31.dirname(workspacePath), project);
     };
     await runGallery(initial, build, args, {
       manifestFor: async (projectId) => (await registered(projectId)).manifestPath,
@@ -15331,14 +15724,14 @@ async function main() {
     });
     return;
   }
-  if (!existsSync24(path30.resolve(args.manifest))) {
+  if (!existsSync25(path31.resolve(args.manifest))) {
     throw new Error(
-      `No manifest at ${path30.resolve(args.manifest)}. Pass --manifest, or run \`pixelkiln init --from <dir>\`.`
+      `No manifest at ${path31.resolve(args.manifest)}. Pass --manifest, or run \`pixelkiln init --from <dir>\`.`
     );
   }
-  const manifestDir = path30.dirname(path30.resolve(args.manifest));
+  const manifestDir = path31.dirname(path31.resolve(args.manifest));
   const envFiles2 = [...loadEnvFiles(manifestDir)];
-  if (path30.resolve(process.cwd()) !== manifestDir) envFiles2.push(...loadEnvFiles(process.cwd()));
+  if (path31.resolve(process.cwd()) !== manifestDir) envFiles2.push(...loadEnvFiles(process.cwd()));
   const loaded = await loadManifest(args.manifest);
   let specs = await resolveSpecs(loaded, {
     styles: args.styles,
@@ -15370,6 +15763,40 @@ async function main() {
   }
   const lock = await loadLock(args.lock);
   normalizeLockOutputPaths(lock, specs);
+  if (args.command === "history") {
+    const limit = historyLimit(loaded.manifest);
+    const selected = specs.map((spec) => ({ spec, entry: lock.entries[lockKey(spec.styleId, spec.assetId)] }));
+    if (args.json) {
+      log(JSON.stringify({
+        version: 1,
+        limit,
+        assets: selected.map(({ spec, entry }) => ({
+          key: lockKey(spec.styleId, spec.assetId),
+          current: entry ? { objectId: entry.objectId, outputs: entry.outputs, downloadedAt: entry.downloadedAt, cost: entry.cost, costUnit: entry.costUnit } : null,
+          history: entry?.history ?? []
+        }))
+      }, null, 2));
+      return;
+    }
+    log(`  keeping up to ${limit} replaced generation${limit === 1 ? "" : "s"} per asset` + (loaded.manifest.history !== void 0 ? " (manifest history)" : ` (${process.env.PIXELKILN_HISTORY ? "PIXELKILN_HISTORY" : "default; set PIXELKILN_HISTORY or manifest history"})`));
+    let shown = 0;
+    for (const { spec, entry } of selected) {
+      if (!entry?.history?.length) continue;
+      shown++;
+      const key = lockKey(spec.styleId, spec.assetId);
+      log(`
+  ${key}`);
+      log(`    current  ${entry.outputs[0]?.sha256.slice(0, 12) ?? "\u2014"}  ${entry.downloadedAt ?? ""}  ${entry.objectId ?? ""}`);
+      for (const [i, generation] of entry.history.entries()) {
+        const changed = generation.prompt !== entry.prompt ? "  (different prompt)" : "";
+        log(`    #${String(i + 1).padEnd(2)}      ${generation.outputs[0]?.sha256.slice(0, 12) ?? "\u2014"}  ${generation.downloadedAt ?? ""}  ${generation.objectId ?? ""}${changed}`);
+      }
+    }
+    if (!shown) log(`  no asset has a previous generation recorded${selected.length ? "" : " (nothing selected)"}`);
+    else log(`
+  bring one back: pixelkiln restore --only <asset> --style <style> --generation <n|hash>`);
+    return;
+  }
   if (args.command === "status") {
     const byStatus = {};
     for (const e of Object.values(lock.entries)) byStatus[e.status] = (byStatus[e.status] ?? 0) + 1;
@@ -15411,7 +15838,7 @@ async function main() {
       });
     };
     await runGallery(await build(), reload, args, {
-      manifestFor: () => path30.resolve(args.manifest),
+      manifestFor: () => path31.resolve(args.manifest),
       loadProject: async () => {
         const freshLoaded = await loadManifest(args.manifest);
         const freshSpecs = await resolveSpecs(freshLoaded);
@@ -15439,7 +15866,7 @@ async function main() {
     const set = started.members.length > 1;
     const kind = spec.generator === "frames" ? "frames" : "members";
     log(`  ${started.created ? "created" : "found"} ${started.source}${set ? ` (${started.members.length} ${kind})` : ""}${started.declared ? " and declared it as the asset's source" : ""}`);
-    if (set) for (const member of started.members) log(`    ${member.role ?? ""}  ${path30.relative(process.cwd(), member.path)}`);
+    if (set) for (const member of started.members) log(`    ${member.role ?? ""}  ${path31.relative(process.cwd(), member.path)}`);
     if (args.noOpen) {
       log(`  edit ${set ? "them" : "it"} with your own tool, then run pixelkiln plan; mount and pack place ${set ? "them" : "it"} in place of the generated art`);
     } else {
@@ -15489,7 +15916,7 @@ async function main() {
         log(`  ${item.state.padEnd(16)} ${item.key}  ${item.reason}`);
         if (item.state === "needs-approval") {
           log(
-            `    pixelkiln refine approve --from ${path30.relative(process.cwd(), item.record)} --reviewer "Your Name"`
+            `    pixelkiln refine approve --from ${path31.relative(process.cwd(), item.record)} --reviewer "Your Name"`
           );
         }
       }
@@ -15580,7 +16007,7 @@ async function main() {
       let intact = true;
       for (const output of entry.outputs) {
         const file = resolveOutputPath(output.path, item.spec.root);
-        if (!existsSync24(file) || await sha256File(file) !== output.sha256) {
+        if (!existsSync25(file) || await sha256File(file) !== output.sha256) {
           intact = false;
           break;
         }
@@ -15638,7 +16065,7 @@ async function main() {
     if (args.primaryOnly && args.outputRoles.length) {
       throw new Error("pack accepts either --primary-only or --output-role, not both");
     }
-    const manifestDir2 = path30.dirname(path30.resolve(args.manifest));
+    const manifestDir2 = path31.dirname(path31.resolve(args.manifest));
     const styleIds = args.styles.length ? args.styles : Object.keys(loaded.manifest.styles);
     for (const styleId of styleIds) {
       const packagingSpecs = await resolveSpecs(loaded, { styles: [styleId] });
@@ -15651,7 +16078,7 @@ async function main() {
         sources: manifestSources(loaded.manifest, styleId)
       });
       const style = loaded.manifest.styles[styleId];
-      const base = args.out ? path30.resolve(args.out.replace(/\.png$/, "")) : path30.resolve(manifestDir2, style.outDir, `${styleId}-sheet`);
+      const base = args.out ? path31.resolve(args.out.replace(/\.png$/, "")) : path31.resolve(manifestDir2, style.outDir, `${styleId}-sheet`);
       const outputs = [
         { path: `${base}.png`, data: png },
         { path: `${base}.json`, data: JSON.stringify(atlas, null, 2) + "\n" }
@@ -15681,13 +16108,13 @@ async function main() {
       log(
         `  ${styleId} \u2014 ${atlas.frames.length} sprite(s), ${atlas.sheet.width}x${atlas.sheet.height} in ${atlas.columns} column(s)`
       );
-      log(`    ${path30.relative(process.cwd(), base)}.png + .json + .pixelkiln.json`);
+      log(`    ${path31.relative(process.cwd(), base)}.png + .json + .pixelkiln.json`);
       for (const s of skipped) log(`    skipped ${s.id}: ${s.reason}`);
     }
     return;
   }
   if (args.command === "mount") {
-    const manifestDir2 = path30.dirname(path30.resolve(args.manifest));
+    const manifestDir2 = path31.dirname(path31.resolve(args.manifest));
     const styleIds = args.styles.length ? args.styles : Object.keys(loaded.manifest.styles);
     for (const styleId of styleIds) {
       const style = loaded.manifest.styles[styleId];
@@ -15726,7 +16153,7 @@ async function main() {
         sources,
         outputRoles
       );
-      const out = path30.resolve(manifestDir2, style.mount.out);
+      const out = path31.resolve(manifestDir2, style.mount.out);
       const metadata = out.replace(/\.png$/, "") + ".json";
       const companion = out.replace(/\.png$/, "") + ".pixelkiln.json";
       const outputs = [
@@ -15746,7 +16173,7 @@ async function main() {
           await provenanceFile("$lock", args.lock),
           ...qualityRecords,
           ...artifactSources.filter(
-            (source) => source.id !== "$base" || path30.resolve(source.path) !== out
+            (source) => source.id !== "$base" || path31.resolve(source.path) !== out
           )
         ],
         options: {
@@ -15759,7 +16186,7 @@ async function main() {
       log(
         `  ${styleId} \u2014 ${atlas.frames.length} cell(s) into ${atlas.sheet.width}x${atlas.sheet.height}` + (overBase ? ` over ${style.mount.base}` : " (new sheet)")
       );
-      log(`    ${path30.relative(process.cwd(), out)} + atlas/provenance JSON`);
+      log(`    ${path31.relative(process.cwd(), out)} + atlas/provenance JSON`);
       for (const s of skipped) log(`    skipped ${s.id}: ${s.reason}`);
     }
     return;
@@ -15815,7 +16242,7 @@ async function main() {
   }
   if (args.command === "export") {
     const format = args.format ?? "generic";
-    const manifestDir2 = path30.dirname(path30.resolve(args.manifest));
+    const manifestDir2 = path31.dirname(path31.resolve(args.manifest));
     const selected = specs.filter((spec) => {
       if (spec.generator !== "tiles") return false;
       if (args.styles.length && !args.styles.includes(spec.styleId)) return false;
@@ -15831,12 +16258,12 @@ async function main() {
     for (const spec of selected) {
       const entry = lock.entries[lockKey(spec.styleId, spec.assetId)];
       const style = loaded.manifest.styles[spec.styleId];
-      const defaultBase = path30.resolve(manifestDir2, style.outDir, `${spec.assetId}-tileset`);
-      const base = args.out ? path30.resolve(args.out.replace(/\.(?:png|json|tsj|tres)$/i, "")) : defaultBase;
+      const defaultBase = path31.resolve(manifestDir2, style.outDir, `${spec.assetId}-tileset`);
+      const base = args.out ? path31.resolve(args.out.replace(/\.(?:png|json|tsj|tres)$/i, "")) : defaultBase;
       const result = exportTileset(entry, spec, {
         format,
         manifestDir: manifestDir2,
-        imageName: path30.basename(`${base}.png`),
+        imageName: path31.basename(`${base}.png`),
         columns: args.columns
       });
       const outputs = [
@@ -15854,7 +16281,7 @@ async function main() {
           asset: spec.assetId,
           columns: args.columns ?? null,
           format,
-          image: path30.basename(`${base}.png`),
+          image: path31.basename(`${base}.png`),
           providerRules: result.generic.providerRules,
           style: spec.styleId,
           tileType: spec.tileType ?? null
@@ -15864,12 +16291,32 @@ async function main() {
         `  ${spec.styleId}/${spec.assetId} \u2014 ${result.generic.tiles.length} tile(s), ${result.generic.sheet.width}x${result.generic.sheet.height} (${format})`
       );
       log(
-        `    ${path30.relative(process.cwd(), base)}.png + ${path30.basename(base)}${result.extension} + .pixelkiln.json`
+        `    ${path31.relative(process.cwd(), base)}.png + ${path31.basename(base)}${result.extension} + .pixelkiln.json`
       );
     }
     return;
   }
   const providerMode = args.command === "restore" || args.command === "fetch" && !args.tag ? "downloads" : "online";
+  if (args.command === "restore" && args.generation !== void 0) {
+    if (specs.length !== 1) {
+      throw new Error(
+        specs.length ? `restore --generation works on one asset; --only/--style select ${specs.length}. Add --style or narrow --only.` : "restore --generation matched no asset; pass --only <asset id> (and --style when it is in several styles)."
+      );
+    }
+    const spec = specs[0];
+    const entry = lock.entries[lockKey(spec.styleId, spec.assetId)];
+    if (!entry) throw new Error(`${spec.styleId}/${spec.assetId} is not in the lockfile`);
+    const provider = createProvider(entry.provider, "downloads");
+    const result = await revertGeneration(provider, spec, lock, args.lock, {
+      generation: args.generation,
+      force: args.force,
+      onProgress: log
+    });
+    log(`
+  restored generation #${result.index} of ${spec.styleId}/${spec.assetId}${result.restored.objectId ? ` (${result.restored.objectId})` : ""}; the replaced one is now #1 in its history`);
+    log(`  lockfile written: ${args.lock}`);
+    return;
+  }
   const providers = /* @__PURE__ */ new Map();
   const providerFor = (id) => {
     let resolved = providers.get(id);
@@ -15914,12 +16361,12 @@ async function main() {
   tagged ${n} object(s) upstream`);
     }
     if (args.writePrompts) {
-      const { filled, stillEmpty } = await writePromptsBack(path30.resolve(args.manifest), lock, {
+      const { filled, stillEmpty } = await writePromptsBack(path31.resolve(args.manifest), lock, {
         onProgress: log,
         provider: provider.id,
         assetIds: specs.map((spec) => spec.assetId)
       });
-      log(`  recovered ${filled} prompt(s) into ${path30.relative(process.cwd(), args.manifest)}`);
+      log(`  recovered ${filled} prompt(s) into ${path31.relative(process.cwd(), args.manifest)}`);
       const reloaded = await loadManifest(args.manifest);
       const rebased = (await resolveSpecs(reloaded, {
         styles: args.styles,
@@ -15948,12 +16395,12 @@ async function main() {
     const provider = providerFor(selectedAccountProvider);
     const jsonMode = args.dryRun && args.json;
     const diag = jsonMode ? (msg = "") => console.error(msg) : log;
-    const ownLock = path30.resolve(args.lock);
+    const ownLock = path31.resolve(args.lock);
     let workspaceProjects = [];
     let workspaceDir = "";
     if (args.workspace) {
-      const workspacePath = path30.resolve(args.workspace);
-      workspaceDir = path30.dirname(workspacePath);
+      const workspacePath = path31.resolve(args.workspace);
+      workspaceDir = path31.dirname(workspacePath);
       const complete = await requireCompleteWorkspaceClaims(workspacePath);
       workspaceProjects = complete.ws.projects;
       for (const d of complete.diagnostics) diag(`  WARN  ${d.id}: ${d.message}`);
@@ -15962,12 +16409,12 @@ async function main() {
     const lockPaths = [
       .../* @__PURE__ */ new Set([
         ...workspaceLockPaths,
-        ...existsSync24(ownLock) ? [ownLock] : [],
-        ...args.claims.map((c) => path30.resolve(c))
+        ...existsSync25(ownLock) ? [ownLock] : [],
+        ...args.claims.map((c) => path31.resolve(c))
       ])
     ];
     diag(`  claim set (${lockPaths.length} lockfile(s)):`);
-    for (const p of lockPaths) diag(`    ${path30.relative(process.cwd(), p)}`);
+    for (const p of lockPaths) diag(`    ${path31.relative(process.cwd(), p)}`);
     if (!args.claims.length && !args.workspace) {
       diag(
         `
@@ -15975,7 +16422,7 @@ async function main() {
   pass every other project's lockfile via --claims a.json,b.json, or
   register every project in a workspace catalog and pass --workspace.`
       );
-    } else if (args.workspace && !workspaceProjects.some((p) => resolveProject(workspaceDir, p).manifestPath === path30.resolve(args.manifest))) {
+    } else if (args.workspace && !workspaceProjects.some((p) => resolveProject(workspaceDir, p).manifestPath === path31.resolve(args.manifest))) {
       diag(
         `
   This project's manifest is not registered in the workspace catalog. Its own
@@ -16059,7 +16506,7 @@ async function main() {
           manifestPath: loaded.path,
           manifest: accountManifest,
           styleId,
-          importDir: path30.resolve(loaded.root, style.outDir),
+          importDir: path31.resolve(loaded.root, style.outDir),
           lock,
           lockPath: args.lock
         },