fix(ui): make multi-GPU viewer previews survive owner termination and queue lifecycle events

[lstein]

Summary

Follow-up to #9263, addressing the two ImageViewer preview issues deferred in @JPPhoto's 2026-07-25 review. They share the same store and handler, so they are fixed together:

1. Terminal-owner fallback (context.tsx): when the session owning the shared $progressEvent/$progressImage globals reached a terminal state, its tile was removed but the globals were cleared — or, for successful completion with auto-switch, parked on the finished session's stale frame via the resolve illusion. Since the tiled view only renders with more than one active session, the remaining session's still-running preview disappeared until its next image event. The globals are now handed to the most recently updated remaining session immediately, for every terminal status and auto-switch mode.

2. Stale progress lifecycle: $progressData was cleaned only by per-item terminal events. It is now also cleared on:

• queue_cleared — scoped exactly like workflowExecutionCoordinator.onQueueCleared (unscoped and own-user clears apply; foreign scoped clears and the sanitized user_id="redacted" broadcast do not), and the cleared items are marked finished so a trailing invocation_progress event from a worker stopped only by the clear cannot repopulate the preview;
• socket disconnect (mirroring the app-wide progress stores in setEventListeners);
• $socket replacement after an auth-token/user change.

Implementation

The store logic is extracted into viewerProgressLifecycle.ts so it can be unit tested without rendering (per the web CLAUDE.md convention of no UI tests); the provider keeps the socket subscriptions and ownership/scope checks. Sessions gain a seq counter so "most recently updated" promotion is exact rather than timestamp-granular.

Tests

16 vitest cases: preview promotion for completed/canceled/failed and both auto-switch modes, multi-survivor promotion order, non-owner termination leaving the preview alone, last-session clear/resolve behavior, repeat-event idempotence, clear scoping (own/unscoped/foreign/sanitized), trailing-progress suppression after a clear, and disconnect reset.

Merge order

Stacked on #9263 — this branch contains the multi-GPU branch's commits. Draft until #9263 merges; will then rebase onto main and mark ready for review.

Checklist

• The PR has a short but descriptive title, suitable for a changelog
• Tests added / updated (if applicable)
• Documentation added / updated (if applicable)
• Updated What's New copy (if doing a release after this PR)

🤖 Generated with Claude Code

[lstein]

Rebased cleanly onto the current #9263 head (272a2ef2ea); 1691 frontend tests green, tsc + prettier clean.

[JPPhoto]

Merge blockers:

• invokeai/frontend/web/src/features/gallery/components/ImageViewer/viewerProgressLifecycle.ts:77: Queue clear marks only image-tracked items plus current global event. A no-image session can later emit an image and resurrect deleted preview. Test: record item 1 without image, item 2 with image, clear queue, then record item 1 with image; expect rejection.

Other findings/issues to fix:

• invokeai/frontend/web/src/features/gallery/components/ImageViewer/viewerProgressLifecycle.ts:144: A final-image callback has no session identity. If A promotes B, then B completes before A's image loads, A's callback clears B's retained preview. Test: complete A, complete B, invoke A's delayed load; expect B preview retained.

Suggestions:

• Consider tracking every session on progress, including image: null, before queue-clear suppression.

• Consider passing completed item identity through onLoadImage; ignore stale loads from previous sessions.

[lstein]

Thanks @JPPhoto — both findings confirmed against the code and fixed, plus a few things that fell out of adversarially reviewing the fixes themselves. Head is now 80bb03edc0.

1. Queue clear only marked image-tracked items (merge blocker)

Confirmed. $progressData holds only sessions that have produced a preview image, and the shared globals name one item, so a session that had reported progress without an image yet was invisible to both — its first image event after the clear sailed through the finishedQueueItemIds gate.

The lifecycle now tracks unfinishedItemIds: every item seen on progress, image or not, removed on its terminal event and dropped on any reset. The clear marks that set finished. It's a strict superset of the two old sources, so the old loops are gone rather than kept alongside.

Your test is in as written (blocks trailing progress from a session that had not produced a preview image yet).

While tracing this I checked the ordering that makes the hole reachable, and it's narrower than the fix's first framing suggested. clear() runs _cancel_in_progress_matching before deleting rows and emitting queue_cleared (session_queue_sqlite.py:666-706), so anything already running gets its own canceled event first and is finished by the time the clear arrives. The item that genuinely escapes is one a worker claims between the cancel pass and the DELETE: its row is gone, so no terminal event is ever emitted for it, and its first progress event lands seconds later — a preview for a deleted queue item with nothing left to take it down.

