pixelkiln 0.24.0 → 0.26.0

package/dist/index.d.cts

@@ -4310,14 +4310,6 @@ declare class PixelLabClient {
 }
 declare function clientFromEnv(): PixelLabClient;
 
-/**
- * PixelLab, the reference implementation.
- *
- * All PixelLab-specific knowledge lives here: the three generators and their
- * very different pricing, the review/candidate flow, the fact that a map
- * object's job record expires while its image does not, and that pixflux
- * returns bytes inline instead of a job id.
- */
 declare class PixelLabProvider implements Provider {
     private readonly client;
     readonly id = "pixellab";
@@ -7225,6 +7217,8 @@ interface FetchResult {
     downloaded: number;
     skipped: number;
     failed: number;
+    /** `refresh` only: outputs re-downloaded and found byte-identical upstream. */
+    unchanged?: number;
 }
 /**
  * Downloads every selected object to its manifest-defined path and records the
@@ -7239,6 +7233,13 @@ declare function fetchAssets(provider: Provider, specs: ResolvedSpec[], lock: Lo
     repair?: boolean;
     /** Replace an existing untracked or modified destination. Explicit ownership override. */
     force?: boolean;
+    /**
+     * Re-download `downloaded` outputs from their durable provider reference
+     * and replace the local file when the upstream bytes changed — an object
+     * edited in the provider's own editor, say. Unchanged objects are left
+     * alone; a locally modified file is still refused without `force`.
+     */
+    refresh?: boolean;
     /** Content-addressed media cache. Defaults beside the lockfile; false disables it. */
     cacheDir?: string | false;
 }): Promise<FetchResult>;
@@ -7670,6 +7671,10 @@ interface GalleryItem {
      */
     edit: GalleryOutput | null;
     editStatus: HandEditStatus | null;
+    /** Where the provider's own app shows this object, when it has one. */
+    upstreamUrl: string | null;
+    /** Downloaded work with a durable provider reference; `fetch --refresh` can re-pull it. */
+    refreshable: boolean;
     tags: string[];
     category: string | null;
 }
@@ -7849,8 +7854,8 @@ interface GenerateJob {
     id: string;
     project: string | null;
     keys: string[];
-    /** `resume` skips submission: poll, review, and fetch existing work at no cost. */
-    mode: "generate" | "resume";
+    /** `resume` skips submission: poll, review, and fetch existing work at no cost; `refresh` re-pulls changed objects. */
+    mode: "generate" | "resume" | "refresh";
     phase: GeneratePhase;
     startedAt: string;
     finishedAt: string | null;
@@ -7911,23 +7916,39 @@ interface GalleryGenerateHandlers {
     }): Promise<ReviewSession | null>;
     applyReview(jobId: string, body: unknown): Promise<PickResult>;
 }
