Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS
JavaScript ai-agentsdashboarddeveloper-toolsdigital-twinquantified-selfsecond-brainself-hostedtailscale
[issue-11669] Complete character sheets after restart or listener timeout (#11717)
[._.]/cfcc10d00681
diff --git a/server/lib/schemaVersions.js b/server/lib/schemaVersions.jsindex 8b0d18c9ce..2737b0fa4c 100644--- a/server/lib/schemaVersions.js+++ b/server/lib/schemaVersions.js@@ -80,7 +80,9 @@ export const PORTOS_SCHEMA_VERSIONS = Object.freeze({// <=v11 peer would strip it in its `factual`-unaware `sanitizeTemplate`// and last-writer-wins the loss back, silently reclassifying the user's// Reality universe as fiction.- universes: 12,+ // v13 = durable character sheet request identities (#11669). Older peers+ // must not strip supersession state during an unrelated canon edit.+ universes: 13,// v1 = post-split. Migrations 035/036 introduced the pipeline collection// layout for issues and series.// v2 = `stages.audio.audioMode` + `stages.audio.cues[]` added (whole-episodediff --git a/server/lib/schemaVersions.test.js b/server/lib/schemaVersions.test.jsindex 00a973a186..71b70b1a71 100644--- a/server/lib/schemaVersions.test.js+++ b/server/lib/schemaVersions.test.js@@ -25,7 +25,7 @@ describe('PORTOS_SCHEMA_VERSIONS', () => {// v12 adds the universe factual flag (#7616).// These are additive + version-gated so an older peer// cannot strip-then-LWW them.- expect(PORTOS_SCHEMA_VERSIONS.universes).toBe(12);+ expect(PORTOS_SCHEMA_VERSIONS.universes).toBe(13);});it('declares pipeline collection layout versions', () => {@@ -91,14 +91,14 @@ describe('buildPortosMeta', () => {it('returns { portosVersion, schemaVersions } with the live registry', async () => {const meta = await buildPortosMeta();expect(meta.portosVersion).toMatch(/^\d+\.\d+\.\d+/);- expect(meta.schemaVersions.universes).toBe(12);+ expect(meta.schemaVersions.universes).toBe(13);expect(meta.schemaVersions.pipelineIssues).toBe(4);expect(meta.schemaVersions.pipelineSeries).toBe(14);});it('overrides merge into schemaVersions', async () => {const meta = await buildPortosMeta({ schemaVersions: { future: 1 } });- expect(meta.schemaVersions.universes).toBe(12);+ expect(meta.schemaVersions.universes).toBe(13);expect(meta.schemaVersions.future).toBe(1);});});diff --git a/server/lib/storyBible.js b/server/lib/storyBible.jsindex 8418d7364c..b75137bfab 100644--- a/server/lib/storyBible.js+++ b/server/lib/storyBible.js@@ -252,8 +252,8 @@ export function findBibleEntryByName(list, name) {// render-completion mutator is the sole writer. Distinct from the// `imageRefs[]` gallery — lives in `data/image-refs/`.//-// `SERVER_OWNED_CHARACTER_FIELDS` is a strict subset: ONLY the pointers-// that the *server* writes via render-completion mutators (never the+// `SERVER_OWNED_CHARACTER_FIELDS` is a strict subset: pointers and request+// identities that the *server* writes via render mutators (never the// client, never the LLM). `updateUniverse` preserves these across// literal-object PATCHes so a stale client body can't clobber a newer// server stamp (multi-tab / parallel render race). Mutator-form callers@@ -265,11 +265,11 @@ export const CANON_CONTROL_FIELDS = Object.freeze([// Sheet pointers — see SHEET_VARIANTS in universeCharacterSheet.js for the// catalog of styles; legacy 'standard' stays in `referenceSheetImageRef`,// every other variant lives in `referenceSheets[<id>]`.- 'referenceSheetImageRef', 'referenceSheets',+ 'referenceSheetImageRef', 'referenceSheets', 'referenceSheetRequests',]);export const SERVER_OWNED_CHARACTER_FIELDS = Object.freeze([- 'referenceSheetImageRef', 'referenceSheets',+ 'referenceSheetImageRef', 'referenceSheets', 'referenceSheetRequests',]);export function stripCanonControlFields(entry) {@@ -452,6 +452,8 @@ const ADDITIVE_CHARACTER_FIELD_VERSIONS = Object.freeze({identityPack: 10,// v11 — optional structured psychology profile (#6414).psychology: 11,+ // v13 — durable per-variant render intent (#11669).+ referenceSheetRequests: 13,});const ADDITIVE_OBJECT_FIELD_VERSIONS = Object.freeze({// v7 — structured object↔character attachments (#1288).@@ -463,7 +465,8 @@ const ADDITIVE_OBJECT_FIELD_VERSIONS = Object.freeze({// sanitizer defaults to `[]` (relationshipLinks, attachments).export function isLegacyAbsentValue(value) {return value === undefined || value === null || value === false || value === ''- || (Array.isArray(value) && value.length === 0);+ || (Array.isArray(value) && value.length === 0)+ || (isPlainObject(value) && Object.keys(value).length === 0);}/**@@ -534,7 +537,8 @@ function isValidVariantId(id) {* immutable-by-convention. */export function mergePreservedSheetPointers(prev, patchChar, resolveExists) {if (!prev || !patchChar) return patchChar;- const out = { ...patchChar };+ // Intent has no file yet and must survive even if a prior sheet was deleted.+ const out = { ...patchChar, referenceSheetRequests: prev.referenceSheetRequests ?? {} };if (prev.referenceSheetImageRef && resolveExists(prev.referenceSheetImageRef)) {out.referenceSheetImageRef = prev.referenceSheetImageRef;@@ -1021,6 +1025,9 @@ export function sanitizeCharacter(raw, { idPrefix = DEFAULT_ID_PREFIX.character,// migration. Sanitizer drops invalid keys and basename-validates every// value with the same rules as the legacy field.referenceSheets: deriveReferenceSheets(raw.referenceSheets),+ referenceSheetRequests: Object.fromEntries(Object.entries(isPlainObject(raw.referenceSheetRequests) ? raw.referenceSheetRequests : {})+ .filter(([variant, token]) => (variant === LEGACY_SHEET_VARIANT_ID || isValidVariantId(variant))+ && typeof token === 'string' && /^[0-9a-f-]{36}$/.test(token))),// Wardrobes (A2): outfit/styling variants applied on top of// physicalDescription. Empty array stays the legacy shape — every// existing character keeps rendering through physicalDescription alone.diff --git a/server/lib/storyBible.test.js b/server/lib/storyBible.test.jsindex 8b803c4f98..258b6f382d 100644--- a/server/lib/storyBible.test.js+++ b/server/lib/storyBible.test.js@@ -976,7 +976,7 @@ describe('storyBible — canon control + server-owned field invariants', () => {// Pin the current set so a new server-owned addition is a deliberate// change (update both this test AND the corresponding render flow).expect([...SERVER_OWNED_CHARACTER_FIELDS]).toEqual([- 'referenceSheetImageRef', 'referenceSheets',+ 'referenceSheetImageRef', 'referenceSheets', 'referenceSheetRequests',]);});});@@ -1781,3 +1781,22 @@ describe('storyBible — reveal-gated canon (#2178)', () => {});});});++// The durable render identity must survive canonical storage and stale client+// edits, while model-generated content cannot create or replace it.+it('round-trips server-owned sheet request identity and preserves it across stale edits', () => {+ const requestId = '11111111-1111-4111-8111-111111111111';+ const current = sanitizeCharacter({ id: 'character-1', name: 'Example', referenceSheetRequests: { standard: requestId, blueprint: requestId } });+ expect(current.referenceSheetRequests).toEqual({ standard: requestId, blueprint: requestId });+ const patched = mergePreservedSheetPointers(current, { ...current, name: 'Edited', referenceSheetRequests: {} }, () => false);+ expect(sanitizeCharacter(patched).referenceSheetRequests).toEqual(current.referenceSheetRequests);+ expect(stripCanonControlFields(current)).not.toHaveProperty('referenceSheetRequests');+});++it('preserves sheet request identity from pre-v13 peers but honors current peer supersession', () => {+ const local = [{ id: 'character-1', referenceSheetRequests: { standard: '11111111-1111-4111-8111-111111111111' } }];+ const legacy = [{ id: 'character-1', name: 'Peer edit', referenceSheetRequests: {} }];+ expect(preserveLegacyCharacterFields(legacy, local, 12)[0].referenceSheetRequests).toEqual(local[0].referenceSheetRequests);+ const newer = [{ id: 'character-1', referenceSheetRequests: { standard: '22222222-2222-4222-8222-222222222222' } }];+ expect(preserveLegacyCharacterFields(newer, local, 13)).toEqual(newer);+});diff --git a/server/services/dataSync.pipelineUniverse.test.js b/server/services/dataSync.pipelineUniverse.test.jsindex 1fe1b4c369..f49c373e70 100644--- a/server/services/dataSync.pipelineUniverse.test.js+++ b/server/services/dataSync.pipelineUniverse.test.js@@ -163,19 +163,19 @@ describe('dataSync — universe category', () => {const snap = await dataSync.getSnapshot('universe');expect(snap.portosMeta).toBeDefined();expect(typeof snap.portosMeta.portosVersion).toBe('string');- expect(snap.portosMeta.schemaVersions.universes).toBe(12);+ expect(snap.portosMeta.schemaVersions.universes).toBe(13);});it('applyRemote rejects when sender schemaVersions are AHEAD of local code', async () => {writeUniverseState({ universes: [], runs: [] });const result = await dataSync.applyRemote('universe', {universes: [{ id: 'u-new', name: 'Foundry', updatedAt: '2026-05-17T10:00:00Z' }],- }, { portosMeta: { portosVersion: '99.0.0', schemaVersions: { universes: 13 } } });+ }, { portosMeta: { portosVersion: '99.0.0', schemaVersions: { universes: 14 } } });expect(result.applied).toBe(false);expect(result.count).toBe(0);expect(result.blockedBySchema).toBeDefined();expect(result.blockedBySchema.ahead).toEqual([- { category: 'universes', senderV: 13, receiverV: 12 },+ { category: 'universes', senderV: 14, receiverV: 13 },]);expect(result.blockedBySchema.senderPortosVersion).toBe('99.0.0');// Nothing was written.@@ -213,6 +213,25 @@ describe('dataSync — universe category', () => {expect('moodBoardId' in persisted.universes[0]).toBe(false);});+ it('preserves durable sheet intent through old-peer sync and accepts current-peer supersession', async () => {+ const first = '11111111-1111-4111-8111-111111111111';+ const next = '22222222-2222-4222-8222-222222222222';+ const base = { id: 'u-sheet', name: 'Example', createdAt: '2026-05-17T09:00:00Z' };+ writeUniverseState({ universes: [{ ...base, updatedAt: '2026-05-17T10:00:00Z',+ characters: [{ id: 'character-1', name: 'Example', referenceSheetRequests: { standard: first } }],+ }], runs: [] });+ const behind = await dataSync.applyRemote('universe', { universes: [{ ...base,+ updatedAt: '2026-05-17T11:00:00Z', characters: [{ id: 'character-1', name: 'Peer edit' }],+ }] }, { portosMeta: { schemaVersions: { universes: 12 } } });+ expect(behind.applied).toBe(true);+ expect(readUniverseState().universes[0].characters[0].referenceSheetRequests).toEqual({ standard: first });+ const current = await dataSync.applyRemote('universe', { universes: [{ ...base,+ updatedAt: '2026-05-17T12:00:00Z', characters: [{ id: 'character-1', name: 'Peer edit', referenceSheetRequests: { standard: next } }],+ }] }, { portosMeta: { schemaVersions: { universes: 13 } } });+ expect(current.applied).toBe(true);+ expect(readUniverseState().universes[0].characters[0].referenceSheetRequests).toEqual({ standard: next });+ });+it('applyRemote falls through for legacy senders that send NO portosMeta at all', async () => {writeUniverseState({ universes: [], runs: [] });const result = await dataSync.applyRemote('universe', {diff --git a/server/services/sharing/integration.test.js b/server/services/sharing/integration.test.jsindex 018300db21..535f2c2942 100644--- a/server/services/sharing/integration.test.js+++ b/server/services/sharing/integration.test.js@@ -2373,7 +2373,7 @@ describe('sharing round-trip', () => {const exp = await exporter.exportSeries(s.id, bucket.id);const manifest = JSON.parse(readFileSync(join(tempBucket, 'manifests', exp.filename), 'utf-8'));expect(manifest.portosSchemaVersions).toBeDefined();- expect(manifest.portosSchemaVersions.universes).toBe(12);+ expect(manifest.portosSchemaVersions.universes).toBe(13);});it('preserves character production packages when an older peer wins universe LWW', async () => {diff --git a/server/services/sharing/peerSync.test.js b/server/services/sharing/peerSync.test.jsindex 5529f7660e..a91992d2d5 100644--- a/server/services/sharing/peerSync.test.js+++ b/server/services/sharing/peerSync.test.js@@ -4059,17 +4059,17 @@ describe('peerSync', () => {describe('receiver — applyIncomingPush', () => {it('rejects when sender schemaVersions.universes is AHEAD of local code', async () => {- // Local code is at universes:12 (see server/lib/schemaVersions.js).- // A push from a sender on universes:13 must NOT touch local state.+ // Local code is at universes:13 (see server/lib/schemaVersions.js).+ // A push from a sender on universes:14 must NOT touch local state.const rejection = await applyIncomingPush({kind: 'universe',record: { id: 'u1', name: 'Foo' },assetManifest: [],sourceInstanceId: 'peer-a',- portosMeta: { portosVersion: '99.0.0', schemaVersions: { universes: 13 } },+ portosMeta: { portosVersion: '99.0.0', schemaVersions: { universes: 14 } },}).catch((err) => err);expect(rejection.code).toBe('PEER_SYNC_SCHEMA_VERSION_AHEAD');- expect(rejection.details.ahead).toEqual([{ category: 'universes', senderV: 13, receiverV: 12 }]);+ expect(rejection.details.ahead).toEqual([{ category: 'universes', senderV: 14, receiverV: 13 }]);expect(rejection.details.senderPortosVersion).toBe('99.0.0');// Receiver MUST stamp its OWN PortOS version so the sender can show// the user "peer X is on PortOS vY" — without this, the sender would@@ -4362,7 +4362,7 @@ describe('peerSync', () => {expect(call).toBeDefined();const body = JSON.parse(call[1].body);expect(body.portosMeta).toBeDefined();- expect(body.portosMeta.schemaVersions.universes).toBe(12);+ expect(body.portosMeta.schemaVersions.universes).toBe(13);expect(typeof body.portosMeta.portosVersion).toBe('string');});diff --git a/server/services/universeAssetBackupAdmission.test.js b/server/services/universeAssetBackupAdmission.test.jsindex 0032c7bbd7..ba2ad225c9 100644--- a/server/services/universeAssetBackupAdmission.test.js+++ b/server/services/universeAssetBackupAdmission.test.js@@ -40,11 +40,21 @@ vi.mock('./universeBuilder.js', () => ({},}));+// Retain the same job identity and params from admission through terminal+// publication, as the persisted queue does across process lifetimes.+const queuedJobs = new Map();vi.mock('./mediaJobQueue/index.js', () => ({mediaJobEvents: new EventEmitter(),- enqueueJob: async () => ({ jobId: 'sheet-job', position: 1 }),+ enqueueJob: async ({ kind, params }) => {+ const job = { id: 'sheet-job', kind, params: structuredClone(params), status: 'queued' };+ queuedJobs.set(job.id, job);+ return { jobId: job.id, position: 1, status: job.status };+ },+ getJob: id => queuedJobs.get(id),}));vi.mock('./mediaCollections.js', () => ({ addItem: vi.fn(), ERR_DUPLICATE: 'DUPLICATE' }));+// This suite owns universe references; music-video pool cleanup has its own contracts.+vi.mock('./musicVideo/mediaPool.js', () => ({ forgetDeletedMusicVideoAssets: async () => {} }));vi.mock('./mediaAssetIndex/index.js', () => ({ indexImage: async () => {}, unindexImage: async () => {} }));vi.mock('./settings.js', () => ({ getSettings: async () => ({ imageGen: { mode: 'local', local: { modelId: 'dev' } } }) }));vi.mock('./universeRunTag.js', () => ({ buildUniverseRunTag: async () => null }));@@ -88,6 +98,7 @@ initUniverseBuilderCollectionHook();afterAll(cleanupTempDataRoots);beforeEach(async () => {beforeRowWrite = async () => {};+ queuedJobs.clear();await rm(PATHS.data, { recursive: true, force: true });await Promise.all([PATHS.images, PATHS.imageRefs].map(directory => mkdir(directory, { recursive: true })));await writeFile(renderPath(), 'synthetic render');@@ -115,7 +126,9 @@ describe('render completion listeners', () => {job: async () => {const { jobId, destFilename } = await renderCharacterReferenceSheet('universe-1', 'character-1');sheet = destFilename;- return { id: jobId, kind: 'image', result: { filename: RENDER } };+ const completed = { ...queuedJobs.get(jobId), status: 'completed', result: { filename: RENDER } };+ queuedJobs.set(jobId, completed);+ return structuredClone(completed);},changedFiles: async () => {expect(await readFile(join(PATHS.imageRefs, sheet), 'utf8')).toBe('synthetic render');diff --git a/server/services/universeBuilder.test.js b/server/services/universeBuilder.test.jsindex 050000d69f..bb408a808d 100644--- a/server/services/universeBuilder.test.js+++ b/server/services/universeBuilder.test.js@@ -774,6 +774,7 @@ describe("universeBuilder service", () => {await svc.updateUniverse(w.id, (latest) => {const next = [...(latest.characters || []), {id: "c-1", name: "Vale", referenceSheetImageRef: "sheet-B.png",+ referenceSheetRequests: { standard: "11111111-1111-4111-8111-111111111111" },}];return { characters: next };});@@ -791,6 +792,7 @@ describe("universeBuilder service", () => {});const charOmit = afterOmitPatch.characters.find((c) => c.id === "c-1");expect(charOmit?.referenceSheetImageRef).toBe("sheet-B.png");+ expect(charOmit?.referenceSheetRequests).toEqual({ standard: "11111111-1111-4111-8111-111111111111" });// Mutator path (the render-completion handler) IS trusted to update// referenceSheetImageRef — it constructs the patch from the latestdiff --git a/server/services/universeCharacterSheet.js b/server/services/universeCharacterSheet.jsindex a35ee7d102..af1b7f6c8e 100644--- a/server/services/universeCharacterSheet.js+++ b/server/services/universeCharacterSheet.js@@ -14,6 +14,7 @@*/import { join, basename } from 'path';+import { randomUUID } from 'node:crypto';import { PATHS, ensureDir, shortId, assertSafeFilename, copyFileGuarded, unlinkGuarded } from '../lib/fileUtils.js';import { ServerError } from '../lib/errorHandler.js';import { withBackupAssetPublication } from '../lib/backupSnapshotBoundary.js';@@ -22,7 +23,7 @@ import { getUniverse, updateUniverse } from './universeBuilder.js';import { purgeReferenceSheetFromAllUniverses } from './universeCanon.js';import { universeAestheticLine } from '../lib/universeVisualStyle.js';import { promptAddition } from '../lib/modelInput.js';-import { enqueueJob, mediaJobEvents } from './mediaJobQueue/index.js';+import { enqueueJob, getJob, mediaJobEvents } from './mediaJobQueue/index.js';import { buildUniverseRunTag } from './universeRunTag.js';import { IMAGE_GEN_MODE } from './imageGen/modes.js';import { resolveRenderTargetConfig } from './imageGen/cloudProviderConfig.js';@@ -328,14 +329,6 @@ export function listSheetVariants() {}));}-// `(universeId, characterId) → latest generationId requested` is owned by-// `./universeCharacterSheetSlot.js` (extracted so universeBuilder.js can-// clear slots on delete without an import cycle). The supersede-aware-// contract is unchanged: a render claims the slot at enqueue, the-// completion handler only stamps `referenceSheetImageRef` when the slot-// still holds its jobId, and a newer render overwrites the slot so the-// older one sees itself as superseded.-// Single-dispatcher subscription so N pending sheets don't attach 4*N// listeners on the global `mediaJobEvents` emitter (Node defaults to a// 10-listener soft cap before warning). Each render claims an entry by@@ -347,11 +340,34 @@ function ensureSheetDispatchListeners() {if (_sheetListenersAttached) return;_sheetListenersAttached = true;mediaJobEvents.on('started', (job) => sheetSubscribers.get(job?.id)?.onStarted?.(job));- mediaJobEvents.on('completed', (job) => sheetSubscribers.get(job?.id)?.onCompleted?.(job));- const onTerminal = (job) => sheetSubscribers.get(job?.id)?.onFailed?.(job);+ mediaJobEvents.on('completed', (job) => {+ sheetSubscribers.get(job?.id)?.onCompleted?.(job);+ const tag = job?.params?.characterSheet;+ if (!tag) return;+ // The persisted job owns completion, even after restart or listener expiry.+ void onSheetComplete({ ...tag, jobId: job.id, sourceFilename: job.result?.filename })+ .catch((err) => {+ console.error(`❌ Character sheet post-completion failed [${shortId(job.id)}]: ${err?.message}`);+ return null;+ }).then((result) => {+ releasePendingSheetSlot(tag.universeId, tag.entryId, job.id, tag.variant);+ mediaJobEvents.emit('reference-sheet:changed', {+ universeId: tag.universeId, entryId: tag.entryId, jobId: job.id, variant: tag.variant,+ status: result?.superseded ? 'superseded' : result ? 'ready' : 'failed',+ });+ });+ });+ const onTerminal = (job) => {+ sheetSubscribers.get(job?.id)?.onFailed?.(job);+ const tag = job?.params?.characterSheet;+ if (tag) releasePendingSheetSlot(tag.universeId, tag.entryId, job.id, tag.variant);+ };mediaJobEvents.on('failed', onTerminal);mediaJobEvents.on('canceled', onTerminal);}+// Routes import this module before queue recovery starts at boot.+ensureSheetDispatchListeners();+function subscribeToSheetJob(jobId, handlers) {ensureSheetDispatchListeners();sheetSubscribers.set(jobId, handlers);@@ -484,33 +500,29 @@ export async function renderCharacterReferenceSheet(universeId, entryId, optionsparams.universeRun = universeRun;}- // Enqueue through mediaJobQueue so the render serializes through the right- // backend lane alongside Image Gen / Universe Builder renders. The queue- // dispatches by `params.mode` (codex → codex lane, local → GPU lane).+ // Persist intent BEFORE enqueue can dispatch. The serialized universe write+ // establishes ordering without timestamps or a process-local pending slot.+ // Retain the token after completion/failure: an older job must stay superseded.+ const requestId = randomUUID();+ await updateUniverse(universeId, (latest) => {+ const current = latest.characters?.find((entry) => entry.id === entryId);+ if (!current) throw new ServerError('Character not found in universe', { status: 404, code: 'UNIVERSE_CANON_NOT_FOUND' });+ return { characters: latest.characters.map((entry) => entry.id === entryId ? {+ ...entry,+ referenceSheetRequests: { ...entry.referenceSheetRequests, [variant]: requestId },+ } : entry) };+ });+ params.characterSheet = { universeId, entryId, variant, requestId };const queued = await enqueueJob({ kind: 'image', params });const jobId = queued.jobId;- // Claim the latest-pending slot for this character + variant. onSheetComplete- // checks it before stamping — guards against an older-but-slower render- // finishing after a newer one and overwriting the newer pointer. The variant- // key keeps standard and blueprint slots independent so a blueprint render- // can't be superseded by an illustrated one or vice versa.- claimPendingSheetSlot(universeId, entryId, jobId, variant);-- // Subscribe to the queue's completion bus via the shared sheet- // dispatcher (NOT imageGenEvents directly — the queue mediates the- // imageGen lifecycle and re-emits on mediaJobEvents with the full job- // record). The shared dispatcher caps listeners at 4 regardless of how- // many sheets are pending (see `subscribeToSheetJob` above), so a user- // running 10+ parallel character renders won't trip- // MaxListenersExceededWarning on the global emitter.- //- // Two-stage timeout: a generous queue-wait window covers the pre-start- // gap (so a sheet queued behind a long video / first-run-download- // doesn't detach mid-queue), then the `started` event resets the timer- // to the tighter run window. Without the reset, a sheet waiting 30+- // minutes behind a video job would lose its bookkeeping listener- // before onSheetComplete had a chance to run — file copy + character- // pointer stamp lost.+ const latest = await getUniverse(universeId);+ if (latest.characters?.find((entry) => entry.id === entryId)?.referenceSheetRequests?.[variant] === requestId) {+ claimPendingSheetSlot(universeId, entryId, jobId, variant);+ }++ // Per-request listeners only track pending UI state. Expiry releases that+ // state, while the permanent hook still owns publication from the job tag.+ // Queue wait gets a longer window than active rendering.const QUEUE_WAIT_MS = 4 * 60 * 60 * 1000; // 4h — generous; survives chained video jobs.// 30min sits comfortably above the codex backend's 20min CODEX_TIMEOUT_MS// watchdog and the typical local FLUX.2 ceiling, so a legitimate slow@@ -528,32 +540,25 @@ export async function renderCharacterReferenceSheet(universeId, entryId, options}, ms);timeoutHandle.unref?.();};- const detach = () => {+ const detach = (release = true) => {if (timeoutHandle) { clearTimeout(timeoutHandle); timeoutHandle = null; }if (unsubscribe) { unsubscribe(); unsubscribe = null; }+ if (release) releasePendingSheetSlot(universeId, entryId, jobId, variant);};unsubscribe = subscribeToSheetJob(jobId, {onStarted: () => armTimeout(RUN_TIMEOUT_MS, 'exceeded run window'),- onCompleted: async (job) => {- detach();- const sourceFilename = job.result?.filename;- const result = await onSheetComplete({ universeId, entryId, jobId, sourceFilename, variant }).catch((err) => {- console.error(`❌ ${variantConfig.label} post-completion failed [${shortId(jobId)}]: ${err?.message}`);- });- releasePendingSheetSlot(universeId, entryId, jobId, variant);- mediaJobEvents.emit('reference-sheet:changed', {- universeId, entryId, jobId, variant,- status: result?.superseded ? 'superseded' : result ? 'ready' : 'failed',- });- },+ onCompleted: () => detach(false),onFailed: (job) => {detach();- // Release the slot so a retry render doesn't get superseded by this dead one.- releasePendingSheetSlot(universeId, entryId, jobId, variant);console.log(`⚠️ ${variantConfig.label} render ${job.status} [${shortId(jobId)}]: ${job.error || 'unknown'}`);},});armTimeout(QUEUE_WAIT_MS, 'queue-wait timeout');+ // Queue admission starts its worker before resolving. A fast completion or+ // cancellation can precede this subscriber; never leave its terminal job pending.+ const admittedJob = getJob(jobId);+ if (['completed', 'failed', 'canceled'].includes(admittedJob?.status ?? queued.status)) detach();+ else if (admittedJob?.status === 'running') armTimeout(RUN_TIMEOUT_MS, 'exceeded run window');// Deterministic destination filename — uses the queue's jobId so the client// can correlate the persisted pointer with this particular render.@@ -584,7 +589,7 @@ export function onSheetComplete(completion) {return withBackupAssetPublication(() => publishCompletedSheet(completion));}-async function publishCompletedSheet({ universeId, entryId, jobId, sourceFilename, variant = LEGACY_SHEET_VARIANT_ID }) {+async function publishCompletedSheet({ universeId, entryId, jobId, sourceFilename, requestId, variant = LEGACY_SHEET_VARIANT_ID }) {if (!sourceFilename) return null;const variantConfig = getVariantConfig(variant);await ensureDir(PATHS.imageRefs);@@ -597,49 +602,21 @@ async function publishCompletedSheet({ universeId, entryId, jobId, sourceFilenamawait copyFileGuarded(srcPath, destPath);console.log(`📸 ${variantConfig.label} copied to image-refs: ${destFilename}`);- // If a newer render has been started for this character+variant while ours- // was in flight (OR the character was deleted, which clears all variants'- // slots), the slot no longer holds our jobId. Skip the stamp — the newer- // render will stamp its own filename when it finishes, and a deleted- // character would re-introduce an orphaned pointer. Without this, an- // older-but-slower render could overwrite a newer-but-finished pointer.- if (getPendingSheetSlot(universeId, entryId, variant) !== jobId) {- console.log(`⏭️ ${variantConfig.label} [${shortId(jobId)}] superseded by newer render — file saved, pointer not stamped`);- return { filename: destFilename, path: destPath, superseded: true };- }- // Stamp ONLY the variant's pointer (legacy field OR `referenceSheets` map- // slot) inside the write queue against the freshest persisted universe so- // a concurrent user edit (or sibling render landing close in time) can't- // clobber unrelated character fields. The sheet file lives in- // data/image-refs/, distinct from `imageRefs[]` (gallery, /data/images/) —- // polluting imageRefs would 404 the CanonCard thumbnail.+ // Compare the durable request identity inside the serialized write. An+ // absent character/token is superseded too; deletion must not revive a sheet.let stamped = false;await updateUniverse(universeId, (latest) => {- // Recheck inside the serialized write: a newer render can claim the slot- // while this completion waits for an earlier universe update.- if (getPendingSheetSlot(universeId, entryId, variant) !== jobId) return null;const latestList = Array.isArray(latest.characters) ? latest.characters : [];const latestIdx = latestList.findIndex((c) => c.id === entryId);- if (latestIdx < 0) return null;+ if (latestIdx < 0 || !requestId || latestList[latestIdx].referenceSheetRequests?.[variant] !== requestId) return null;const nextList = latestList.map((e, i) => (i === latestIdx ? applySheetPointerToCharacter(e, variant, destFilename) : e));stamped = true;return { characters: nextList };});- // Release the slot only after a successful stamp AND only if it still- // belongs to us — between the supersede check and this delete, a newer- // render could have started, claimed the slot, and arrived here in- // parallel. An unconditional delete would wipe the newer render's slot- // and cause its onSheetComplete to see "superseded" (slot empty ≠ jobId)- // and skip its own stamp — leaving the older filename persisted. A- // failed stamp leaves the slot owned by us so the next render-start- // cleanly overwrites it.releasePendingSheetSlot(universeId, entryId, jobId, variant);- if (!stamped) {- console.log(`⚠️ Character ${entryId} not found post-render — ${variantConfig.label.toLowerCase()} saved but not linked`);- return null;- }+ if (!stamped) return { filename: destFilename, path: destPath, superseded: true };console.log(`📌 Character ${shortId(entryId)} [${variant}] = ${destFilename}`);return { filename: destFilename, path: destPath, variant };}diff --git a/server/services/universeCharacterSheet.modelResolution.test.js b/server/services/universeCharacterSheet.modelResolution.test.jsindex 53e6c914dc..a870ffa875 100644--- a/server/services/universeCharacterSheet.modelResolution.test.js+++ b/server/services/universeCharacterSheet.modelResolution.test.js@@ -13,10 +13,11 @@ const mocks = vi.hoisted(() => ({claimPendingSheetSlot: vi.fn(),}));-vi.mock('./universeBuilder.js', () => ({ getUniverse: (...args) => mocks.getUniverse(...args) }));+vi.mock('./universeBuilder.js', () => ({ getUniverse: (...args) => mocks.getUniverse(...args), updateUniverse: vi.fn() }));vi.mock('./settings.js', () => ({ getSettings: (...args) => mocks.getSettings(...args) }));vi.mock('./mediaJobQueue/index.js', () => ({enqueueJob: (...args) => mocks.enqueueJob(...args),+ getJob: vi.fn(),mediaJobEvents: { on: vi.fn(), off: vi.fn() },}));vi.mock('./universeRunTag.js', () => ({ buildUniverseRunTag: (...args) => mocks.buildUniverseRunTag(...args) }));diff --git a/server/services/universeCharacterSheet.publication.test.js b/server/services/universeCharacterSheet.publication.test.jsindex 0e6fe905f4..0b5ddd0159 100644--- a/server/services/universeCharacterSheet.publication.test.js+++ b/server/services/universeCharacterSheet.publication.test.js@@ -1,4 +1,4 @@-import { describe, it, expect, vi, beforeEach } from 'vitest';+import { it, expect, vi, beforeEach, afterEach } from 'vitest';vi.mock('../lib/imageCleanDefaults.js', () => ({resolveImageCleaners: vi.fn(() => ({ cleanC2PA: false, denoise: false })),@@ -7,7 +7,7 @@ vi.mock('../lib/imageCleanDefaults.js', () => ({const mocks = vi.hoisted(() => ({getUniverse: vi.fn(),getSettings: vi.fn(),- enqueueJob: vi.fn(),+ enqueueJob: vi.fn(), getJob: vi.fn(),getImageModels: vi.fn(),buildUniverseRunTag: vi.fn(),copy: vi.fn(), update: vi.fn(),@@ -17,7 +17,7 @@ vi.mock('./universeBuilder.js', () => ({ getUniverse: (...args) => mocks.getUnivvi.mock('./settings.js', () => ({ getSettings: (...args) => mocks.getSettings(...args) }));vi.mock('./mediaJobQueue/index.js', async () => {const { EventEmitter } = await import('node:events');- return { enqueueJob: (...args) => mocks.enqueueJob(...args), mediaJobEvents: new EventEmitter() };+ return { enqueueJob: (...args) => mocks.enqueueJob(...args), getJob: (...args) => mocks.getJob(...args), mediaJobEvents: new EventEmitter() };});vi.mock('../lib/fileUtils.js', async importOriginal => ({...(await importOriginal()), ensureDir: vi.fn(), copyFileGuarded: (...args) => mocks.copy(...args),@@ -32,31 +32,35 @@ import { renderCharacterReferenceSheet, getCharacterReferenceSheet } from './uniimport { mediaJobEvents } from './mediaJobQueue/index.js';-import { claimPendingSheetSlot } from './universeCharacterSheetSlot.js';+import { __testing as slots } from './universeCharacterSheetSlot.js';let universe;beforeEach(() => {vi.clearAllMocks();+ slots.reset();universe = { id: 'universe-1', name: 'Example Universe', characters: [{ id: 'character-1', name: 'Example Character' }] };mocks.getUniverse.mockImplementation(async () => universe);mocks.getSettings.mockResolvedValue({ imageGen: { mode: 'local', local: { modelId: 'dev' } } });mocks.getImageModels.mockReturnValue([{ id: 'dev', hardwareCompatibility: { state: 'available' } }]);mocks.buildUniverseRunTag.mockResolvedValue(null);+ mocks.getJob.mockReturnValue(null);mocks.enqueueJob.mockResolvedValue({ jobId: 'job-1', position: 1 });mocks.copy.mockResolvedValue();mocks.update.mockImplementation(async (_id, update) => { universe = { ...universe, ...update(universe) }; });});-const completed = () => mediaJobEvents.emit('completed', { id: 'job-1', result: { filename: 'render.png' } });+const queuedJob = (index = 0) => ({ id: `job-${index + 1}`, params: structuredClone(mocks.enqueueJob.mock.calls[index][0].params), result: { filename: 'render.png' } });+const completed = (job = queuedJob()) => mediaJobEvents.emit('completed', job);+afterEach(() => vi.useRealTimers());const publication = () => new Promise(resolve => mediaJobEvents.once('reference-sheet:changed', resolve));it('announces readiness only after the destination copy and pointer persistence, with correlated recovery state', async () => {let finishCopy;mocks.copy.mockImplementation(() => new Promise(resolve => { finishCopy = resolve; }));+ const queued = await renderCharacterReferenceSheet('universe-1', 'character-1');let finishWrite;mocks.update.mockImplementation((_id, update) => new Promise(resolve => {finishWrite = () => { universe = { ...universe, ...update(universe) }; resolve(); };}));- const queued = await renderCharacterReferenceSheet('universe-1', 'character-1');const listener = vi.fn();mediaJobEvents.on('reference-sheet:changed', listener);const result = publication();@@ -78,18 +82,102 @@ it('reports copy failure and releases pending state for reconnect recovery', asyconst result = publication();completed();expect(await result).toMatchObject({ jobId: 'job-1', status: 'failed' });- expect(mocks.update).not.toHaveBeenCalled();+ expect(mocks.update).toHaveBeenCalledTimes(1); // Only the durable request claim.expect(await getCharacterReferenceSheet('universe-1', 'character-1')).toMatchObject({ pendingJobId: null });});-it('does not stamp an older render when another job claims the slot during the queued write', async () => {- mocks.update.mockImplementation(async (_id, update) => {- claimPendingSheetSlot('universe-1', 'character-1', 'new-job');- expect(update(universe)).toBeNull();- });+it('publishes from persisted job metadata after restart without a subscriber or pending slot', async () => {+ const requestId = '11111111-1111-4111-8111-111111111111';+ universe.characters[0].referenceSheetRequests = { blueprint: requestId };+ const result = publication();+ completed({ id: 'recovered-job', params: { characterSheet: {+ universeId: 'universe-1', entryId: 'character-1', variant: 'blueprint', requestId,+ } }, result: { filename: 'recovered.png' } });+ expect(await result).toMatchObject({ jobId: 'recovered-job', variant: 'blueprint', status: 'ready' });+ expect(mocks.copy).toHaveBeenCalledOnce();+ expect(universe.characters[0].referenceSheets.blueprint).toContain('recovere');+});++it('releases an expired listener slot and still publishes its later completion', async () => {+ vi.useFakeTimers();await renderCharacterReferenceSheet('universe-1', 'character-1');+ await vi.advanceTimersByTimeAsync(4 * 60 * 60 * 1000);+ expect(await getCharacterReferenceSheet('universe-1', 'character-1')).toMatchObject({ pendingJobId: null });const result = publication();completed();- await result;- expect(await getCharacterReferenceSheet('universe-1', 'character-1')).toMatchObject({ pendingJobId: 'new-job' });+ expect(await result).toMatchObject({ status: 'ready' });+});++it('keeps newer intent after restart even when its render fails and an older job completes last', async () => {+ await renderCharacterReferenceSheet('universe-1', 'character-1');+ const older = queuedJob();+ mocks.enqueueJob.mockResolvedValue({ jobId: 'job-2', position: 2 });+ await renderCharacterReferenceSheet('universe-1', 'character-1');+ const newer = queuedJob(1);+ mediaJobEvents.emit('failed', newer);+ slots.reset();+ const result = publication();+ completed(older);+ expect(await result).toMatchObject({ status: 'superseded' });+ expect(universe.characters[0].referenceSheetImageRef).toBeUndefined();+});++it('preserves the newest completed pointer and independently rendered variants', async () => {+ await renderCharacterReferenceSheet('universe-1', 'character-1');+ const older = queuedJob();+ mocks.enqueueJob.mockResolvedValue({ jobId: 'job-2', position: 2 });+ await renderCharacterReferenceSheet('universe-1', 'character-1');+ const newer = queuedJob(1);+ const ready = publication();+ completed(newer);+ expect(await ready).toMatchObject({ status: 'ready' });+ const filename = universe.characters[0].referenceSheetImageRef;+ slots.reset();+ const stale = publication();+ completed(older);+ expect(await stale).toMatchObject({ status: 'superseded' });+ expect(universe.characters[0].referenceSheetImageRef).toBe(filename);++ mocks.enqueueJob.mockResolvedValue({ jobId: 'job-3', position: 3 });+ await renderCharacterReferenceSheet('universe-1', 'character-1', { variant: 'blueprint' });+ const blueprint = publication();+ completed(queuedJob(2));+ expect(await blueprint).toMatchObject({ status: 'ready' });+ expect(universe.characters[0].referenceSheetImageRef).toBe(filename);+ expect(universe.characters[0].referenceSheets.blueprint).toContain('job-3');+});++it('does not enqueue if the durable claim fails', async () => {+ mocks.update.mockRejectedValue(new Error('request write failed'));+ await expect(renderCharacterReferenceSheet('universe-1', 'character-1')).rejects.toThrow('request write failed');+ expect(mocks.enqueueJob).not.toHaveBeenCalled();+});++it('rechecks supersession when the pointer write waits behind a newer request', async () => {+ await renderCharacterReferenceSheet('universe-1', 'character-1');+ const job = queuedJob();+ let finishWrite;+ mocks.update.mockImplementation((_id, update) => new Promise(resolve => {+ finishWrite = () => { universe = { ...universe, ...update(universe) }; resolve(); };+ }));+ const result = publication();+ completed(job);+ await vi.waitFor(() => expect(finishWrite).toBeTypeOf('function'));+ universe.characters[0].referenceSheetRequests.standard = '22222222-2222-4222-8222-222222222222';+ finishWrite();+ expect(await result).toMatchObject({ status: 'superseded' });+ expect(universe.characters[0].referenceSheetImageRef).toBeUndefined();+});++it('does not reclaim pending state when a fast job publishes before enqueue returns', async () => {+ mocks.enqueueJob.mockImplementation(async ({ params }) => {+ const job = { id: 'fast-job', status: 'completed', params, result: { filename: 'fast.png' } };+ const result = publication();+ completed(job);+ expect(await result).toMatchObject({ status: 'ready' });+ mocks.getJob.mockReturnValue(job);+ return { jobId: job.id, position: 1, status: 'queued' };+ });+ const queued = await renderCharacterReferenceSheet('universe-1', 'character-1');+ expect(await getCharacterReferenceSheet('universe-1', 'character-1')).toEqual({ filename: queued.destFilename, pendingJobId: null });});