scenri 0.7.4 → 0.7.5

package/dist/serve.js

@@ -212,11 +212,13 @@ function widenNodeStatusCheck(db) {
         overlays TEXT NOT NULL DEFAULT '{}',
         brief TEXT,
         archived INTEGER NOT NULL DEFAULT 0,
-        duration_ms INTEGER
+        duration_ms INTEGER,
+        batch_id TEXT,
+        batch_index INTEGER NOT NULL DEFAULT 0
       );
       INSERT INTO nodes_new
         SELECT id, project_id, parent_id, kind, prompt, engine_id, status, images, cost_usd, kept, error,
-               created_at, overlays, brief, archived, duration_ms
+               created_at, overlays, brief, archived, duration_ms, batch_id, batch_index
         FROM nodes;
       DROP TABLE nodes;
       ALTER TABLE nodes_new RENAME TO nodes;
@@ -295,11 +297,104 @@ function collapseProjects(db) {
     })();
   }
 }
-var SCHEMA_VERSION = 1;
+function splitMultiImageNodes(db) {
+  const rows = db.prepare("SELECT * FROM nodes").all();
+  const multi = rows.filter((r) => {
+    try {
+      return JSON.parse(r.images).length > 1;
+    } catch {
+      return false;
+    }
+  });
+  if (!multi.length) return;
+  const parse2 = (s) => {
+    if (!s) return null;
+    try {
+      return JSON.parse(s);
+    } catch {
+      return null;
+    }
+  };
+  const stampOf = (iso, minusMs) => {
+    const t = (/* @__PURE__ */ new Date(`${iso.replace(" ", "T")}Z`)).getTime() - minusMs;
+    const d = new Date(t);
+    const p = (n, w = 2) => String(n).padStart(w, "0");
+    return `${d.getUTCFullYear()}-${p(d.getUTCMonth() + 1)}-${p(d.getUTCDate())} ${p(d.getUTCHours())}:${p(d.getUTCMinutes())}:${p(d.getUTCSeconds())}.${p(d.getUTCMilliseconds(), 3)}`;
+  };
+  const updateOriginal = db.prepare(
+    "UPDATE nodes SET images=?, overlays=?, brief=?, batch_id=?, batch_index=0 WHERE id=?"
+  );
+  const insertSibling = db.prepare(
+    `INSERT INTO nodes (id, project_id, parent_id, kind, prompt, engine_id, status, images, cost_usd, kept,
+       error, created_at, overlays, brief, archived, duration_ms, batch_id, batch_index)
+     VALUES (?,?,?,?,?,?,?,?,0,?,?,?,?,?,?,NULL,?,?)`
+  );
+  const childrenOf = db.prepare("SELECT id, brief FROM nodes WHERE parent_id=?");
+  const repoint = db.prepare("UPDATE nodes SET parent_id=? WHERE id=?");
+  const setsOf = db.prepare("SELECT set_id FROM set_nodes WHERE node_id=?");
+  const addMember = db.prepare("INSERT OR IGNORE INTO set_nodes (set_id, node_id) VALUES (?,?)");
+  db.transaction(() => {
+    for (const r of multi) {
+      const images = JSON.parse(r.images);
+      const overlays = parse2(r.overlays) ?? {};
+      const brief = parse2(r.brief);
+      const sizes = Array.isArray(brief?.rendered?.sizes) ? brief.rendered.sizes : null;
+      const briefFor = (i) => {
+        if (!brief) return null;
+        const b = { ...brief, variants: images.length };
+        if (brief.rendered) {
+          const { requested: _req, variantIndexes: _vi, ...rendered } = brief.rendered;
+          b.rendered = { ...rendered, ...sizes ? { sizes: sizes[i] !== void 0 ? [sizes[i]] : [] } : {} };
+        }
+        return JSON.stringify(b);
+      };
+      const siblingIds = [r.id];
+      updateOriginal.run(
+        JSON.stringify([images[0]]),
+        JSON.stringify(overlays["0"] !== void 0 ? { "0": overlays["0"] } : {}),
+        briefFor(0),
+        r.id,
+        r.id
+      );
+      for (let i = 1; i < images.length; i++) {
+        const id = randomUUID();
+        siblingIds.push(id);
+        insertSibling.run(
+          id,
+          r.project_id,
+          r.parent_id,
+          r.kind,
+          r.prompt,
+          r.engine_id,
+          r.status,
+          JSON.stringify([images[i]]),
+          r.kept,
+          r.error,
+          stampOf(r.created_at, i),
+          JSON.stringify(overlays[String(i)] !== void 0 ? { "0": overlays[String(i)] } : {}),
+          briefFor(i),
+          r.archived,
+          r.id,
+          i
+        );
+      }
+      for (const child of childrenOf.all(r.id)) {
+        const src = parse2(child.brief)?.sourceImage;
+        if (typeof src !== "string") continue;
+        const at = images.indexOf(src);
+        if (at > 0) repoint.run(siblingIds[at], child.id);
+      }
+      for (const s of setsOf.all(r.id)) {
+        for (let i = 1; i < siblingIds.length; i++) addMember.run(s.set_id, siblingIds[i]);
+      }
+    }
+  })();
+}
+var SCHEMA_VERSION = 2;
 var SchemaTooNewError = class extends Error {
-  constructor(found, supported) {
+  constructor(found, supported, backupsDir) {
     super(
-      `This library was written by a newer Scenri (schema ${found}; this build understands ${supported}). Update and retry: npx scenri@latest`
+      `This library was written by a newer Scenri (schema ${found}; this build understands ${supported}). Update and retry: npx scenri@latest` + (backupsDir ? ` (a pre-migration snapshot of the library is kept in ${backupsDir})` : "")
     );
     this.name = "SchemaTooNewError";
   }
@@ -329,7 +424,7 @@ function openDb(homeDir) {
   const found = db.pragma("user_version", { simple: true });
   if (found > SCHEMA_VERSION) {
     db.close();
-    throw new SchemaTooNewError(found, SCHEMA_VERSION);
+    throw new SchemaTooNewError(found, SCHEMA_VERSION, join(homeDir, "backups"));
   }
   if (preExisting && found < SCHEMA_VERSION) backupBeforeMigration(db, homeDir, found);
   db.exec(MIGRATIONS);
@@ -346,6 +441,12 @@ function openDb(homeDir) {
   if (!nodeCols.includes("duration_ms")) {
     db.exec("ALTER TABLE nodes ADD COLUMN duration_ms INTEGER");
   }
+  if (!nodeCols.includes("batch_id")) {
+    db.exec("ALTER TABLE nodes ADD COLUMN batch_id TEXT");
+  }
+  if (!nodeCols.includes("batch_index")) {
+    db.exec("ALTER TABLE nodes ADD COLUMN batch_index INTEGER NOT NULL DEFAULT 0");
+  }
   const projectCols = db.pragma("table_info(projects)").map((c) => c.name);
   if (!projectCols.includes("slug")) {
     db.exec("ALTER TABLE projects ADD COLUMN slug TEXT");
@@ -362,6 +463,7 @@ function openDb(homeDir) {
   widenNodeStatusCheck(db);
   backfillSlugs(db);
   collapseProjects(db);
+  splitMultiImageNodes(db);
   db.prepare(
     "UPDATE nodes SET status='error', error='interrupted: server restarted mid-generation' WHERE status='running'"
   ).run();
@@ -482,9 +584,21 @@ function rowToNode(r) {
     createdAt: r.created_at,
     overlays: JSON.parse(r.overlays ?? "{}"),
     brief: r.brief ? JSON.parse(r.brief) : null,
-    archived: !!r.archived
+    archived: !!r.archived,
+    batchId: r.batch_id ?? null,
+    batchIndex: r.batch_index ?? 0
   };
 }
+var lastBatchStamp = 0;
+function batchStamps(count) {
+  const base = Math.max(Date.now(), lastBatchStamp + count);
+  lastBatchStamp = base;
+  const p = (n, w = 2) => String(n).padStart(w, "0");
+  return Array.from({ length: count }, (_, i) => {
+    const d = new Date(base - i);
+    return `${d.getUTCFullYear()}-${p(d.getUTCMonth() + 1)}-${p(d.getUTCDate())} ${p(d.getUTCHours())}:${p(d.getUTCMinutes())}:${p(d.getUTCSeconds())}.${p(d.getUTCMilliseconds(), 3)}`;
+  });
+}
 function createStore(db) {
   return {
     // brands
@@ -648,6 +762,42 @@ function createStore(db) {
       ).run(id, input.projectId, input.parentId, input.kind, input.prompt, input.engineId);
       return this.getNode(id);
     },
+    /**
+     * One multi-shot request, N first-class sibling nodes, one transaction.
+     * Slot 0 gets the newest stamp (see batchStamps) so the newest-first feed
+     * reads the batch in request order; batch_id is the first node's id, held
+     * by every sibling including the first, and stays null for a single send
+     * — one shot is not a batch.
+     */
+    addNodes(input) {
+      if (input.parentId) {
+        const parent = this.getNode(input.parentId);
+        if (!parent || parent.projectId !== input.projectId) throw new Error("parent node not found in project");
+      }
+      const count = Math.max(1, Math.floor(input.count));
+      const ids = Array.from({ length: count }, () => randomUUID());
+      const stamps = batchStamps(count);
+      const batchId = count > 1 ? ids[0] : null;
+      const insert = db.prepare(
+        "INSERT INTO nodes (id, project_id, parent_id, kind, prompt, engine_id, created_at, batch_id, batch_index) VALUES (?,?,?,?,?,?,?,?,?)"
+      );
+      db.transaction(() => {
+        for (let i = 0; i < count; i++) {
+          insert.run(
+            ids[i],
+            input.projectId,
+            input.parentId,
+            input.kind,
+            input.prompt,
+            input.engineId,
+            stamps[i],
+            batchId,
+            i
+          );
+        }
+      })();
+      return ids.map((id) => this.getNode(id));
+    },
     completeNode(id, result) {
       db.prepare("UPDATE nodes SET status='done', images=?, cost_usd=?, duration_ms=? WHERE id=?").run(
         JSON.stringify(result.images),
@@ -1454,7 +1604,17 @@ function createOpenRouterEngine(opts) {
         localOnly: false,
         supportsEdit: true,
         supportsMask: false,
+        // Four is OUR conservative constant, not a provider fact: OpenRouter
+        // multiplexes many image models and their input limits differ, so
+        // there is no single upstream number to cite the way codex's five is
+        // cited. Four keeps a full identity payload (product essential +
+        // angle, presenter, mark) inside every model we have routed to.
         maxReferenceImages: 4,
+        // Same uplink argument as codex: the provider reads references at
+        // reduced resolution anyway, and these ride base64-inlined inside a
+        // JSON body — a full-resolution phone photo is tens of megabytes of
+        // request for nothing.
+        maxReferenceEdge: 2048,
         // 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,
@@ -3242,9 +3402,9 @@ var ROLE_PRIORITY = {
   product: 0,
   character: 1,
   brand: 2,
-  scene: 3,
-  composition: 4,
-  reference: 5,
+  reference: 3,
+  scene: 4,
+  composition: 5,
   style: 6
 };
 function allocateAttachments(attachments, cap2) {
@@ -3594,6 +3754,7 @@ function validateBrief(brief) {
 function compileBrief(brief, ctx) {
   const warnings = [];
   const attachments = [];
+  const unattachable = [];
   const rawSceneFallback = [];
   const productDirectives = [];
   const personDirectives = [];
@@ -3645,7 +3806,7 @@ function compileBrief(brief, ctx) {
               ...angle ? { angle } : {}
             });
           });
-          productDirectives.push(productFidelityDirective(pshots.length));
+          productDirectives.push({ need: "fidelity", id: p.id });
           productDirectives.push(...productFactDirectives(p));
           if (p.description && !p.dimensions)
             productDirectives.push(
@@ -3653,6 +3814,7 @@ function compileBrief(brief, ctx) {
             );
         } else {
           warnings.push(`${p.name} has no usable photo, so it is named but not attached.`);
+          unattachable.push({ role: "product", id: p.id, label: p.name, hash: "", essential: true, reason: "missing" });
         }
         break;
       }
@@ -3694,6 +3856,14 @@ function compileBrief(brief, ctx) {
           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.`);
+          unattachable.push({
+            role: "character",
+            id: c.id,
+            label: c.name,
+            hash: "",
+            essential: true,
+            reason: "missing"
+          });
         }
         break;
       }
@@ -3713,7 +3883,12 @@ function compileBrief(brief, ctx) {
           break;
         }
         attachments.push({ role: "reference", label: "Reference shot", hash: tok.imageHash });
-        otherDirectives.push("Match the composition, lighting and treatment of the attached reference.");
+        otherDirectives.push({
+          need: "attachment",
+          role: "reference",
+          hash: tok.imageHash,
+          text: "Match the composition, lighting and treatment of the attached reference."
+        });
         break;
       }
       case "mark": {
@@ -3733,9 +3908,12 @@ function compileBrief(brief, ctx) {
             );
         } catch {
         }
-        otherDirectives.push(
-          "The attached brand mark is this brand's own mark. If the direction asks for the logo to appear, reproduce it exactly as drawn \u2014 same colours, letterforms and proportions, never redrawn or re-lettered. Every character it carries appears intact, including the smallest secondary lettering, in its original script and reading direction \u2014 never translated, transliterated or re-spelled. Otherwise take only its colour and treatment from it."
-        );
+        otherDirectives.push({
+          need: "attachment",
+          role: "brand",
+          hash: tok.imageHash,
+          text: "The attached brand mark is this brand's own mark. If the direction asks for the logo to appear, reproduce it exactly as drawn \u2014 same colours, letterforms and proportions, never redrawn or re-lettered. Every character it carries appears intact, including the smallest secondary lettering, in its original script and reading direction \u2014 never translated, transliterated or re-spelled. Otherwise take only its colour and treatment from it."
+        });
         break;
       }
       case "template": {
@@ -3815,8 +3993,32 @@ function compileBrief(brief, ctx) {
       if (i !== -1) attachments.splice(i, 1);
     }
   }
+  const identityHashes = /* @__PURE__ */ new Map();
+  for (const a of attachments)
+    if ((a.role === "product" || a.role === "character") && !identityHashes.has(a.hash))
+      identityHashes.set(a.hash, a.label);
+  for (let i = attachments.length - 1; i >= 0; i--) {
+    const a = attachments[i];
+    if (a.role === "reference" && identityHashes.has(a.hash)) {
+      attachments.splice(i, 1);
+      warnings.push(
+        `That reference is the same image as ${identityHashes.get(a.hash)}'s own photo, so it rides once, as the identity.`
+      );
+    }
+  }
   const max = ctx.engineCaps.maxReferenceImages;
-  const { kept, dropped } = allocateAttachments(attachments, max);
+  const { kept, dropped: budgetDropped } = allocateAttachments(attachments, max);
+  const presentKeys = new Set((ctx.presentAttachments ?? kept).map((a) => `${a.role}:${a.hash}`));
+  const resolveDirective = (d) => {
+    if (typeof d === "string") return d;
+    if (d.need === "fidelity") {
+      const n = attachments.filter(
+        (a) => a.role === "product" && a.id === d.id && presentKeys.has(`product:${a.hash}`)
+      ).length;
+      return n > 0 ? productFidelityDirective(n) : null;
+    }
+    return presentKeys.has(`${d.role}:${d.hash}`) ? d.text : null;
+  };
   const guard = scene ? sceneGuardDirectives({
     hasProduct: !!productId,
     hasPerson,
@@ -3838,8 +4040,9 @@ function compileBrief(brief, ctx) {
     treatment: scene.figureTreatment,
     hasPerson,
     // The treatment's fictional-brands rule needs to know a real mark is
-    // deliberately in play; attachments are fully collected by this point.
-    hasMark: attachments.some((a) => a.role === "brand")
+    // deliberately in play - and only one that actually rides counts,
+    // same honesty rule as the photo guard above.
+    hasMark: [...presentKeys].some((k) => k.startsWith("brand:"))
   }) : [];
   if (hasPerson) personDirectives.push(personSkinDirective());
   const closeUpDirectives = hasPerson && /\bclose[- ]?up\b|\bmacro\b|\bzoom(?:ed)?\b|\bDOF\b|\bdepth of field\b/i.test(sentence) ? [
@@ -3877,23 +4080,26 @@ function compileBrief(brief, ctx) {
     ...refGuard,
     ...preservation
   ];
-  if (allDirectives.length) prompt = `${prompt}${prompt.endsWith(".") ? "" : "."} ${dedupe(allDirectives).join(" ")}`;
-  if (dropped.some((d) => d.role !== "scene")) {
+  const spoken = dedupe(allDirectives.map(resolveDirective).filter((s) => s !== null));
+  if (spoken.length) prompt = `${prompt}${prompt.endsWith(".") ? "" : "."} ${spoken.join(" ")}`;
+  if (budgetDropped.some((d) => d.role !== "scene")) {
     const keptLabels = new Set(kept.map((a) => a.label));
-    const names = [...new Set(dropped.filter((d) => d.role !== "scene").map((d) => d.label))].filter(
+    const names = [...new Set(budgetDropped.filter((d) => d.role !== "scene").map((d) => d.label))].filter(
       (l) => !keptLabels.has(l)
     );
     if (names.length) {
       const reads = max === 0 ? "reads no reference images" : `reads ${max} reference image${max === 1 ? "" : "s"}`;
       warnings.push(
-        `${ctx.engineCaps.displayName} ${reads}, so ${names.join(" and ")} ${names.length === 1 ? "was" : "were"} left out.`
+        `${names.join(" and ")} ${names.length === 1 ? "was" : "were"} left out \u2014 ${ctx.engineCaps.displayName} ${reads}.`
       );
     }
   }
   return {
     prompt: prompt.trim(),
     referenceImages: kept.map((a) => ctx.images.pathFor(a.hash)),
-    dropped,
+    // The missing-photo identities lead: they are essential, and the refusal
+    // path reads this list. Budget losses carry their reason for the chips.
+    dropped: [...unattachable, ...budgetDropped.map((d) => ({ ...d, reason: "budget" }))],
     width,
     height,
     attachments: kept,
@@ -8760,6 +8966,25 @@ function registerImageRoutes(app, deps) {
 
 // src/release/notes.data.ts
 var RELEASES = [
+  {
+    version: "0.7.5",
+    date: "2026-09-01",
+    title: "Every shot is one card.",
+    sections: [
+      {
+        heading: "Create",
+        body: "Every shot is now its own card with its own image. Asking for several shots gives you that many cards, made together and standing on their own, and older multi-image shots split into separate cards the first time this version opens. The shot panel is rebuilt around the brief itself, with inline ingredient chips and versions in a single strip under the picture."
+      },
+      {
+        heading: "Refining",
+        body: "The shot being refined appears as a regular chip in the composer, and the card it points at is marked in the feed. Scenes sit out of the attach panel while a refine is armed, with a note saying why, instead of quietly trading the refine for a new shot."
+      },
+      {
+        heading: "Fixes",
+        body: "Generation requests carry exactly the reference images they claim to carry, and a product or presenter whose photo is missing stops the shot with a clear message instead of running without it. Cards that are still rendering show a simple counter and a cancel button."
+      }
+    ]
+  },
   {
     version: "0.7.4",
     date: "2026-08-31",
@@ -9900,7 +10125,7 @@ function buildServer(opts) {
       }
     }
     if (inheritedPerson) inheritedDirectives.push(personSkinDirective());
-    const compiled2 = compileBrief(brief, {
+    const compileCtx = {
       brand: brandJson,
       images: core.images,
       engineCaps: uncapped,
@@ -9918,7 +10143,8 @@ function buildServer(opts) {
       // Only the explicit op drops the dimension promise: an implicit legacy
       // expansion keeps its historical prompt byte for byte.
       ...opts2?.reshape === "extend" ? { editReshape: "extend" } : {}
-    });
+    };
+    const compiled2 = compileBrief(brief, compileCtx);
     let inheritedAttachments = [];
     let identityWarnings = [];
     if (inheritedTokens.length) {
@@ -9939,27 +10165,22 @@ function buildServer(opts) {
     }
     const cap2 = Math.max(0, engineCaps.maxReferenceImages - 1);
     const merged = mergeEditAttachments(compiled2.attachments, inheritedAttachments, cap2);
+    const prompt = compileBrief(brief, { ...compileCtx, presentAttachments: merged.kept }).prompt;
     const warnings = [...compiled2.warnings, ...identityWarnings.filter((w) => !compiled2.warnings.includes(w))];
     if (inherited.truncated)
       warnings.push("This thread is deeper than 64 steps, so identity attached before that could not be carried.");
     if (merged.dropped.length) {
       if (engineCaps.maxReferenceImages <= 1) {
-        warnings.push(
-          `${engineCaps.displayName} cannot carry reference images, so the identity rides on the source frame alone.`
-        );
+        warnings.push(`The identity rides on the shot itself \u2014 ${engineCaps.displayName} reads no other images.`);
       } else {
         const keptLabels = new Set(merged.kept.map((a) => a.label));
         const names = [...new Set(merged.dropped.map((d) => d.label))].filter((l) => !keptLabels.has(l));
         if (names.length)
-          warnings.push(
-            `${engineCaps.displayName} reads ${engineCaps.maxReferenceImages} reference images and the frame being refined keeps one, so ${names.join(
-              " and "
-            )} ${names.length === 1 ? "was" : "were"} left out.`
-          );
+          warnings.push(`${names.join(" and ")} ${names.length === 1 ? "was" : "were"} left out of this refinement.`);
       }
     }
     return {
-      compiled: compiled2,
+      compiled: { ...compiled2, prompt },
       inheritedTokens,
       merged,
       warnings,
@@ -9986,7 +10207,9 @@ function buildServer(opts) {
       return {
         ...rest2,
         attachments: edit.merged.kept,
-        dropped: edit.merged.dropped,
+        // The own compile runs uncapped, so its dropped list holds exactly the
+        // missing-photo identities; the budget losses live on the merge.
+        dropped: [...edit.compiled.dropped, ...edit.merged.dropped],
         warnings: edit.warnings,
         referenceCount: edit.merged.kept.length
       };
@@ -10141,11 +10364,11 @@ function buildServer(opts) {
     }
   }
   const NODE_TIMEOUT_MS = 6e5;
-  async function runNode(nodeId, engine, estimate, work, expect, post, timeoutMs) {
+  async function runNode(nodeIds, engine, estimate, work, expect, postFor, timeoutMs) {
     const engineId = engine?.capabilities().id ?? "local";
     reserved.set(engineId, (reserved.get(engineId) ?? 0) + estimate);
     const ctrl = new AbortController();
-    runningGenerations.set(nodeId, ctrl);
+    for (const id of nodeIds) runningGenerations.set(id, ctrl);
     const bound = opts.nodeTimeoutMs ?? timeoutMs ?? NODE_TIMEOUT_MS;
     let watchdogFired = false;
     const watchdog = setTimeout(() => {
@@ -10153,43 +10376,68 @@ function buildServer(opts) {
       ctrl.abort(BUDGET_EXHAUSTED);
     }, bound);
     const startedAt = Date.now();
+    const settled = /* @__PURE__ */ new Set();
     try {
       const result = await work(ctrl.signal);
       clearTimeout(watchdog);
-      result.images = await normalizePngs(result.images);
-      if (post) result.images = await post(result.images);
-      if (expect) await assertAspect(result.images, expect);
-      try {
-        const sizes = [];
-        for (const h of result.images) {
-          const meta2 = await sharp20(core.images.read(h)).metadata();
-          if (meta2.width && meta2.height) sizes.push([meta2.width, meta2.height]);
+      const images = await normalizePngs(result.images);
+      const raw = result.raw;
+      const bySlot = new Array(nodeIds.length);
+      images.forEach((h, k) => {
+        const slot = raw?.variantIndexes?.[k] ?? k;
+        if (slot < nodeIds.length && bySlot[slot] === void 0) bySlot[slot] = h;
+      });
+      const wall = Date.now() - startedAt;
+      const failures = [...raw?.partialFailures ?? []];
+      for (let slot = 0; slot < nodeIds.length; slot++) {
+        const id = nodeIds[slot];
+        const hash = bySlot[slot];
+        if (hash === void 0) {
+          core.store.failNode(id, failures.shift() ?? "the engine returned no image for this shot");
+          settled.add(id);
+          continue;
         }
-        const node = core.store.getNode(nodeId);
-        if (node && sizes.length) {
-          const brief = node.brief ?? {};
-          const raw = result.raw;
-          const survivors = typeof raw?.requested === "number" && Array.isArray(raw.variantIndexes) ? { requested: raw.requested, variantIndexes: raw.variantIndexes } : {};
-          const asked = expect ? { requestedSize: [expect.width, expect.height] } : {};
-          core.store.setBrief(nodeId, { ...brief, rendered: { sizes, ...survivors, ...asked } });
-          if (node.kind === "generation" && engineId === "codex-cli" && expect && expect.width !== expect.height && sizes.some(([w, h]) => w === expect.width && h === expect.height))
-            app.log.warn(
-              { nodeId },
-              "codex delivered exactly the requested pixels; its image tool cannot pin size - suggests a forbidden shell resize"
-            );
+        try {
+          let own = [hash];
+          const post = postFor?.(id);
+          if (post) own = await post(own);
+          if (expect) await assertAspect(own, expect);
+          try {
+            const meta2 = await sharp20(core.images.read(own[0])).metadata();
+            const node = core.store.getNode(id);
+            if (node && meta2.width && meta2.height) {
+              const brief = node.brief ?? {};
+              const asked = expect ? { requestedSize: [expect.width, expect.height] } : {};
+              core.store.setBrief(id, { ...brief, rendered: { sizes: [[meta2.width, meta2.height]], ...asked } });
+              if (node.kind === "generation" && engineId === "codex-cli" && expect && expect.width !== expect.height && meta2.width === expect.width && meta2.height === expect.height)
+                app.log.warn(
+                  { nodeId: id },
+                  "codex delivered exactly the requested pixels; its image tool cannot pin size - suggests a forbidden shell resize"
+                );
+            }
+          } catch {
+          }
+          core.store.completeNode(id, {
+            images: own,
+            costUsd: slot === 0 ? result.costUsd : 0,
+            durationMs: wall
+          });
+        } catch (err) {
+          core.store.failNode(id, String(err?.message ?? err));
         }
-      } catch {
+        settled.add(id);
       }
-      core.store.completeNode(nodeId, { ...result, durationMs: Date.now() - startedAt });
-      core.ledger.recordCost(engineId, nodeId, result.costUsd);
+      core.ledger.recordCost(engineId, nodeIds[0], result.costUsd);
     } catch (err) {
-      if (watchdogFired)
-        core.store.failNode(nodeId, `generation timed out after ${Math.round(bound / 6e4)} minutes`);
-      else if (ctrl.signal.aborted) core.store.cancelNode(nodeId);
-      else core.store.failNode(nodeId, String(err?.message ?? err));
+      for (const id of nodeIds) {
+        if (settled.has(id)) continue;
+        if (watchdogFired) core.store.failNode(id, `generation timed out after ${Math.round(bound / 6e4)} minutes`);
+        else if (ctrl.signal.aborted) core.store.cancelNode(id);
+        else core.store.failNode(id, String(err?.message ?? err));
+      }
     } finally {
       clearTimeout(watchdog);
-      runningGenerations.delete(nodeId);
+      for (const id of nodeIds) runningGenerations.delete(id);
       const left = (reserved.get(engineId) ?? 0) - estimate;
       if (left > 1e-9) reserved.set(engineId, left);
       else reserved.delete(engineId);
@@ -10238,7 +10486,7 @@ function buildServer(opts) {
         images: [core.images.save(await sharp20(args.srcBuf).extract(window).png().toBuffer())],
         costUsd: 0
       });
-      void runNode(node2.id, null, 0, work2, { width: plan2.width, height: plan2.height }).catch(
+      void runNode([node2.id], null, 0, work2, { width: plan2.width, height: plan2.height }).catch(
         (err) => app.log.error({ err }, "crop run failed")
       );
       return reply.status(202).send(args.note ? { ...node2, warnings: [args.note] } : node2);
@@ -10395,6 +10643,14 @@ function buildServer(opts) {
       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 missing = lostIdentity.filter((d) => d.reason === "missing");
+        if (missing.length) {
+          const names2 = joinNames(missing.map((d) => d.label));
+          const kindWord2 = missing[0].role === "product" ? "product" : "presenter";
+          return reply.code(400).send({
+            error: `${names2} ${missing.length === 1 ? "has" : "have"} no usable photo, so the result would not be your ${kindWord2}. Re-add ${missing.length === 1 ? "its" : "their"} photo, or remove ${names2} from the brief.`
+          });
+        }
         const names = joinNames(lostIdentity.map((d) => d.label));
         const kindWord = lostIdentity[0].role === "product" ? "product" : "presenter";
         return reply.code(400).send({
@@ -10405,6 +10661,19 @@ function buildServer(opts) {
       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 ?? [];
+      if (process.env.SCENRI_DEBUG) {
+        const sent = {};
+        for (const r of sentRoles) sent[r] = (sent[r] ?? 0) + 1;
+        app.log.info(
+          {
+            engine: engine.capabilities().id,
+            cap: cap2,
+            sent,
+            dropped: (compiled2?.dropped ?? []).map((d) => `${d.role}:${d.label} (${d.reason ?? "budget"})`)
+          },
+          "reference transport"
+        );
+      }
       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"),
@@ -10436,6 +10705,20 @@ function buildServer(opts) {
       const editRefs = mergedEdit ? mergedEdit.kept.map((a) => ({ path: core.images.pathFor(a.hash), role: a.role })) : (referenceImages ?? []).map((path, i) => ({ path, role: referenceRoles?.[i] })).slice(0, Math.max(0, engine.capabilities().maxReferenceImages - 1));
       const editEdge = engine.capabilities().maxReferenceEdge;
       if (editEdge) for (const r of editRefs) r.path = await capReferenceEdge(core, r.path, editEdge);
+      if (process.env.SCENRI_DEBUG) {
+        const sent = {};
+        for (const r of editRefs) sent[String(r.role ?? "reference")] = (sent[String(r.role ?? "reference")] ?? 0) + 1;
+        app.log.info(
+          {
+            engine: engine.capabilities().id,
+            cap: Math.max(0, engine.capabilities().maxReferenceImages - 1),
+            sourceFrame: true,
+            sent,
+            dropped: (mergedEdit?.dropped ?? []).map((d) => `${d.role}:${d.label} (${d.reason ?? "budget"})`)
+          },
+          "reference transport"
+        );
+      }
       const srcBuf = core.images.read(String(srcHash));
       const srcMeta = await sharp20(srcBuf).metadata();
       if (srcMeta.width && srcMeta.height) expectShape = { width: srcMeta.width, height: srcMeta.height };
@@ -10603,15 +10886,26 @@ function buildServer(opts) {
     }
     const billedId = runEngine.capabilities().id;
     core.ledger.assertUnderCap(billedId, estimate + (reserved.get(billedId) ?? 0));
-    const node = core.store.addNode({
+    const nodes = kind === "generation" ? core.store.addNodes({
       projectId: project.id,
       parentId: resolvedParentId,
       kind,
       prompt: finalPrompt,
-      engineId: billedId
-    });
-    if (brief)
-      core.store.setBrief(node.id, {
+      engineId: billedId,
+      // the same clamp the engine request and the watchdog use
+      count: Math.min(Math.max(1, Number(count)), 8)
+    }) : [
+      core.store.addNode({
+        projectId: project.id,
+        parentId: resolvedParentId,
+        kind,
+        prompt: finalPrompt,
+        engineId: billedId
+      })
+    ];
+    const node = nodes[0];
+    for (const sibling of brief ? nodes : [])
+      core.store.setBrief(sibling.id, {
         ...briefInputsOnly(brief),
         ...editedFrom ? { sourceImage: editedFrom } : {},
         ...kind === "edit" && reshape ? { reshape } : {},
@@ -10758,14 +11052,23 @@ function buildServer(opts) {
         staged = await conformToCanvas(node.id, expectShape)(staged);
       }
       return enforceEditCanvas(staged);
-    } : kind === "generation" && compiled2?.width && compiled2?.height ? conformToCanvas(node.id, { width: compiled2.width, height: compiled2.height }) : void 0;
+    } : void 0;
+    const genW = compiled2?.width;
+    const genH = compiled2?.height;
+    const postFor = post !== void 0 ? () => post : kind === "generation" && genW && genH ? (id) => conformToCanvas(id, { width: genW, height: genH }) : 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")
-    );
+    void runNode(
+      nodes.map((n) => n.id),
+      runEngine,
+      estimate,
+      work,
+      expectShape,
+      postFor,
+      nodeBudgetMs
+    ).catch((err) => app.log.error({ err }, "node run failed"));
     const allWarnings = [...compiled2?.warnings ?? [], ...extraWarnings];
-    return reply.status(202).send(allWarnings.length ? { ...node, warnings: allWarnings } : node);
+    return reply.status(202).send({ ...node, siblings: nodes, ...allWarnings.length ? { warnings: allWarnings } : {} });
   });
   app.post("/api/nodes/:id/cancel", async (req, reply) => {
     const id = req.params.id;
@@ -10838,7 +11141,10 @@ function buildServer(opts) {
     runtime,
     stageImpl: opts.stageImpl,
     exitImpl: opts.exitImpl,
-    busyCount: () => runningGenerations.size + runningImportCount() + runningAssetBuildCount()
+    // one physical run counts once, however many sibling nodes share its
+    // controller — an update gate held open by a 4-shot batch is still held
+    // open by exactly one piece of work
+    busyCount: () => new Set(runningGenerations.values()).size + runningImportCount() + runningAssetBuildCount()
   });
   let drained = null;
   app.decorate("drain", () => {