-declare const GenerateRequestSchema: z.ZodObject<{
+declare const GenerateRequestSchema: z.ZodEffects<z.ZodObject<{
     project: z.ZodOptional<z.ZodString>;
     keys: z.ZodArray<z.ZodString, "many">;
     /** Regenerate work that is up to date, as `gen --force` does. */
     force: z.ZodOptional<z.ZodBoolean>;
     /** Advance in-flight, review, or selected work without submitting anything. */
     resume: z.ZodOptional<z.ZodBoolean>;
+    /** Re-download downloaded outputs and replace files whose object changed upstream. */
+    refresh: z.ZodOptional<z.ZodBoolean>;
 }, "strict", z.ZodTypeAny, {
     keys: string[];
     resume?: boolean | undefined;
     force?: boolean | undefined;
     project?: string | undefined;
+    refresh?: boolean | undefined;
+}, {
+    keys: string[];
+    resume?: boolean | undefined;
+    force?: boolean | undefined;
+    project?: string | undefined;
+    refresh?: boolean | undefined;
+}>, {
+    keys: string[];
+    resume?: boolean | undefined;
+    force?: boolean | undefined;
+    project?: string | undefined;
+    refresh?: boolean | undefined;
 }, {
     keys: string[];
     resume?: boolean | undefined;
     force?: boolean | undefined;
     project?: string | undefined;
+    refresh?: boolean | undefined;
 }>;
 declare class GenerateRequestError extends Error {
     readonly status: number;

package/dist/index.d.ts

@@ -4310,14 +4310,6 @@ declare class PixelLabClient {
 }
 declare function clientFromEnv(): PixelLabClient;
 
-/**
- * PixelLab, the reference implementation.
- *
- * All PixelLab-specific knowledge lives here: the three generators and their
- * very different pricing, the review/candidate flow, the fact that a map
- * object's job record expires while its image does not, and that pixflux
- * returns bytes inline instead of a job id.
- */
 declare class PixelLabProvider implements Provider {
     private readonly client;
     readonly id = "pixellab";
@@ -7225,6 +7217,8 @@ interface FetchResult {
     downloaded: number;
     skipped: number;
     failed: number;
+    /** `refresh` only: outputs re-downloaded and found byte-identical upstream. */
+    unchanged?: number;
 }
 /**
  * Downloads every selected object to its manifest-defined path and records the
@@ -7239,6 +7233,13 @@ declare function fetchAssets(provider: Provider, specs: ResolvedSpec[], lock: Lo
     repair?: boolean;
     /** Replace an existing untracked or modified destination. Explicit ownership override. */
     force?: boolean;
+    /**
+     * Re-download `downloaded` outputs from their durable provider reference
+     * and replace the local file when the upstream bytes changed — an object
+     * edited in the provider's own editor, say. Unchanged objects are left
+     * alone; a locally modified file is still refused without `force`.
+     */
+    refresh?: boolean;
     /** Content-addressed media cache. Defaults beside the lockfile; false disables it. */
     cacheDir?: string | false;
 }): Promise<FetchResult>;
@@ -7670,6 +7671,10 @@ interface GalleryItem {
      */
     edit: GalleryOutput | null;
     editStatus: HandEditStatus | null;
+    /** Where the provider's own app shows this object, when it has one. */
+    upstreamUrl: string | null;
+    /** Downloaded work with a durable provider reference; `fetch --refresh` can re-pull it. */
+    refreshable: boolean;
     tags: string[];
     category: string | null;
 }
@@ -7849,8 +7854,8 @@ interface GenerateJob {
     id: string;
     project: string | null;
     keys: string[];
-    /** `resume` skips submission: poll, review, and fetch existing work at no cost. */
-    mode: "generate" | "resume";
+    /** `resume` skips submission: poll, review, and fetch existing work at no cost; `refresh` re-pulls changed objects. */
+    mode: "generate" | "resume" | "refresh";
     phase: GeneratePhase;
     startedAt: string;
     finishedAt: string | null;
@@ -7911,23 +7916,39 @@ interface GalleryGenerateHandlers {
     }): Promise<ReviewSession | null>;
     applyReview(jobId: string, body: unknown): Promise<PickResult>;
 }