Its claim is the only event that names it, so the viewer now also tracks in_progress status changes (dequeue → _set_queue_item_status(status="in_progress") emits one). This narrows that race, it does not close it: the claim event is emitted from the worker thread two DB round-trips after the status UPDATE commits (session_queue_sqlite.py:530-546), while queue_cleared comes from the clearing thread, so the claim can still arrive after the clear and re-register the item. Nothing client-side can tell that item apart from a legitimately new one enqueued right after the clear. Closing it properly means the backend emitting a terminal event for an item deleted while claimed — happy to file that as a follow-up if you agree it's worth one.

2. Final-image callback has no session identity

Confirmed, with the sequence you described: A completes and hands the preview to B, B completes and starts its own resolve illusion, then A's image finally loads and clears B's retained frame.

clearProgressOnFinalImageLoad: boolean is now pendingResolveItemId: number | null, and onLoadImage takes the loaded DTO's session_id. Attribution comes from a session→item map fed by progress events (QueueItemStatusChangedEvent has no session_id; InvocationProgressEvent does). A load is ignored only when it positively resolves to a different tracked item.

Both call sites wrap the callback rather than passing it through — <DndImage onLoad={onLoadImage}> would have handed React's event object in as the session id.

One thing worth your attention here. Ignoring loads by identity removes the only thing that ever took a retained preview down, and the retained session's own image is not guaranteed to load at all:

• DndImage passes fallbackSrc, so Chakra's <Image> routes load failures through onError, never onLoad;
• auto-switch selection is async per completion (onInvocationComplete awaits the DTO fetch), so with concurrent completions the other session's image can end up selected and the retained session's image is never rendered;
• and the plainest one: the user clicks any other image during the illusion.

In all three the preview is an opaque bg="base.900" overlay, and the 2-second reveal path is explicitly disabled while isProgressImageResolving is true — so the guard traded a ~200 ms flicker for an overlay stuck until the next generation. The illusion now carries a RESOLVE_TIMEOUT_MS (3 s) safety timeout armed with it; every write to pendingResolveItemId goes through one helper that keeps the timer in sync, so whoever ends the illusion also disarms it. An ignored load can now only end the illusion early, never keep it up.

3 s is a judgment call — long enough that a normal DTO-fetch-plus-full-res-load wins the race, short enough that a stale frame over a deliberately clicked image is brief. Easy to retune if you'd rather bias one way.

Two smaller things from the same pass: the session→item attributions are now dropped in clearAll (they outlived the state they described, so post-reset images read as "another session's" and refused to end a later illusion), and a completed item that never reported progress no longer arms an illusion over nothing, which used to leave $isProgressImageResolving stuck on.

Known residuals (pre-existing, untouched)

A progress event carrying no image replaces $progressEvent but not $progressImage, so the previous session's frame stays up while the next queue item spins up — that's how the overlay persists across a batch today, and the timeout deliberately doesn't cover it, since bounding it would make the overlay flicker mid-batch. The non-owner early-return in onTerminal can strand a frame the same way. Both are main's behavior; I left them and noted the boundary in the code.

Tests

27 lifecycle cases (1816 frontend tests total), tsc/eslint/prettier clean. Each new test was checked by reverting its fix in place and confirming it fails — including two timeout cases that initially passed against a leaked timer because the stores were already null at that point; they now assert the timer count instead.

[JPPhoto]

No merge blockers!

I did find a few corner cases - your call as to whether they get addressed:

• invokeai/frontend/web/src/features/gallery/components/ImageViewer/viewerProgressLifecycle.ts:150-160: an in_progress event arriving after queue_cleared re-registers a deleted item; later progress resurrects its preview. Test: deliver clear, then claim, then progress; expect progress rejected.

• invokeai/frontend/web/src/features/gallery/components/ImageViewer/context.tsx:127: sessions with no progress never enter itemIdBySessionId; their final-image load is treated as unknown and clears another session's retained preview. Test: A retains preview, B completes without progress, B image loads; expect A preview retained.

Suggestions:

• Consider backend clear-generation/tombstone data to reject post-clear claims.
• Consider recording session_id from claim/terminal events.