scenri 0.7.0 → 0.7.1

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## [0.7.1](https://github.com/tonygorb/Scenri/compare/v0.7.0...v0.7.1) (2026-08-30)
+
+
+### Bug Fixes
+
+* condition a presenter on their face, not only on their figure ([b556b91](https://github.com/tonygorb/Scenri/commit/b556b91403e53ee424ceb0c937d5d0f968cc77fe))
+* condition a presenter on their face, not only on their figure ([4f1e02b](https://github.com/tonygorb/Scenri/commit/4f1e02b9a0512bf588c7f8b46f7d469f22ecae67))
+* decode a presenter's references once, and let one e2e test finish ([e862212](https://github.com/tonygorb/Scenri/commit/e862212898d96a46148f5bf3cb6106a624bfcf67))
+* draw presenters a portrait frame, and stop the crop copying the sweep ([a41eb27](https://github.com/tonygorb/Scenri/commit/a41eb271c03a3130085637ac88d030034d552d3e))
+* make a multi-image run one coherent set ([a463074](https://github.com/tonygorb/Scenri/commit/a463074c6fe28e048b95d5848e660146f5c6b9f9))
+* make a multi-image run one coherent set ([d4ae447](https://github.com/tonygorb/Scenri/commit/d4ae4479965f779b18c41d4d518b84c5a69428a9))
+* preview the same identity payload a generation sends ([15a8d30](https://github.com/tonygorb/Scenri/commit/15a8d304807e271c21f28929976551b8bee914f4))
+* record which view every attachment is, and settle the portrait untouched ([9f1a1a4](https://github.com/tonygorb/Scenri/commit/9f1a1a4bff8b5237f7e322ab6fcffd62a6d836b9))
+* send the presenter portrait that was already on disk ([bbd3def](https://github.com/tonygorb/Scenri/commit/bbd3defbfd936cd0bc672e0e66b5399637ec2d89))
+
 ## [0.7.0](https://github.com/tonygorb/Scenri/compare/v0.6.13...v0.7.0) (2026-08-30)
 
 

package/dist/serve.js

@@ -1315,6 +1315,7 @@ var EDIT_REFERENCE_ROLE_DIRECTIVE = {
   style: "a reference for treatment and mood only",
   reference: "a reference for composition, lighting and treatment only"
 };
+var BUDGET_EXHAUSTED = "scenri:budget-exhausted";
 var ASPECT_TOLERANCE = 0.15;
 var NAMED_RATIOS = [
   ["1:1", 1],
@@ -1363,6 +1364,7 @@ function createCore(homeDir = defaultHome()) {
   };
 }
 var ENDPOINT = "https://openrouter.ai/api/v1/chat/completions";
+var PER_IMAGE_TIMEOUT_MS = 3e5;
 var DEFAULT_MODEL = "google/gemini-2.5-flash-image";
 var DEFAULT_COST_PER_IMAGE_USD = 0.04;
 function dataUrl(path) {
@@ -1401,6 +1403,7 @@ function createOpenRouterEngine(opts) {
     return key;
   }
   async function post(key, body, signal) {
+    const bound = AbortSignal.timeout(PER_IMAGE_TIMEOUT_MS);
     const res = await fetchImpl(ENDPOINT, {
       method: "POST",
       headers: {
@@ -1408,7 +1411,7 @@ function createOpenRouterEngine(opts) {
         "Content-Type": "application/json"
       },
       body: JSON.stringify(body),
-      signal
+      signal: signal ? AbortSignal.any([signal, bound]) : bound
     });
     const text = await res.text();
     if (!res.ok) {
@@ -1451,7 +1454,11 @@ function createOpenRouterEngine(opts) {
         localOnly: false,
         supportsEdit: true,
         supportsMask: false,
-        maxReferenceImages: 4
+        maxReferenceImages: 4,
+        // N sequential calls, one image each: the server budgets the node by
+        // that shape instead of handing the whole run one flat ten minutes.
+        perImageTimeoutMs: PER_IMAGE_TIMEOUT_MS,
+        imageConcurrency: 1
       };
     },
     async isAvailable() {
@@ -1492,7 +1499,12 @@ function createOpenRouterEngine(opts) {
       let reportedCost = 0;
       let sawReportedCost = false;
       for (let i = 0; i < req.count; i++) {
-        const json = await post(key, body, signal);
+        const variation = req.variations?.[i];
+        const json = await post(
+          key,
+          variation ? { ...body, messages: [{ role: "user", content: [...content, { type: "text", text: variation }] }] } : body,
+          signal
+        );
         raws.push(json);
         for (const buf of extractImages(json)) hashes.push(opts.saveImage(buf));
         if (typeof json?.usage?.cost === "number") {
@@ -2527,9 +2539,6 @@ function createCodexSetup(opts = {}) {
 
 // ../engines/codex/src/index.ts
 var CODEX_POOL = 2;
-function codexNodeBudgetMs(count) {
-  return Math.ceil(Math.max(1, count) / CODEX_POOL) * DEFAULT_TIMEOUT_MS2 + 6e4;
-}
 function orientationOf(width, height) {
   return width === height ? "square" : width > height ? "landscape" : "portrait";
 }
@@ -2561,7 +2570,7 @@ function createCodexEngine(opts) {
       return /* @__PURE__ */ new Set();
     }
   }
-  async function collectImages(dir, before = null) {
+  async function collectImages(dir, before = null, claimed) {
     const entries = await readdir(dir);
     const outFiles = entries.filter((name) => /^out-.*\.png$/.test(name)).sort((a, b) => {
       const na = Number(/^out-(\d+)\.png$/.exec(a)?.[1] ?? NaN);
@@ -2571,7 +2580,7 @@ function createCodexEngine(opts) {
     });
     if (outFiles.length === 0) {
       if (before) {
-        const recovered = await recoverFromGenerated(before);
+        const recovered = await recoverFromGenerated(before, claimed);
         if (recovered) return [recovered];
       }
       throw new Error("Codex finished but produced no images");
@@ -2584,11 +2593,11 @@ function createCodexEngine(opts) {
     }
     return hashes;
   }
-  async function recoverFromGenerated(before) {
+  async function recoverFromGenerated(before, claimed) {
     const home = generatedImagesDir();
     let names;
     try {
-      names = (await readdir(home)).filter((n) => !before.has(n));
+      names = (await readdir(home)).filter((n) => !before.has(n) && !claimed?.has(n));
     } catch {
       return null;
     }
@@ -2596,6 +2605,7 @@ function createCodexEngine(opts) {
     const stamped = await Promise.all(names.map(async (n) => ({ n, mtime: (await stat(join(home, n))).mtimeMs })));
     stamped.sort((a, b) => b.mtime - a.mtime);
     const pick2 = stamped[0].n;
+    claimed?.add(pick2);
     console.warn(`codex: workdir empty, recovered ${pick2} from ${home}`);
     return saveImage(await readFile(join(home, pick2)));
   }
@@ -2645,7 +2655,12 @@ function createCodexEngine(opts) {
          * budget — a full-resolution phone-photo PNG is tens of megabytes that
          * buy nothing. Same cap as brand marks (MARK_MAX_EDGE).
          */
-        maxReferenceEdge: 2048
+        maxReferenceEdge: 2048,
+        // One exec per image at CODEX_POOL at a time, each carrying its own
+        // full timer. The server turns these two numbers into the node bound,
+        // which is the same arithmetic codexNodeBudgetMs states above.
+        perImageTimeoutMs: DEFAULT_TIMEOUT_MS2,
+        imageConcurrency: CODEX_POOL
       };
     },
     isAvailable() {
@@ -2659,8 +2674,9 @@ function createCodexEngine(opts) {
       const refs = req.referenceImages ?? [];
       const roles = req.referenceRoles ?? refs.map(() => "reference");
       const inner = new AbortController();
-      const onOuterAbort = () => inner.abort();
-      if (signal?.aborted) inner.abort();
+      const claimed = /* @__PURE__ */ new Set();
+      const onOuterAbort = () => inner.abort(signal?.reason);
+      if (signal?.aborted) inner.abort(signal.reason);
       else signal?.addEventListener("abort", onOuterAbort, { once: true });
       const jobs = Array.from(
         { length: count },
@@ -2679,7 +2695,7 @@ function createCodexEngine(opts) {
             stdin: buildPrompt2(req, i, roles),
             label: `gen v${i + 1}/${count} refs=${refs.length} refKB=${Math.round(refBytes / 1024)}`
           });
-          return collectImages(dir, before);
+          return collectImages(dir, before, claimed);
         })
       );
       const results = new Array(count);
@@ -2693,7 +2709,7 @@ function createCodexEngine(opts) {
             try {
               results[i] = await jobs[i]();
             } catch (err) {
-              if (signal?.aborted) throw err;
+              if (signal?.aborted && signal.reason !== BUDGET_EXHAUSTED) throw err;
               results[i] = [];
               failures.push(err);
               if (fatal == null && isFatalSetupError(err)) {
@@ -2776,10 +2792,10 @@ function createCodexEngine(opts) {
     );
   }
   function buildPrompt2(req, index, roles) {
+    const variation = req.variations?.[index] ?? "";
     const roleDirective = REFERENCE_ROLE_DIRECTIVE;
     const names = refFileNames(roles, roles.length);
     const refDirectives = roles.map((role, i) => `${names[i]} shows ${roleDirective[role]}.`).join(" ");
-    const count = Math.max(1, req.count);
     const native = codexNativeSize(req.width, req.height);
     return (
       // "professional-grade", not "flawless": the audit of the waxy-presenter
@@ -2793,13 +2809,19 @@ function createCodexEngine(opts) {
       // to the requested one, and the aspect check passed BECAUSE of the shear
       // - the reported crushed faces. Copy/move stays licensed because the
       // win32 recovery path moves files out of generated_images.
-      ` Do not browse the web or explore files. Save the tool's output in the current directory as out-1.png, byte-for-byte unchanged: you may run the commands needed to copy or move the file, but never resize, scale, stretch, pad, crop or re-encode it \u2014 deliver the tool's own pixels at the tool's own size. Nothing else.` + // Every take in a batch gets the SAME-shaped clause. Take 1 used to get
-      // nothing - so the first output was literally asked for the most
-      // reference-faithful decode - and later takes were licensed to a
-      // "different composition", which read as permission to drift from the
-      // directives. Reported as: output #1 copies the scene reference, output
-      // #2 mixes identities. A single generation stays byte-stable.
-      (count > 1 ? ` (take ${index + 1} of ${count} \u2014 same brief, same identities and constraints, a naturally different moment and framing of the same shoot)` : "")
+      ` Do not browse the web or explore files. Save the tool's output in the current directory as out-1.png, byte-for-byte unchanged: you may run the commands needed to copy or move the file, but never resize, scale, stretch, pad, crop or re-encode it \u2014 deliver the tool's own pixels at the tool's own size. Nothing else.` + // The set clause, built once by the server for the whole run and handed
+      // over index-aligned with the output slots. It carries the photographic
+      // move this frame explores and the locks every frame shares.
+      //
+      // What used to be here was a COUNTER — "take 3 of 4". Every take got the
+      // same-shaped sentence, so this was already the hardened version, and the
+      // drift survived it: a rising take number is not neutral text. In shoot
+      // language it reads as "we have already done that, go further", a licence
+      // to deviate that grows with the output index, which is precisely the
+      // reported shape (output 1 holds the presenter, 2 and 3 and 4 drift). No
+      // frame is described in terms of any other frame now, and no number
+      // reaches the model at all.
+      (variation ? ` ${variation}` : "")
     );
   }
 }
@@ -3015,14 +3037,22 @@ function presenterRefPath(templatesRoot, id, slot) {
 function presenterAvatarPath(templatesRoot, id) {
   return contentFile(templatesRoot, "previews", "presenters", id, "avatar.jpg");
 }
+var resolvedRefs = /* @__PURE__ */ new Map();
+async function refHash(core, path) {
+  const hit = resolvedRefs.get(path);
+  if (hit && core.images.has(hit)) return hit;
+  const hash = core.images.save(await sharp20(readFileSync(path)).png().toBuffer());
+  resolvedRefs.set(path, hash);
+  return hash;
+}
 async function resolvePresenterImages(core, templatesRoot, presenter) {
   const shots = [];
+  const avatar = presenterAvatarPath(templatesRoot, presenter.id);
+  if (existsSync(avatar)) shots.push({ file: `asset:${await refHash(core, avatar)}`, angle: "portrait", locked: true });
   for (const [slot, angle] of PRESENTER_ANGLES) {
     const path = presenterRefPath(templatesRoot, presenter.id, slot);
     if (!existsSync(path)) continue;
-    const png = await sharp20(readFileSync(path)).png().toBuffer();
-    const hash = core.images.save(png);
-    shots.push({ file: `asset:${hash}`, angle, locked: true });
+    shots.push({ file: `asset:${await refHash(core, path)}`, angle, locked: true });
   }
   if (!shots.length) return null;
   return {
@@ -3031,6 +3061,8 @@ async function resolvePresenterImages(core, templatesRoot, presenter) {
     ...presenter.identityNotes ? { identityNotes: presenter.identityNotes } : {},
     ...presenter.negativeConstraints?.length ? { negativeConstraints: presenter.negativeConstraints } : {},
     ...presenter.skin ? { skin: presenter.skin } : {},
+    ...presenter.facial ? { facial: presenter.facial } : {},
+    ...presenter.build ? { build: presenter.build } : {},
     shots
   };
 }
@@ -3288,6 +3320,7 @@ async function capReferenceEdge(core, path, maxEdge) {
       out = core.images.pathFor(core.images.save(buf));
     }
   } catch {
+    return path;
   }
   cappedRefs.set(key, out);
   return out;
@@ -3557,17 +3590,25 @@ function compileBrief(brief, ctx) {
         append(p.promptName ?? p.name);
         const primary = tok.angle && p.shots?.find((s) => s.angle === tok.angle) || p.shots?.[0];
         const orderedShots = [primary, ...(p.shots ?? []).filter((s) => s && s !== primary)];
-        const phashes = [];
+        const pshots = [];
         for (const s of orderedShots) {
-          if (phashes.length >= PRODUCT_REF_MAX) break;
+          if (pshots.length >= PRODUCT_REF_MAX) break;
           const h = assetHash2(s?.file);
-          if (h && ctx.images.has(h) && !phashes.includes(h)) phashes.push(h);
+          if (h && ctx.images.has(h) && !pshots.some((x) => x.h === h))
+            pshots.push({ h, ...s?.angle ? { angle: String(s.angle) } : {} });
         }
-        if (phashes.length) {
-          phashes.forEach((h, i) => {
-            attachments.push({ role: "product", id: p.id, label: p.name, hash: h, essential: i === 0 });
+        if (pshots.length) {
+          pshots.forEach(({ h, angle }, i) => {
+            attachments.push({
+              role: "product",
+              id: p.id,
+              label: p.name,
+              hash: h,
+              essential: i === 0,
+              ...angle ? { angle } : {}
+            });
           });
-          productDirectives.push(productFidelityDirective(phashes.length));
+          productDirectives.push(productFidelityDirective(pshots.length));
           productDirectives.push(...productFactDirectives(p));
           if (p.description && !p.dimensions)
             productDirectives.push(
@@ -3586,10 +3627,17 @@ function compileBrief(brief, ctx) {
         }
         hasPerson = true;
         append(c.promptName ?? c.name);
-        const chashes = (c.shots ?? []).slice(0, CHARACTER_REF_MAX).map((s) => assetHash2(s?.file)).filter((h) => !!h && ctx.images.has(h));
-        if (chashes.length) {
-          chashes.forEach((chash, i) => {
-            attachments.push({ role: "character", id: c.id, label: c.name, hash: chash, essential: i === 0 });
+        const cshots = (c.shots ?? []).slice(0, CHARACTER_REF_MAX).map((s) => ({ h: assetHash2(s?.file), angle: s?.angle ? String(s.angle) : void 0 })).filter((x) => !!x.h && ctx.images.has(x.h));
+        if (cshots.length) {
+          cshots.forEach(({ h, angle }, i) => {
+            attachments.push({
+              role: "character",
+              id: c.id,
+              label: c.name,
+              hash: h,
+              essential: i === 0,
+              ...angle ? { angle } : {}
+            });
           });
           personDirectives.push(
             `${c.promptName ?? c.name} is in this photograph: a real person, clearly visible in the frame. Do not leave them out, crop them out, or reduce them to a reflection or a shadow.`
@@ -3602,6 +3650,11 @@ function compileBrief(brief, ctx) {
             personDirectives.push(
               `${c.promptName ?? c.name}'s skin, exactly as the reference photographs show it: ${c.skin}.`
             );
+          if (c.facial)
+            personDirectives.push(
+              `${c.promptName ?? c.name}'s face, which must survive every generation unchanged: ${c.facial}.`
+            );
+          if (c.build) personDirectives.push(`${c.promptName ?? c.name}'s build: ${c.build}.`);
         } else {
           warnings.push(`${c.name} has no usable photo, so they are named but not attached.`);
         }
@@ -5984,7 +6037,8 @@ function presenterRecordFrom(input, base) {
   const has = (k) => input[k] !== void 0;
   const name = has("name") ? str3(input.name, 60) : base?.name ?? "";
   if (!name) return { ok: false, error: "a presenter needs a name" };
-  const shots = has("shotHashes") ? strList(input.shotHashes, 8, 64).map((h) => assetRef(h)).filter((f) => !!f).map((file) => ({ file, locked: true })) : base?.shots ?? [];
+  const angles = has("shotAngles") ? strList(input.shotAngles, 8, 32) : [];
+  const shots = has("shotHashes") ? strList(input.shotHashes, 8, 64).map((h) => assetRef(h)).filter((f) => !!f).map((file, i) => angles[i] ? { file, angle: angles[i], locked: true } : { file, locked: true }) : base?.shots ?? [];
   if (!shots.length) return { ok: false, error: "a presenter needs at least one photo" };
   const sources = has("sourceHashes") ? strList(input.sourceHashes, 8, 64).map((h) => assetRef(h)).filter((f) => !!f).map((file) => ({ file })) : base?.sourceRefs;
   const presenter = {
@@ -6122,6 +6176,26 @@ async function runBuild(deps, job, hashes, instruction, signal) {
   }
 }
 var STUDIO_FRAMES = [
+  /*
+   * The identity frame, and it comes first because that is the order a brief
+   * attaches: `shots[0]` is the essential character reference.
+   *
+   * Every other frame here is full-length head-to-toe, which is right for
+   * build, proportion and wardrobe and useless for a face — in a 1024x1280
+   * full-length frame the face is about 105px brow to chin, while a portrait
+   * output renders it at four times that. Measured 2026-08-30 against the
+   * reported failure: four outputs of one brief, four different jaws, and
+   * drift that tracked nothing but how big the face was in the output.
+   *
+   * Drawn `from: 'sources'` rather than chained off the front view, because
+   * the user's own photographs are the only real face evidence in the system
+   * and a chain would just enlarge the same 105px.
+   */
+  {
+    angle: "portrait",
+    from: "sources",
+    subject: (who) => `${who}, head-and-shoulders portrait framing from just above the top of the head down to the collarbone, facing the camera straight-on, relaxed neutral expression, eyes to the lens, their own hair exactly as the references show it, the same plain studio backdrop and even frontal light`
+  },
   {
     angle: "front",
     from: "sources",
@@ -6174,22 +6248,28 @@ async function runPresenterBuild(deps, job, hashes, instruction, signal) {
   }
   if (signal.aborted) throw new Error("cancelled");
   let shotHashes = hashes;
+  let shotAngles = [];
   const warnings = [];
   if (deps.engine) {
     patch(job, { stage: "building", steps: STUDIO_FRAMES.length, message: "Building the studio views" });
     const built2 = await generateStudioSet(deps, job, whoIs(job.name, draft), sourcePaths, signal);
-    if (built2.length) shotHashes = built2;
-    else warnings.push("The studio views could not be drawn, so the photos are being used directly.");
+    if (built2.hashes.length) {
+      shotHashes = built2.hashes;
+      shotAngles = built2.angles;
+    } else warnings.push("The studio views could not be drawn, so the photos are being used directly.");
   } else {
     warnings.push("No engine could draw the studio views, so the photos are being used directly.");
   }
   if (signal.aborted) throw new Error("cancelled");
   patch(job, { stage: "saving", message: null });
   const generated = shotHashes !== hashes;
-  const { previewHash, avatarHash } = await presenterCrops(core, shotHashes[0], generated ? "generated" : "upload");
+  const frontIndex = shotAngles.indexOf("front");
+  const cardSource = frontIndex === -1 ? shotHashes[0] : shotHashes[frontIndex];
+  const { previewHash, avatarHash } = await presenterCrops(core, cardSource, generated ? "generated" : "upload");
   const built = presenterRecordFrom({
     name: job.name,
     shotHashes,
+    shotAngles,
     sourceHashes: hashes,
     previewHash,
     avatarHash,
@@ -6212,16 +6292,16 @@ async function runPresenterBuild(deps, job, hashes, instruction, signal) {
     stage: "done",
     step: job.steps,
     assetId: built.presenter.id,
-    previewHash: previewHash ?? shotHashes[0] ?? null,
+    previewHash: previewHash ?? cardSource ?? null,
     warnings: [...job.warnings, ...warnings],
     finished: true
   });
 }
 async function generateStudioSet(deps, job, who, sourcePaths, signal) {
   const engine = deps.engine;
-  if (!engine) return [];
+  if (!engine) return { hashes: [], angles: [] };
   const caps = engine.capabilities();
-  if (!caps.maxReferenceImages) return [];
+  if (!caps.maxReferenceImages) return { hashes: [], angles: [] };
   const byAngle = /* @__PURE__ */ new Map();
   for (const frame of STUDIO_FRAMES) {
     if (signal.aborted) throw new Error("cancelled");
@@ -6248,7 +6328,8 @@ async function generateStudioSet(deps, job, who, sourcePaths, signal) {
       patch(job, { warnings: [...job.warnings, `The ${frame.angle} view could not be drawn.`] });
     }
   }
-  return STUDIO_FRAMES.map((f) => byAngle.get(f.angle)).filter((h) => !!h);
+  const kept = STUDIO_FRAMES.filter((f) => byAngle.get(f.angle));
+  return { hashes: kept.map((f) => byAngle.get(f.angle)), angles: kept.map((f) => f.angle) };
 }
 async function edgeBarGeometry(buf) {
   const { data, info } = await sharp20(buf).greyscale().raw().toBuffer({ resolveWithObject: true });
@@ -6346,6 +6427,64 @@ async function avatarCrop(core, hash) {
     AVATAR_MAX_PX
   );
 }
+var IDENTITY_FIGURE_FRACTION = 0.26;
+var IDENTITY_HEADROOM = 0.08;
+var IDENTITY_ASPECT = 0.66;
+var IDENTITY_TARGET_HEIGHT = 1280;
+var IDENTITY_MAX_UPSCALE = 3;
+var STANDING_FIGURE_RATIO = 2.2;
+async function identityCrop(core, hash) {
+  if (!hash || !core.images.has(hash)) return void 0;
+  const hit = identityCrops.get(hash);
+  if (hit && core.images.has(hit)) return hit;
+  let box = null;
+  try {
+    box = await figureBox(core.images.read(hash));
+  } catch {
+    box = null;
+  }
+  if (!box) return void 0;
+  if (box.height / Math.max(1, box.width) < STANDING_FIGURE_RATIO) return void 0;
+  let nativeHeight = 0;
+  const out = await crop(core, hash, (w, h) => {
+    const height = Math.min(h, Math.max(16, Math.round(box.height * IDENTITY_FIGURE_FRACTION)));
+    const width = Math.min(w, Math.max(16, Math.round(height * IDENTITY_ASPECT)));
+    nativeHeight = height;
+    const top = Math.min(Math.max(0, Math.round(box.top - height * IDENTITY_HEADROOM)), h - height);
+    const left = Math.min(Math.max(0, Math.round(box.left + box.width / 2 - width / 2)), w - width);
+    return { left, top, width, height };
+  });
+  if (!out) return void 0;
+  try {
+    const height = Math.min(IDENTITY_TARGET_HEIGHT, Math.round(nativeHeight * IDENTITY_MAX_UPSCALE)) || IDENTITY_TARGET_HEIGHT;
+    const png = await sharp20(core.images.read(out)).resize({ height, fit: "inside", kernel: "lanczos3", withoutEnlargement: false }).png().toBuffer();
+    const scaled = core.images.save(png);
+    identityCrops.set(hash, scaled);
+    return scaled;
+  } catch {
+    identityCrops.set(hash, out);
+    return out;
+  }
+}
+var identityCrops = /* @__PURE__ */ new Map();
+async function brandJsonWithIdentityCrops(core, json, characterIds) {
+  const wanted = new Set(characterIds);
+  const roster = json?.characters ?? [];
+  if (!wanted.size || !roster.length) return json;
+  let changed = false;
+  const characters = await Promise.all(
+    roster.map(async (c) => {
+      if (!wanted.has(c?.id) || !c?.shots?.length) return c;
+      if (c.shots[0]?.angle === "portrait") return c;
+      const front = String(c.shots[0]?.file ?? "").replace(/^asset:/, "") || null;
+      const cropped = await identityCrop(core, front ?? void 0);
+      if (!cropped) return c;
+      changed = true;
+      return { ...c, shots: [{ file: `asset:${cropped}`, angle: "identity", locked: true }, ...c.shots] };
+    })
+  );
+  return changed ? { ...json, characters } : json;
+}
 async function figureBox(buf) {
   const meta = await sharp20(buf).metadata();
   const W = meta.width ?? 0;
@@ -6616,6 +6755,49 @@ function inheritedIdentityTokens(parentId, getNode) {
   return { tokens: [], truncated: id !== null };
 }
 
+// src/variationPlan.ts
+var OPEN_LADDER = [
+  "Frame this one as the direction describes it, the straight read of the brief.",
+  "Step the camera to one side of where the direction places it, and let the pose settle with the move.",
+  "Frame tighter on the subject than the straight read, same lens character.",
+  "Drop the eye line a little and leave more air in the frame.",
+  "Step back for a wider read of the same setup.",
+  "Come round to a three-quarter view of the same arrangement.",
+  "Take it from slightly above, the same distance.",
+  "Hold the same framing and let the subject carry a different beat of the same moment."
+];
+var FIXED_LADDER = [
+  "Frame this one as the direction describes it, the straight read of the brief.",
+  "Keep the camera the direction asks for and shift it a little laterally.",
+  "Keep the camera the direction asks for and let the weight and hands settle differently.",
+  "Keep the camera the direction asks for and change the head angle slightly.",
+  "Keep the camera the direction asks for and let the light fall a touch differently across the same setup.",
+  "Keep the camera the direction asks for and give the expression a different beat of the same moment.",
+  "Keep the camera the direction asks for and rearrange the near foreground slightly.",
+  "Keep the camera the direction asks for and let the pose breathe a little wider."
+];
+function locks(ctx) {
+  const parts = [
+    "Every frame in this run belongs to one continuous shoot: the same location, the same light, and the same wardrobe garment for garment, changing only as the pose moves the cloth."
+  ];
+  if (ctx.hasPresenter)
+    parts.push(
+      "The person is the one in the character references and nobody else, unchanged in face, hair, build and skin."
+    );
+  if (ctx.hasProduct)
+    parts.push(
+      "The product is the one in the product references and no other, unchanged in geometry, packaging, label and colour."
+    );
+  if (ctx.hasMark) parts.push("The brand mark stays exactly as drawn.");
+  return parts.join(" ");
+}
+function variationPlan(count, ctx) {
+  if (!Number.isFinite(count) || count <= 1) return [];
+  const ladder = ctx.cameraFixed ? FIXED_LADDER : OPEN_LADDER;
+  const shared = locks(ctx);
+  return Array.from({ length: Math.floor(count) }, (_, i) => `${ladder[i % ladder.length]} ${shared}`);
+}
+
 // src/editScopeRules.ts
 var GLOBAL_CUES = [
   ["light", /\b(light|lighting|lit|relight|exposure|white ?balance|backlit|shadows everywhere)\b/i],
@@ -8467,6 +8649,25 @@ function registerImageRoutes(app, deps) {
 
 // src/release/notes.data.ts
 var RELEASES = [
+  {
+    version: "0.7.1",
+    date: "2026-08-30",
+    title: "Four images from one brief are one set.",
+    sections: [
+      {
+        heading: "Create",
+        body: "Asking for two, three or four images returns variations of one shot rather than four readings of it. The presenter, the product, the scene and the brand hold across the set, and so does the wardrobe. What changes is the photography: each frame explores a different camera position, crop or pose within the brief you wrote."
+      },
+      {
+        heading: "Presenters",
+        body: "A selected presenter now reaches generation as a portrait, not only as full-length views, so their face carries into every image of a run instead of being rebuilt each time. Presenters built in Scenri gain a head-and-shoulders reference of their own, and their casting notes reach the shot."
+      },
+      {
+        heading: "Fixes",
+        body: "A run that takes too long keeps the images that already finished instead of throwing them away with the rest. Refining a shot conditions on the same presenter portrait the generation used."
+      }
+    ]
+  },
   {
     version: "0.7.0",
     date: "2026-08-30",
@@ -9502,18 +9703,22 @@ function buildServer(opts) {
     );
     const inheritedTokens = borrowed.filter((t) => !already.has(identityTokenKey(t)));
     const combined = [...brief.tokens, ...inheritedTokens];
-    const brandJson = await brandJsonWithResolvedPresenters(
+    const brandJson = await brandJsonWithIdentityCrops(
       core,
-      templatesRoot,
-      presenters,
-      await brandJsonWithResolvedDemoProducts(
+      await brandJsonWithResolvedPresenters(
         core,
         templatesRoot,
-        demoProducts,
-        brandJsonWithCatalogProducts(core, brandId),
+        presenters,
+        await brandJsonWithResolvedDemoProducts(
+          core,
+          templatesRoot,
+          demoProducts,
+          brandJsonWithCatalogProducts(core, brandId),
+          combined
+        ),
         combined
       ),
-      combined
+      combined.filter((t) => t.t === "character").map((t) => t.id)
     );
     const sceneById = sceneFor(brandJson);
     const uncapped = { ...engineCaps, maxReferenceImages: 32 };
@@ -9640,18 +9845,22 @@ function buildServer(opts) {
         referenceCount: edit.merged.kept.length
       };
     }
-    const brandJson = await brandJsonWithResolvedPresenters(
+    const brandJson = await brandJsonWithIdentityCrops(
       core,
-      templatesRoot,
-      presenters,
-      await brandJsonWithResolvedDemoProducts(
+      await brandJsonWithResolvedPresenters(
         core,
         templatesRoot,
-        demoProducts,
-        brandJsonWithCatalogProducts(core, brand.id),
+        presenters,
+        await brandJsonWithResolvedDemoProducts(
+          core,
+          templatesRoot,
+          demoProducts,
+          brandJsonWithCatalogProducts(core, brand.id),
+          brief.tokens
+        ),
         brief.tokens
       ),
-      brief.tokens
+      (brief.tokens ?? []).filter((t) => t.t === "character").map((t) => t.id)
     );
     const sceneById = sceneFor(brandJson);
     const compiled2 = compileBrief(brief, {
@@ -9795,7 +10004,7 @@ function buildServer(opts) {
     let watchdogFired = false;
     const watchdog = setTimeout(() => {
       watchdogFired = true;
-      ctrl.abort();
+      ctrl.abort(BUDGET_EXHAUSTED);
     }, bound);
     const startedAt = Date.now();
     try {
@@ -9944,18 +10153,22 @@ function buildServer(opts) {
         if (!compiled2.prompt.trim() && reshape !== "extend")
           return reply.status(400).send({ error: "the brief is empty" });
       } else {
-        const brandJson = await brandJsonWithResolvedPresenters(
+        const brandJson = await brandJsonWithIdentityCrops(
           core,
-          templatesRoot,
-          presenters,
-          await brandJsonWithResolvedDemoProducts(
+          await brandJsonWithResolvedPresenters(
             core,
             templatesRoot,
-            demoProducts,
-            brandJsonWithCatalogProducts(core, project.brandId),
+            presenters,
+            await brandJsonWithResolvedDemoProducts(
+              core,
+              templatesRoot,
+              demoProducts,
+              brandJsonWithCatalogProducts(core, project.brandId),
+              brief.tokens
+            ),
             brief.tokens
           ),
-          brief.tokens
+          (brief.tokens ?? []).filter((t) => t.t === "character").map((t) => t.id)
         );
         const sceneById = sceneFor(brandJson);
         compiled2 = compileBrief(brief, {
@@ -10021,6 +10234,7 @@ function buildServer(opts) {
     }
     if (kind === "generation") {
       const cap2 = engine.capabilities().maxReferenceImages;
+      const wantedCount = Math.min(Math.max(1, Number(count)), 8);
       const lostIdentity = engine.capabilities().placeholder ? [] : (compiled2?.dropped ?? []).filter((d) => d.essential);
       if (lostIdentity.length) {
         const names = joinNames(lostIdentity.map((d) => d.label));
@@ -10032,14 +10246,23 @@ function buildServer(opts) {
       const maxEdge = engine.capabilities().maxReferenceEdge;
       const keptRefs = referenceImages && cap2 > 0 ? referenceImages.slice(0, cap2) : void 0;
       const sentRefs = keptRefs && maxEdge ? await Promise.all(keptRefs.map((p) => capReferenceEdge(core, p, maxEdge))) : keptRefs;
+      const sentRoles = referenceRoles && cap2 > 0 ? referenceRoles.slice(0, cap2) : referenceRoles ?? [];
+      const briefText = Array.isArray(brief?.tokens) ? brief.tokens.filter((t) => t?.t === "text").map((t) => String(t?.v ?? "")).join(" ") : String(prompt ?? "");
+      const variations = variationPlan(wantedCount, {
+        hasPresenter: sentRoles.includes("character"),
+        hasProduct: sentRoles.includes("product"),
+        hasMark: sentRoles.includes("brand"),
+        cameraFixed: shotSpecifiesCamera(briefText)
+      });
       const genReq = {
         prompt: finalPrompt,
         brand: ctx,
         width: Number(width),
         height: Number(height),
-        count: Math.min(Math.max(1, Number(count)), 8),
+        count: wantedCount,
         ...sentRefs ? { referenceImages: sentRefs } : {},
-        ...referenceRoles && cap2 > 0 ? { referenceRoles: referenceRoles.slice(0, cap2) } : {}
+        ...sentRoles.length && cap2 > 0 ? { referenceRoles: sentRoles } : {},
+        ...variations.length ? { variations } : {}
       };
       estimate = await engine.costEstimate(genReq);
       work = (signal) => engine.generate(genReq, signal);
@@ -10328,7 +10551,8 @@ function buildServer(opts) {
       }
       return enforceEditCanvas(staged);
     } : kind === "generation" && compiled2?.width && compiled2?.height ? conformToCanvas(node.id, { width: compiled2.width, height: compiled2.height }) : void 0;
-    const nodeBudgetMs = kind === "generation" && runEngine.capabilities().id === "codex-cli" ? codexNodeBudgetMs(Math.min(Math.max(1, Number(count)), 8)) : void 0;
+    const runCaps = runEngine.capabilities();
+    const nodeBudgetMs = kind === "generation" && runCaps.perImageTimeoutMs ? Math.ceil(Math.min(Math.max(1, Number(count)), 8) / Math.max(1, runCaps.imageConcurrency ?? 1)) * runCaps.perImageTimeoutMs + 6e4 : void 0;
     void runNode(node.id, runEngine, estimate, work, expectShape, post, nodeBudgetMs).catch(
       (err) => app.log.error({ err }, "node run failed")
     );

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "scenri",
-  "version": "0.7.0",
+  "version": "0.7.1",
   "author": "Tony Gorb <hello@scenri.co>",
   "license": "AGPL-3.0-only",
   "type": "module",