-declare const GenerateRequestSchema: z.ZodObject<{
+declare const GenerateRequestSchema: z.ZodEffects<z.ZodObject<{
     project: z.ZodOptional<z.ZodString>;
     keys: z.ZodArray<z.ZodString, "many">;
     /** Regenerate work that is up to date, as `gen --force` does. */
     force: z.ZodOptional<z.ZodBoolean>;
     /** Advance in-flight, review, or selected work without submitting anything. */
     resume: z.ZodOptional<z.ZodBoolean>;
+    /** Re-download downloaded outputs and replace files whose object changed upstream. */
+    refresh: z.ZodOptional<z.ZodBoolean>;
 }, "strict", z.ZodTypeAny, {
     keys: string[];
     resume?: boolean | undefined;
     force?: boolean | undefined;
     project?: string | undefined;
+    refresh?: boolean | undefined;
+}, {
+    keys: string[];
+    resume?: boolean | undefined;
+    force?: boolean | undefined;
+    project?: string | undefined;
+    refresh?: boolean | undefined;
+}>, {
+    keys: string[];
+    resume?: boolean | undefined;
+    force?: boolean | undefined;
+    project?: string | undefined;
+    refresh?: boolean | undefined;
 }, {
     keys: string[];
     resume?: boolean | undefined;
     force?: boolean | undefined;
     project?: string | undefined;
+    refresh?: boolean | undefined;
 }>;
 declare class GenerateRequestError extends Error {
     readonly status: number;

package/dist/index.js

@@ -1291,6 +1291,10 @@ import { mkdirSync, existsSync, readFileSync, writeFileSync } from "fs";
 import { randomUUID } from "crypto";
 import os from "os";
 import path from "path";
+function pixelLabObjectUrl(generator, objectId) {
+  if (!objectId || generator !== "map" && generator !== "1dir") return null;
+  return `https://www.pixellab.ai/objects/${encodeURIComponent(objectId)}`;
+}
 var PixelLabProvider = class _PixelLabProvider {
   constructor(client) {
     this.client = client;
@@ -7742,14 +7746,16 @@ import path16 from "path";
 async function fetchAssets(provider, specs, lock, lockPath, opts = {}) {
   const log = opts.onProgress ?? (() => {
   });
-  const result = { downloaded: 0, skipped: 0, failed: 0 };
+  const result = { downloaded: 0, skipped: 0, failed: 0, ...opts.refresh ? { unchanged: 0 } : {} };
   const specByKey = new Map(specs.map((s) => [lockKey(s.styleId, s.assetId), s]));
   normalizeLockOutputPaths(lock, specs);
   const cacheDir = opts.cacheDir === false ? null : path16.resolve(opts.cacheDir ?? path16.join(path16.dirname(lockPath), ".pixelkiln", "cache"));
   const pending = Object.entries(lock.entries).filter(([key, e]) => {
     if (e.provider !== provider.id || !specByKey.has(key)) return false;
     if (e.status === "selected" || e.status === "download-failed") return true;
-    if (!opts.repair || e.status !== "downloaded") return false;
+    if (e.status !== "downloaded") return false;
+    if (opts.refresh) return e.outputs.length > 0 && Boolean(e.sourceUrls?.length || e.sourceUrl);
+    if (!opts.repair) return false;
     const spec = specByKey.get(key);
     return e.outputs.length === 0 || !spec || e.outputs.some((output) => !existsSync12(resolveOutputPath(output.path, spec.root)));
   });
@@ -7781,6 +7787,7 @@ async function fetchAssets(provider, specs, lock, lockPath, opts = {}) {
         continue;
       }
       const outputs = [];
+      let wrote = false;
       try {
         for (let index = 0; index < sources.length; index++) {
           const source = sources[index];
@@ -7788,41 +7795,55 @@ async function fetchAssets(provider, specs, lock, lockPath, opts = {}) {
             (o) => source.role ? o.role === source.role : !o.role && sources.length === 1
           );
           const target = recorded ? resolveOutputPath(recorded.path, spec.root) : expectedOutputPath(spec, source.role, index, sources.length, source.mediaType);
+          let fresh = null;
+          if (opts.refresh) {
+            if (!source.url) throw new Error(`no durable source URL to refresh ${source.role ?? "asset"} from`);
+            fresh = await provider.download(source.url);
+            if (recorded && sha256(fresh) === recorded.sha256) {
+              log(`  current ${path16.relative(process.cwd(), target)}`);
+              outputs.push({ ...recorded, path: portableOutputPath(target, spec.root) });
+              continue;
+            }
+          }
           if (existsSync12(target)) {
             const currentHash = await sha256File(target);
             if (recorded && currentHash === recorded.sha256) {
-              if (cacheDir) {
-                await cacheMedia(
-                  cacheDir,
-                  await readFile11(target),
-                  recorded.mediaType ?? MediaType.PNG,
-                  recorded.sha256
-                );
+              if (!fresh) {
+                if (cacheDir) {
+                  await cacheMedia(
+                    cacheDir,
+                    await readFile11(target),
+                    recorded.mediaType ?? MediaType.PNG,
+                    recorded.sha256
+                  );
+                }
+                outputs.push({ ...recorded, path: portableOutputPath(target, spec.root) });
+                continue;
               }
-              outputs.push({ ...recorded, path: portableOutputPath(target, spec.root) });
-              continue;
-            }
-            const superseded = (entry.supersededOutputs ?? []).find(
-              (output, oldIndex, all) => currentOutputPath(output, spec, oldIndex, all.length) === target
-            );
-            if (!opts.force) {
-              if (!recorded && superseded && currentHash === superseded.sha256) {
-              } else if (recorded || superseded) {
-                throw new Error(
-                  `refusing to overwrite modified output ${target}; pass --force to replace it`
-                );
-              } else {
-                throw new Error(
-                  `refusing to overwrite untracked output ${target}; pass --force to replace it`
-                );
+              log(`  changed ${path16.relative(process.cwd(), target)} (upstream)`);
+            } else {
+              const superseded = (entry.supersededOutputs ?? []).find(
+                (output, oldIndex, all) => currentOutputPath(output, spec, oldIndex, all.length) === target
+              );
+              if (!opts.force) {
+                if (!recorded && superseded && currentHash === superseded.sha256) {
+                } else if (recorded || superseded) {
+                  throw new Error(
+                    `refusing to overwrite modified output ${target}; pass --force to replace it`
+                  );
+                } else {
+                  throw new Error(
+                    `refusing to overwrite untracked output ${target}; pass --force to replace it`
+                  );
+                }
               }
+              log(
+                `  replace ${path16.relative(process.cwd(), target)}` + (opts.force ? " (--force)" : " (previous tracked generation)")
+              );
             }
-            log(
-              `  replace ${path16.relative(process.cwd(), target)}` + (opts.force ? " (--force)" : " (previous tracked generation)")
-            );
           }
           const expectedMediaType = source.mediaType ?? recorded?.mediaType ?? MediaType.PNG;
-          let buf = recorded && cacheDir ? await readCachedMedia(cacheDir, recorded.sha256, expectedMediaType) : null;
+          let buf = fresh ?? (recorded && cacheDir ? await readCachedMedia(cacheDir, recorded.sha256, expectedMediaType) : null);
           if (buf) {
             log(`  cached  ${path16.relative(process.cwd(), target)}`);
           } else {
@@ -7854,8 +7875,13 @@ async function fetchAssets(provider, specs, lock, lockPath, opts = {}) {
           upsert(lock, key, { outputs: mergeOutputs(entry.outputs, outputs) });
           await saveLock(lockPath, lock);
           await rename4(tmp, target);
+          wrote = true;
           log(`  wrote   ${path16.relative(process.cwd(), target)}`);
         }
+        if (opts.refresh && !wrote) {
+          result.unchanged = (result.unchanged ?? 0) + 1;
+          continue;
+        }
         const persistentSources = sources.filter((source) => shouldPersistSourceUrl(source.url));
         upsert(lock, key, {
           status: "downloaded",
@@ -9739,6 +9765,8 @@ async function buildGallerySnapshot(opts) {
       source: spec.source ?? null,
       edit,
       editStatus,
+      upstreamUrl: entry?.provider === "pixellab" ? pixelLabObjectUrl(entry.generator, entry.objectId) : null,
+      refreshable: Boolean(entry && entry.status === "downloaded" && entry.outputs.length && (entry.sourceUrls?.length || entry.sourceUrl)),
       tags: spec.tags,
       category: asset?.category ?? null
     });
@@ -9793,6 +9821,8 @@ async function buildGallerySnapshot(opts) {
       source: null,
       edit: null,
       editStatus: null,
+      upstreamUrl: entry.provider === "pixellab" ? pixelLabObjectUrl(entry.generator, entry.objectId) : null,
+      refreshable: false,
       tags: [],
       category: null
     });
@@ -10464,7 +10494,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 === 'resume' ? 'resume ' : 'generate ') + job.keys.length + (job.keys.length === 1 ? ' asset' : ' assets') +
+    const what = (job.mode === 'refresh' ? 'pull upstream for ' : 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');
@@ -10503,13 +10533,15 @@ 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 } = {}) {
+function generateDialog(items, { project = null, force = false, resume = false, refresh = false } = {}) {
   const host = $('dialog-host');
   host.textContent = '';
   const wrap = el('div', 'dialog');
   const form = el('form');
-  form.append(el('h3', null, resume ? 'Resume ' + items.length + (items.length === 1 ? ' asset' : ' assets')
-    : (force ? 'Regenerate ' : 'Generate ') + items.length + (items.length === 1 ? ' asset' : ' assets')));
+  const noun = items.length + (items.length === 1 ? ' asset' : ' assets');
+  form.append(el('h3', null, refresh ? 'Pull upstream changes for ' + noun
+    : resume ? 'Resume ' + noun
+    : (force ? 'Regenerate ' : 'Generate ') + noun));
   const table = el('table');
   const thead = el('tr'); thead.append(el('th', null, 'asset'), el('th', null, 'state'), el('th', 'n', 'candidates'), el('th', 'n', 'estimate'));
   table.append(thead);
@@ -10517,16 +10549,18 @@ function generateDialog(items, { project = null, force = false, resume = false }
   for (const item of items) {
     const tr = el('tr');
     tr.append(el('td', 'mono', item.key), el('td', null, item.state), el('td', 'n', item.candidates ?? '\u2014'),
-      el('td', 'n', resume ? 'no cost' : fmtCost(item.costUnit, item.estimatedCost ?? 0)));
+      el('td', 'n', resume || refresh ? 'no cost' : fmtCost(item.costUnit, item.estimatedCost ?? 0)));
     table.append(tr);
-    if (!resume) {
+    if (!resume && !refresh) {
       const g = byProvider.get(item.provider) || { cost: 0, unit: item.costUnit };
       g.cost += item.estimatedCost ?? 0; byProvider.set(item.provider, g);
     }
   }
   form.append(table);
   const sum = el('div', 'sum');
-  if (resume) {
+  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 (resume) {
     sum.append(el('div', null, 'Polls, reviews, and downloads existing provider work. Nothing is submitted.'));
   } else {
     for (const [provider, g] of byProvider) {
@@ -10543,7 +10577,7 @@ function generateDialog(items, { project = null, force = false, resume = false }
   }
   form.append(sum);
   const actions = el('div', 'actions');
-  const go = el('button', 'primary', resume ? 'Resume' : 'Generate');
+  const go = el('button', 'primary', refresh ? 'Pull changes' : resume ? 'Resume' : 'Generate');
   go.type = 'submit';
   const cancel = el('button', null, 'Cancel'); cancel.type = 'button'; cancel.onclick = () => { host.textContent = ''; };
   const msg = el('span', 'msg');
@@ -10557,6 +10591,7 @@ function generateDialog(items, { project = null, force = false, resume = false }
       if (project) body.project = project;
       if (force) body.force = true;
       if (resume) body.resume = true;
+      if (refresh) body.refresh = true;
       const job = await postGenerate(body);
       host.textContent = '';
       GEN.jobs.unshift(job);
@@ -10846,6 +10881,13 @@ function renderMain(items) {
         g.onclick = () => generateDialog(snap.items.filter((i) => i.project === s.project && s.actionable.keys.includes(i.key)), { project: s.project });
         tools.append(g);
       }
+      const refreshable = snap.items.filter((i) => i.project === s.project && i.styleId === s.id && i.refreshable && i.upstreamUrl);
+      if (GENERATION && refreshable.length) {
+        const r = el('button', null, 'Pull upstream ' + refreshable.length); r.type = 'button';
+        r.title = 'Re-download objects edited in the provider\u2019s own editor; no cost';
+        r.onclick = () => generateDialog(refreshable, { project: s.project, refresh: true });
+        tools.append(r);
+      }
       const styleKey = 'style:' + (s.project || '') + ':' + s.id;
       if (EDITABLE && s.outDir) {
         const es = el('button', null, ui.editing === styleKey ? 'Cancel' : 'Edit style');
@@ -10939,6 +10981,30 @@ function candidatesControl(style) {
   return wrap;
 }
 
+function upstreamSection(item) {
+  if (!item.upstreamUrl && !(GENERATION && item.refreshable)) return null;
+  const s = el('section', 'meta');
+  s.append(el('h3', null, 'Upstream'));
+  const dl = el('dl');
+  if (item.upstreamUrl) {
+    const a = el('a', null, 'Open in ' + item.provider + ' \u2197');
+    a.href = item.upstreamUrl; a.target = '_blank'; a.rel = 'noopener';
+    row(dl, 'object', a);
+    row(dl, 'note', item.provider === 'pixellab'
+      ? 'The account object this generation came from. Edit it there with PixelLab\u2019s editor, then pull the changes back here; the lockfile records the new bytes as this generation.'
+      : 'The provider\u2019s page for this object.');
+  }
+  s.append(dl);
+  if (GENERATION && item.refreshable) {
+    const acts = el('div', 'hand-actions');
+    const b = el('button', null, 'Pull upstream changes \xB7 no cost'); b.type = 'button';
+    b.onclick = () => generateDialog([item], { project: item.project, refresh: true });
+    acts.append(b);
+    s.append(acts);
+  }
+  return s;
+}
+
 function generateActions(item) {
   const row = el('div', 'gen');
   if (!GENERATION || !item.declared || item.currentSpecHash === null) return row;
@@ -11657,6 +11723,8 @@ function renderDrawer() {
 
   const hand = handEditSection(item);
   if (hand) body.append(hand);
+  const upstream = upstreamSection(item);
+  if (upstream) body.append(upstream);
 
   if (item.revision || item.revisionParentKey) {
     const { s, dl } = section('Lineage');
@@ -12150,8 +12218,10 @@ var GenerateRequestSchema = z9.object({
   /** Regenerate work that is up to date, as `gen --force` does. */
   force: z9.boolean().optional(),
   /** Advance in-flight, review, or selected work without submitting anything. */
-  resume: z9.boolean().optional()
-}).strict();
+  resume: z9.boolean().optional(),
+  /** Re-download downloaded outputs and replace files whose object changed upstream. */
+  refresh: z9.boolean().optional()
+}).strict().refine((request) => !(request.resume && request.refresh), { message: "resume and refresh are exclusive" });
 var GenerateRequestError = class extends Error {
   constructor(message6, status = 400) {
     super(message6);
@@ -12209,6 +12279,20 @@ function createGenerateHandlers(opts) {
     }
     return groups;
   };
+  async function refresh(job, ctx, specs) {
+    job.phase = "fetching";
+    for (const [providerId, providerSpecs] of groupByRecordedProvider(specs, ctx.lock)) {
+      const provider = opts.providerFor(job.project ?? void 0, providerId);
+      const res = await fetchAssets(provider, providerSpecs, ctx.lock, ctx.lockPath, {
+        onProgress: (line) => say(job, line),
+        refresh: true
+      });
+      job.counts.downloaded += res.downloaded;
+      say(job, `${providerId}: ${res.downloaded} changed upstream and replaced, ${res.unchanged ?? 0} unchanged, ${res.skipped} skipped, ${res.failed} failed`);
+    }
+    job.phase = "done";
+    job.finishedAt = now().toISOString();
+  }
   async function settle(job, ctx, specs) {
     job.phase = "polling";
     for (const [providerId, providerSpecs] of groupByRecordedProvider(specs, ctx.lock)) {
@@ -12242,6 +12326,10 @@ function createGenerateHandlers(opts) {
   }
   async function run(job, ctx, specs, groups) {
     try {
+      if (job.mode === "refresh") {
+        await refresh(job, ctx, specs);
+        return;
+      }
       if (job.mode === "generate") {
         job.phase = "submitting";
         for (const group of groups) {
@@ -12305,7 +12393,7 @@ function createGenerateHandlers(opts) {
         if (holder) throw new GenerateRequestError(`"${key}" is already being worked on by job ${holder}`, 409);
       }
       let groups = [];
-      if (!request.resume) {
+      if (!request.resume && !request.refresh) {
         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);
@@ -12325,7 +12413,7 @@ function createGenerateHandlers(opts) {
         id: randomBytes2(8).toString("hex"),
         project: request.project ?? null,
         keys: request.keys,
-        mode: request.resume ? "resume" : "generate",
+        mode: request.refresh ? "refresh" : request.resume ? "resume" : "generate",
         phase: "queued",
         startedAt: now().toISOString(),
         finishedAt: null,
@@ -12337,7 +12425,7 @@ function createGenerateHandlers(opts) {
       };
       jobs.set(job.id, job);
       contexts.set(job.id, ctx);
-      say(job, 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.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;
     },