Hand a cued clip's warm decoder to Program (T1.11 / #449 step 2)

[iamfatness]

Closes #449 (step 2). docs/BACKLOG.md T1.11.

A clip taken from Preview to Program cold-started: a placeholder slab on air for the ticks before its first frame, and a take record reading rebuilt with missingSources=[media:<id>].

Why it cold-started

A clip changes identity twice on go-live:

	Preview cue	After the Take
sourceId	preview:media:<id>	media:<id>
mediaPlaybackKey	media:<id>:live:<n>	media:<id>:live:<n+1>

Both are deliberate — the preview: prefix keeps a paused poster from replacing Program's rolling copy, and the generation bump is what guarantees "roll from 0, audio on". But OwnedMediaFrameSource::requests() keys a decoder on sourceId|path|assetId|playbackKey|loop, so the arriving request matched nothing, a fresh decoder opened, and resolveLayers painted colorFromParticipantId over PROGRAM.

The fix

adoptCuedDecoders re-keys the cue's entry onto the live request instead of letting it retire. Entry is a shared_ptr whose worker holds its own reference, so the hand-over is a map re-key — the decoder and its held poster never notice.

This is not an exception to the go-live contract, it is the contract. The cue poster sits paused at frame 0 (MediaVideoPresentation::hold shows the first prepared frame and never advances), so resuming it is exactly "roll from 0, audio on".

The decision is pure (modules/MediaCueHandoff.h, the CaptureReaderStallPolicy / TakeRecordPolicy shape). Every condition is required: same asset id and same path, same loop flag, the retiring sourceId is exactly "preview:" + arriving.sourceId, the arriving generation is exactly +1, and — the load-bearing one — the cue never rolled. A decoder that has played is at an arbitrary position, and adopting it would put a clip on air mid-roll while the take record still read cut. Two candidates for one arrival is refused loudly and cold-starts: never guess which cue is the predecessor.

Three things the tests caught that reasoning had not

1. It must run on the REQUEST path (selectVideo / pollMediaAudioFrames), never in manage(). The request set changes on the take tick, but manage() is a separate thread on a 2 ms wait, so an adoption deferred to it lands a tick late — at 60 Hz, exactly one frame of the placeholder this exists to remove. Adoption starts no thread and does no I/O, which is what makes it safe on the caller's path where creating a worker would not be.
2. The queued frames must be dropped and current_ kept (MediaVideoPresentation::dropQueued). They were scheduled against the cue's paused epoch and can never come due on the go-live clock, so keeping them froze the clip on its poster forever. The held poster is what covers the refill.
3. The owner names the source, not the decoder. Every decoder stamps participantId from the layer it was handed, so selectVideo re-stamping it is normally a no-op — but an adopted poster was decoded under the preview: id, and the compositor looks a media layer up by the LIVE source id. Without the re-stamp the hand-off delivered a frame nothing could match and Program painted the placeholder anyway.

The take record now reads missingSources=[] for this case because the cold start stopped happening. CLAUDE.md says that record is honest and the judge must not be taught to excuse a cold start — the judge was not touched.

Verification

903 native tests pass, 0 fail (892 on main before this). The threaded tests were run three times each to check for flakiness; stable.

Red-green, verified by reverting the production wiring and rebuilding:

Test	Without the fix
OwnedMediaFrameSource.ACuedClipHandsItsWarmDecoderToProgram	FAILS — drove the adoption
ProgramPixelContinuity.ACuedClipTakenToProgramNeverShowsThePlaceholder	FAILS at tick 0 — the end-to-end pixel proof, over a REAL OwnedMediaFrameSource
AnAdoptedCueRollsInsteadOfFreezingOnItsPoster	passes; it was red against the intermediate build that adopted without dropQueued, which is where I watched it fail
ACueThatAlreadyRolledIsNeverHandedOver	passes either way — a refusal guard that catches the worker failing to set everPlayed, which the unit test cannot
AnAdoptedCueTurnsItsAudioOn	passes either way — a contract guard, not red-first
MediaCueHandoff.* (6)	new pure code; red as compile errors

A sensitivity check on the audio test found two dead lines in the adoption path (the creation loop re-arms wantsAudio unconditionally in the same manage() pass); they were removed rather than kept as decoration.

Not verified: no live run. The proof is the pixel test over the real owner plus the take record, not a real meeting.

What this does not fix

A clip cut to Program that was never cued in Preview has no warm decoder to adopt and still cold-starts. That is step 1 of #449 — hold the outgoing picture until the first real frame — and is next.

No shell code changed.

🤖 Generated with Claude Code

https://claude.ai/code/session_014yuH7EMvWCWdkhvevrtMyJ