docs/DEVLOG.md

Hand Tie Clips -- engineering log

The dated record behind CLAUDE.md, which is the architecture brief. Everything here is history: what was built on a given day, what it measured, and what it got wrong. Later sections correct earlier ones -- read to the end of a thread before trusting the top of it.

Numbering starts at 8 because sections 1-7 became the brief.

8. References are files, not wires (2026-08-28)

The node had 16 sockets and twelve of them were user media: ref_image_1..9, reference_video, voice, start_image. They occupied roughly 340px down the left of the node before the editor started, each needing its own Load Image. They are gone. The node now has five: model, clip, vae, audio_vae, continuity_state.

A reference names a file under <ComfyUI input>/h3_refs. media.py owns both halves of that:

• resolve(name) is the only thing that turns a name into a path, and it is used by the upload route and the loaders alike. Basename only, normpath, then a prefix check against the reference directory, then an extension whitelist. Verified against absolute paths, ../ traversal, and traversal carrying a legal extension — all refused.
• The loaders return exactly what the sockets delivered — float [N,H,W,3] in 0..1 — so _ref_frames' resize, _collect_ref_images' dense-pack and store.tensor_digest's cache keying are all unchanged. That is why this was a small diff rather than a rewrite.

Pixels never enter a widget. Only the basename is stored. PromptMasterLD measured 1.68 MB of widget value for nine base64 thumbnails and ComfyUI then failed to save the workflow at all; previews are /view?...&subfolder=h3_refs URLs, which cost nothing to rebuild and survive a reload. /view also brings Range support, which a <video> needs to seek — so no thumbnail route was needed.

IS_CHANGED is new and load-bearing. ComfyUI caches a node's output on its inputs, and a filename is a stable input even when the bytes behind it change: overwrite face.png and the previous render would be served. It hashes name:mtime for every referenced file. Deliberately not float("nan") — that is the blunt version PromptMasterLD's studio node uses, and it would force a full re-render of an expensive node on every queue.

Widget order is part of the saved-workflow format. widgets_values is a positional array -- ComfyUI restores value[i] into widget[i] and never looks at the name. The three *_file widgets were first added at the top of optional, which shifted hop_script..tone_compensate by +3; every workflow saved before that change then loaded audio_pin_frames' integer into ref_plan and the editor died with (text || "").trim is not a function on load. That throw was the lucky part -- hop_script, shot_plan and tone_compensate were being silently misassigned too, and only the type mismatch made any of it visible.

New widgets go at the bottom of optional, always. Old workflows are then short rather than misaligned, and the new widget takes its default. There is an append-only marker comment in INPUT_TYPES saying so. Note seed costs two array slots, not one: the frontend appends control_after_generate right after it.

Both plan parsers now coerce (String(text ?? "")) and reject non-object JSON instead of dereferencing it, so a future misalignment shows an empty JSON tab rather than aborting the whole workflow load.

The hop cache needed no change at all. chain_salt already digests the actual tensors, so different pixels behind the same filename still move the key.

Legacy plans cannot be migrated automatically. An old ref_image_N held a tensor from a Load Image; there is no filename to recover. refs.py keeps the authored slot as legacy_slot, parse_ref_plan does not raise on it, and both the rail row and check() say "was wired to ref_image_3 — pick its picture". Failing the parse would have stopped the editor opening the very plan the author needs to repair.

9. Presentation (2026-08-28)

The node collapsed on first click and stayed collapsed. Two causes, both in installHeightGuard (js/editor/widget_utils.js), both ported from PromptMasterLD/js/claude_prompt.js:6285-6370:

• computeLayoutSize().minWidth reported a constant. The layout pass re-reads it on every recompute — selecting the node is enough — and faithfully re-declares the node at its stated minimum. It now tracks node.size[0]. Safe against feedback: max() against a constant is a fixpoint, not an accumulator, and width never feeds height.
• A stale widget.width shadows node.width forever after load, because ComfyUI's DOM-widget position updater reads (widget.width ?? node.width). A live getter with a dropped setter makes the stale value unrepresentable.

Two more fixes alongside: node.computeSize()[0] is floored at the panel width (with no widget declaring one, LiteGraph falls back to NODE_WIDTH * 1.5 = 210 and every resize command is free to crush the panel), and domWidget.computeSize now answers a width-passing caller with the minimum height and a no-argument caller with the live height. Reporting the live height to both pins the resize-drag floor to the current height, so the node could only ever grow.

chrome()'s memo key was stale by construction. It keyed on inputs|outputs|widgets.length, none of which change when a widget is hidden — so every panel height computed after applyVisibility used a chrome measurement taken before it. The hidden count is now part of the key.

The reference rail was permanently crushed, and its rescue was dead code. The 7-track grid needs ~536px and the node offers ~510px at NODE_WIDTH 560. There was a @container (max-width: 460px) block written to relieve it — but nothing in the codebase declared container-type, so the query had no containment context and never matched. .h3e-section now declares container-type: inline-size, and there are two breakpoints.

The palette committed to one look. It used to derive surfaces from the host theme via color-mix() while hardcoding every accent — the intent was light-theme safety, but --h3-bg mixed toward #111827 and --h3-sunken toward #000, so a light theme got dark blue-grey islands anyway. It is now the PromptMasterLD .ldp-root system: #0a0a0a, one hairline #2a2a2a, zero radius, one accent #e8ff47. Changing --h3-accent moves the whole panel. Emphasis inverts (accent fill, --h3-on-accent ink) rather than tinting, because an acid accent at 30% behind unchanged text is olive mud.

A cascade trap worth remembering: the override block was first inserted before the reference-rail section, so .h3e-chip-on, .h3e-inactive .h3e-ord and .h3e-subj-badge all kept winning on source order. Overrides live at the end of the sheet now. Without a browser, a token audit script is the only thing that catches this class of bug.

The panel did not fill the node, and the mirror was why. installHeightGuard kept an independent _h, updated through an onResize hook, so that the arrange pass could not feed its own growth. Measured during a drag: onResize and setSize each fired 57 times while _h sat at 876 and node.size[1] climbed past 1400. measuring was not stuck, which left one gate -- Array.isArray(size). This frontend's node.size is not a plain Array, so every write was skipped and _h held the install-time height forever. A 1911px node had a 742px panel.

The repair was to delete the mirror, not fix the hook. _h existed only to break the arrange loop, and

panelHeight() = max(minHeight, node.size[1] - chrome() - SLACK)   // SLACK 8

breaks it outright: the pass wants panelTop + panelHeight + 4, and panelTop is chrome minus the node's bottom padding, so a panel of exactly size - chrome asks for up to 4px more than the node has on every frame -- the ~130px/frame runaway the header comment records. With slack the inequality holds, the loop settles, and the node's height simply is the panel's height. Nothing to keep in sync, no hook to get wrong. sync() now only ever grows a too-short node; the height is the user's to choose.

RUN is pinned and always open. .h3e-root used to be the scroll container with all four sections inside it, which put RUN below the script -- out of view on any workflow with more than two shots, and it is the section touched on every queue. The root is now a flex column holding .h3e-scroll (the authoring sections) and RUN outside it.

Two flex details, both of which cost a round trip to learn:

• .h3e-scroll needs min-height: 0. A flex item defaults to min-height: auto and refuses to shrink below its content, which pushes RUN off the bottom of the node instead of scrolling.
• .h3e-run must be flex: 0 0 auto, never 0 1 auto. Flex divides a deficit in proportion to each item's content height. The scroller's content is far taller, so a shrinkable RUN loses most of the contest and clips its lower groups. The scroller absorbs all the shrinking; its min-height: 160px is the floor that stops RUN owning the panel and RUN's max-height: 55% is the ceiling.

Always-open removed the only moment RUN re-read its widgets, so it now resyncs on api's promptQueued -- the client-side event that fires after control_after_generate has bumped the seed, and the same one ComfyUI's own change tracker uses. The listener is dropped in node.onRemoved.

Not done: PromptMasterLD's --fsc UI-scale multiplier, which makes every dimension calc(Npx * var(--fsc)) and puts a zoom slider on the panel. It is mechanical churn across every rule in the sheet and was not worth doing blind.

10. Ported for public use (2026-08-29)

The prompting craft was written down and the pack was made installable by a stranger. Four things, in the order they mattered.

The shipped example workflows were broken. All four in workflows/ predated the 2026-08-28 socket removal: twelve dead media inputs each, three LoadImage nodes, and 21 widget values against a 28-widget node. Loading one is a new user's first action, so this outranked any amount of documentation. They are quarantined in _disabled_custom_nodes/h3_legacy_workflows/ (the pack is not under its own version control -- deleting would have been unrecoverable) and replaced by two built from the verified H3_Stress_6x7 structure:

• HandTieClips_Starter.json -- two hops, no references at all, runs the moment the loaders are pointed at files. The empty register is deliberate: an @tag whose picture is missing is a hard error in resolve_tags, so a starter that shipped with tags would fail on first queue for everyone.
• HandTieClips_Showcase.json -- the six-hop continuity test, with the three reference filenames generalised.

Both use core ComfyUI plus this pack only. The dev workflow reaches KJNodes (ModelPreviewOverrideKJ, MiniMaxLowVRAMAttention) and PlagueKind (LTX_lora_loader, H3SLAAttention, H3AdaLNLoRAFix); an example that fails to load because of a pack the reader never asked for teaches nothing. The speed stack is documented, not shipped.

A declared-but-inactive @tag reported the wrong cause. check() already warned correctly that a picture was missing, but the run then died on resolve_tags with "unknown reference '@kitchen'" -- pointing at the beat's spelling, the one thing that was right. resolve_tags now takes declared (every tag in the register, active this hop or not) and separates the two failures. The old two-argument behaviour is unchanged when declared is omitted.

PROMPTING.md and prompt_pack/. The craft rules were spread through README prose; they are now a standalone guide, and a copy-paste system prompt that gets a language model to emit valid plans. Two files under prompt_pack/ are generated, never hand-written:

• tools/gen_schema.py builds SCHEMA.json from directives.VOCAB, refs.RETENTION and the duration table, and asserts against plan._SHOT_KEYS, refs.REF_FIELDS and refs.SUBJECT_FIELDS. Add a camera move and the schema follows; add a shot field and the generator fails loudly rather than emitting a stale schema. --check is the CI form.
• tools/gen_example.py builds EXAMPLE_6_HOP.md from the showcase workflow, including its hop/reference table, so the worked example and the shipped workflow cannot disagree.

Template patterns in the editor. js/editor/templates.js plus a Templates button in the SCRIPT header. They append, never replace -- replacing would be the one destructive control on the node, and stacking is how a chain is actually built. freeId() mints the lowest unused sN because id is the hop cache's pointer and two shots sharing one would make locked reuse the wrong render.

No template contains an @tag, for the same reason the starter workflow has no references. tools/check_templates.py extracts the patterns out of the JS and runs them through plan.parse_plan and plan.check_coherence, and lints every beat for negation -- a template that produced a plan the node rejects would be worse than no templates, because a first-time author would blame their own writing. It caught two: a beat reading "They stop at the window" (naming a cessation, which is law 2) and a line of dialogue containing "did not".

That second one is worth recording as an open question: whether the additive prompt bites inside quoted dialogue was never tested. The templates avoid it, and PROMPTING.md says plainly that this is untested rather than inventing a rule.

11. What chain_00057 taught (2026-08-29)

The six-hop showcase was rendered for the first time. Three failures, and the one that mattered was a code gap the documentation had already claimed was fixed.

locked and context reached hop 1 only. The register's whole promise is that a subject's continuity text carries identity across a hop where the photograph is absent. It did not. subject_prose is called under if i == 0, and _identity_lock returns "" when no subject-bearing ref is active -- so on the showcase, hops 2, 3, 5 and 6 carried no identity text of any kind, and hop 5, scheduled with no references at all, lost the character entirely. Identity was riding on the pinned frames alone, which is the exact failure the register exists to prevent.

refs.continuity_line() now emits that text on every hop 2+, and _assemble_next injects it between the lock and the live-frame citation. The reason it was suppressed in the first place is real and is preserved: naming pictures on a pin-only hop sent the encoder back to the plates (chain_00034 -- commercial kitchen, grey shirt, no apron). So the new line carries no <Picture N> and no <Subject N>. It is a description of what stays the same, not a citation of anything. <Subject N> is excluded specifically because there is no subject_definitions block on a continuation hop to bind it to.

Note this changes the assembled block on hop 2+ of every chain with a register, so it invalidates the hop cache. That is correct, not a regression.

Dialogue propagated through five hops. Shot 1 ended on its spoken line with tail: ongoing. The audio pin carries the previous hop's tail, so the last second of hop 1 -- speech -- opened hop 2, and "action is still underway" was the closing instruction; the model satisfied it with the action it could hear. Nothing in hops 2-6 gave the audio anywhere else to go.

This is the guide's own law 3, broken by the plan written to demonstrate it. The fix is authorial, not code: land the line mid-hop and leave a non-verbal action running into the seam (the knife on the board), and give every dialogue-free hop a narrowband sound of its own. Both PROMPTING.md and the authoring prompt now carry this as a named rule, and the shipped templates were rewritten to obey it.

join: continuous across a location change morphed one room into the other. Hop 6 walked back from the hallway and the kitchen appeared mid-turn. A continuous join asks for one unbroken take between two different rooms, which is not a thing. match_cut is what a walk through a doorway is. The beat also read "steps into @kitchen" -- the container phrasing the README warns produces a composite of the photograph -- and now names the counter in the kitchen.

Hop 5's beat is unchanged in the revised plan on purpose: it is the measurement, and changing it would forfeit the comparison.

The revised plan is in the shipped showcase and in user/default/workflows/H3_Stress_6x7_v2.json; the original that produced chain_00057 is left alone so the A/B survives.

12. Renamed to Hand Tie Clips (2026-08-29)

The pack was ComfyUI-H3-Ref-Chain. It is now ComfyUI-Hand-Tie-Clips, and the four registered ids moved with it:

was	is
H3RefChain	HandTieClips
H3ContinuityState	HTCContinuityState
H3ChainPreview	HTCChainPreview
H3ToneCompensate	HTCToneCompensate

Display names are unchanged (H3 Ref2VA Chain, H3 Chain Preview, ...) because the pack only drives MiniMax H3 checkpoints and a name that hides that costs somebody an afternoon. The menu category is Hand Tie Clips. TAG -- and so the console prefix -- is [HandTieClips].

The old ids are still registered, as DEPRECATED subclasses. A type id is what every saved .json carries, and an unregistered one is a red missing-node box, not a warning. A plain alias in NODE_CLASS_MAPPINGS would have worked but listed each node twice in search: ComfyUI falls back to the mapping key when NODE_DISPLAY_NAME_MAPPINGS has no entry for it. Subclassing and setting DEPRECATED = True gets both -- server.py:783 publishes deprecated: True, and the frontend's Comfy.Node.ShowDeprecated (off by default) keeps it out of search while leaving it fully functional in workflows that name it.

The JS had to learn both ids or the aliases would have been worse than useless. js/h3_ref_chain_ui.js and js/h3_chain_preview.js each compared nodeData.name against a single string; a legacy node would have loaded with no editor at all, which looks exactly like the rename having broken the pack. Both now test membership of a Set. js/h3_chain_preview.js needs it twice: once for its own type, once for CHAIN_TYPES, which is how a preview walks back up images to find the chain feeding it.

What deliberately kept the h3 naming, and must not be "finished" later: module filenames (h3_ref_chain.py), the h3e- CSS class prefix and --h3- tokens (515 occurrences -- one missed class silently breaks styling), the /h3_ref_chain/* routes, the h3_refchain_preview event name, and input/h3_refs. Renaming that folder would orphan every reference photo already on disk.

The two shipped workflows moved to HandTieClips_Starter.json / HandTieClips_Showcase.json and were rewritten onto the new ids, with their SaveVideo prefix now video/HANDTIECLIPS/chain. The three under user/default/workflows/ were left on the legacy ids on purpose: re-running H3_Stress_6x7_v2.json is then a live test of the alias path, and their existing renders stay together under output/video/H3REFCHAIN/.

13. The on-canvas board (2026-08-29)

workflows/HandTieClips_Starter.json carries six MarkdownNote cards to the left of the loaders, wrapped in a group titled READ ME. The text lives in tools/notes.py and is written into the workflow by tools/build_notes.py.

Why on the canvas: the craft was in PROMPTING.md, prompt_pack/ and the Templates panel, and all three require leaving the graph. The rules that decide whether a first render works are needed while beats are being written, which is on the canvas. The cards are a condensation, not a copy -- PROMPTING.md stays the authority and every card says so.

Mechanics worth not rediscovering:

• MarkdownNote is a core virtual node. The frontend renders it with marked at gfm: true and sanitises with DOMPurify, so headings, GFM tables, bold and code fences all work. It needs frontend >= ~1.16.
• Cards are identified by properties.htc_card, which is what makes build_notes.py idempotent -- it drops marked nodes before writing, so re-running replaces the board instead of stacking a second copy.
• extra.ds is restored on load, not fitted. Without setting it, a board at negative x sits off-screen and is never found. Screen is (world + offset) * scale, so the offset is what brings it into view.
• Group serialisation is {id?, title, bounding:[x,y,w,h], color?, font_size?, locked?} -- confirmed against the frontend's own zod schema, not guessed.

widgets_values_named, found while doing this. Both shipped workflows carried a stale copy: chains: 3, duration: 10 s, control_after_generate: randomize, and a legacy ref_plan naming pictures that do not ship -- 25 entries against a 28-widget node. It came from the builder deep-copying nodes out of the dev workflow and overwriting only widgets_values. Dormant while Comfy.Workflow.NamedValuesRestore stays off (experimental, default false), but anyone who turned that on would have loaded a Starter that randomizes its seed and dies on a missing reference. build_notes.py strips it from both, and tools/check_workflows.py now fails if it ever comes back.

tools/check_workflows.py is the promoted version of the validator that guarded the shipped workflows against socket/widget drift. It also checks the board: every card marked and non-empty, exactly one group, the group enclosing every card, and no card reaching past x=0 onto the loaders.

14. The turbo stack ships in the examples (2026-08-29)

Both shipped workflows now carry the dev graph's full MODEL wire:

UNETLoader -> LTX_lora_loader -> H3AdaLNLoRAFix -> MiniMaxLowVRAMAttention
           -> H3SLAAttention -> ModelPreviewOverrideKJ -> HandTieClips

and CLIP reaches the chain from the LoRA loader, not the encoder -- that is what makes the text half of every LoRA land, and it is the wire most likely to get quietly "fixed" back to the encoder by someone tidying the graph.

This reverses the earlier "core ComfyUI and this pack only" rule for the examples, at the user's direction: steps is 7, which only works with a turbo LoRA, so an example without the LoRA stack is not a graph anyone can run at the settings it ships with. PlagueKind supplies the loader, the AdaLN fix and SLA; KJNodes supplies Low VRAM Attention and the preview override.

tools/build_speed_stack.py inserts and rewires the five nodes idempotently (marker properties.htc_speed), rebuilding the plain loader -> chain shape first so it is reentrant from either state. tools/check_workflows.py walks both wires link by link -- a patch node that is present but bypassed round the side looks right on the canvas and does nothing.

H3SLAAttention widget values are written out in full including reference_protection, which post-dates the dev workflow's saved values. That workflow has 10 entries against an 11-widget node, which is the positional rule working as intended: the new widget was appended last, so old values still line up and the missing one falls back to its default. The trailing "" on the LoRA loader and the preview override is carried over verbatim for the same reason -- a value past the last widget is ignored, and dropping one that turns out to belong to a widget would shift every value after it.

head_chunks ships at 4 (the node's own default, safer on unknown VRAM) rather than the 2 used here. Two files have to be on disk as well: the turbo LoRA the loader names, and taeh3.safetensors for the preview override's tiny_vae.

15. What a shipped diagnosis looked like (2026-08-29)

The editor UI vanished after the folder rename -- raw widget boxes, no panel. Not a code fault. ComfyUI had been restarted while the pack was still ComfyUI-H3-Ref-Chain, so the running process held python_module: custom_nodes.ComfyUI-H3-Ref-Chain and served its web assets from a path the move had deleted. /object_info had all eight node types; /extensions listed none of the pack's JS and a direct fetch 404'd.

Worth knowing for next time: /object_info carries python_module, which is the fastest way to find out which copy of a pack a running server actually loaded, and /extensions plus a direct fetch of one script separates "the JS is broken" from "the JS is not being served at all".

16. What the Rain Kitchen renders taught (2026-08-29)

Three six-hop renders of the same 6x7 s chain, each isolating one variable. All three findings are now in PROMPTING.md, the troubleshooting table, the authoring prompt and the on-canvas board.

Identity drift is permanent, and the old advice was backwards. This file and PROMPTING.md used to say a face plate riding a later hop beats the pin and that shots should therefore be kept tight. chain_00059 falsified it: hop 4 carried a face plate photographed in a different kitchen through a walking medium shot and held cleanly, while hop 5 — scheduled with no references at all — came back a different person, and hop 6 never recovered even though a place plate rode it and restored the room instantly. locked holds a face that is still right; only a plate rebuilds one that is gone. Face refs go on every hop. The old advice survives for place plates only.

A beat must survive an over-delivered hop. A hop routinely does more than it was asked. Shot 3 asked for "a first slow step along the counter" and delivered the whole walk; shot 4 was then handed an instruction its own live frame had already satisfied, and the only way to obey was to reset the scene — a hard cut 1.5 s into the hop, not at the seam, because _assemble_next holds the incoming frames for a short beat first. Give one hop the whole movement, and write the next beat true from either ending ("she reaches the window", "she takes up the bowl again").

A noun with no adjective drifts. Three hops said only "the bowl"; it came back stainless steel. Naming it "the white bowl" everywhere and stating it in context as a property (never a location — "stays in her hands" fights the beat the moment she puts it down) held it for six hops. The re-run then proved the rule by accident: context read "the apron stays tied over the grey t-shirt", and the t-shirt held all six hops while the apron, one clause away with no colour, had turned denim blue by hop 6.

The code change this bought

refs.resolve_tags now takes subject_names and the node passes it on continuation hops only. <Subject N> is bound by subject_definitions:, which is hop-1 material — so on hop 4 the ordinal dangled, exactly the same defect as the undescribed bowl. From hop 2 a person tag resolves to the subject's name instead ("The cook walks down the hallway"), which binds to the continuity_line sentence every continuation hop already carries. No name means the old <Subject N> fallback, so nothing regresses.

tools/check_prompts.py mirrors the new call, and gained the banned-word check that previously ran only against templates.js. That gap is how the shipped Showcase carried "None of the kitchen is visible" (law 1 — it adds a kitchen at cfg 1.0) and "She stops at the window" (law 2) through six versions. Both are fixed, and the Showcase's face ref now rides all six hops.

17. The pre-beta audit (2026-08-29)

Read for what a stranger hits, not for what we already check. Six findings; the first two would each have cost a tester a run.

The docs promised a stop the code never did. refs.check() is "warn, never raise", and its caller only printed. A ref naming a file that is not in h3_refs had its slot skipped and the chain rendered on — all six hops, with the reference silently inactive, which is precisely the uncontrolled output the register exists to prevent. Four shipped surfaces said otherwise, including the Showcase's own note: "the run stops and names the reference it could not find. Nothing guesses."

Fixed in the code rather than the docs, because there is no reading under which rendering without a named-but-absent picture is what the author meant. New refs.missing_files() returns (tag, file) for every ref whose named file did not load; h3_ref_chain.py raises on it, after printing the register table so the error arrives with its context. The distinction that matters: a ref with no file stays a warning — the Starter ships that way on purpose so it runs before any pictures exist. Only a named file that is absent is fatal.

The on-canvas board never got §16's corrections. tools/notes.py still carried the row chain_00059 falsified — "a plate riding a hop it does not belong on, beating the pin → tighten shots" — and was missing all three rows PROMPTING.md gained. The board is what a beginner actually reads, so it was shipping the inverse of the rule. Lesson: PROMPTING.md is the authority, but tools/notes.py is a second copy of the same craft, and a correction is not finished until both move. build_notes.py regenerates the Starter's cards and the Showcase's Note from notes.SHOWCASE_NOTE, so one rebuild covers both.

The rest were packaging, not craft: the MIT LICENSE named no copyright holder; pyproject.toml lacks both fields a Registry publish needs (PublisherId and a [project.urls] Repository), now commented in place; the README had no install section at all; ComfyUI-H3-Motion-Context was absent from Needs despite the intro calling it the primary guidance path, so testers land on the MiniMaxH3AddGuide fallback without knowing they changed code paths; and the example workflows name quantised checkpoints by filename with no note that they are one valid set among many, which reads as a broken graph rather than a missing file.

Clean on the same pass, worth not re-checking: no personal data anywhere, no hardcoded local paths in runtime code (only two dev-tool docstrings), 3.10-safe syntax, no third-party dependencies, Motion-Context absence handled with fork detection, WEB_DIRECTORY present, h3_refs auto-created.

18. What a 27B model got wrong, and what the prompt taught it (2026-08-29)

Qwen3 27B at temperature 0.3 was given an 8 x 15 s concept. The ref_plan came back structurally perfect -- both subjects named, face plate on all eight hops, places scheduled off the hops they do not belong on, zero register warnings. The shot_plan carried four defects, and tracing each one back to prompt_pack/AUTHORING_PROMPT.md found more than four gaps.

The prompt taught one of the bugs. Rule 9 illustrated a beat as "stands at the counter in `@kitchen`" -- backticks and all, because it was the one place a tag appeared inside a beat. The model copied the formatting, and literal backticks reach the encoder. Fixed, plus a rule that a beat is plain prose.

Beat length had no guidance at all. The only budget in the file was for dialogue, so a no-dialogue plan had nothing to size against and every beat came back at 22-28 words regardless of a 15 s hop. There is now a word table -- and an honest note on it: the shipped plans run 37-39 words at both 5 s and 7 s, so beat length is near-constant across the only two hop lengths ever rendered. The words-per-second reading that gives 70-100 for a 15 s hop is a reasoned extrapolation, not a measurement, and the table says so.

Two rules were simply missing. Nothing told the model to state a visual style -- for a "2D anime, Ufotable" concept neither returned block contained the word anime, so the text asked for photoreal while the pictures asked for anime. And the over-delivery rule from section 16 had never been carried into the prompt at all, only into PROMPTING.md and the board.

Two statements were wrong. The prompt said "at most 9 pictures on any one hop"; parse_ref_plan counts len(refs) over the whole plan. The code's own error message said "on one hop" too, and has been corrected to match what it checks. And the file bullet still told the model to invent placeholder filenames without noting that, as of 0.3.1, a named file absent from h3_refs stops the run.

Law 2 is the interesting non-fix. It is stated plainly, with the exact example "The cook stops talking", and the model wrote "stops and looks up" anyway. A principle is not something a 27B reliably applies to its own output; the literal word list check_prompts.py enforces now appears in the prompt, because a word list is checkable and a principle is not.

19. What 114 seconds of rendered film and two 27B models taught (2026-08-29)

Three sources landed together: a rendered 8 x 15 s anime chain (chain_00003, 2742 frames, 114.25 s), and Qwen and Gemma each answering two test prompts written to trip specific rules. Shipped as 0.3.3.

The node was fighting every stylised plan

directives.py prepended ESTABLISH = "Live-action, natural light, one continuous take." to hop 1 unconditionally. At cfg 1.0 with no negative branch that is additive, and it landed ahead of the style declaration rule 12 requires. A stop-motion puppet plan compiled to "Live-action, natural light, one continuous take. ... Hand-drawn stop-motion puppet animation in felt and painted wood", and the two fought.

It also explains the anime chain's opening: hop 1 rendered as bright naturalistic daylight (mean luma 72) against a night plan and a night place plate, then fell to 46 on hop 2 the moment ESTABLISH stopped riding. That had been read as drift; it was the node.

Never surfaced because both shipped workflows are live-action.

Fixed twice over, because either alone leaves a hole: an establish widget (appended last in optional, per the positional-widget rule in section 8), and directives.declares_own_medium() / establish_for(), which drop the default when shot 1's opening names a medium. A model-authored plan never touches a widget, which is why the automatic arm is the one that matters.

Luminance drifts, and it only goes one way

Mean luma per hop across the eight: 72, 46, 35, 17, 11, 11, 19, 14. Setting the ESTABLISH artefact aside, hops 2-6 still slide 46 -> 11. The combat, the point of the film, plays at the bottom of it.

This is the colour law one level up. locked holds a face; nothing holds an exposure. Each hop inherits the last frame and darkens it slightly and the error compounds. Restate the light as a positive property in every beat -- naming a light source ("pale moonlight") does not set a level, and at cfg 1.0 it only adds a moon.

The seams were never the problem

7 of 7 hop joins are invisible: largest frame-to-frame difference at any seam is 13.6, inside the range of ordinary in-shot motion, and two seams score below the film's own mean. Identity held 114 seconds on face plates riding every hop.

The one hard cut in the film is inside hop 4, 3.25 s in, at 7.1 sd -- more than double any other jump. Shot 3 ended "ahead the trunks begin to thin toward open ground"; shot 4 opened "Across the flat moonlit stone of @arena_clearing the two of them square off". Hop 4 was handed a live frame of a man among trees and a beat asserting he stood on open stone, held the forest for 3.25 s, then reset the scene. The plan was clean under check_coherence and the banned-word scan. Hence plan.check_place_handoff().

What the two models did

Near-identical answers from Qwen and Gemma on the same prompt -- same beats to the word in 5 of 6 shots, same defects, same invented justification. The prompt is prescriptive enough to collapse two models onto one answer; a shared blind spot is then invisible from output alone.

The word table was inert. Both models, asked for six 15 s hops, returned beats averaging 54 words against a 70-100 band -- every beat under the floor -- and the same models on much shorter hops returned 40-48. Beat length is near-invariant to hop length in model output, now measured in a third setting. A reference table does not move a model with a prior on paragraph length; the rule is now an instruction to count, with a worked 74-word example.

The banned-word list beat the principle, and made things worse. Zero literal banned words in all four plans -- and "The storm's roar begins to fade... raindrops strike the glass with decreasing force" and "The storm has passed". The list taught token avoidance and handed them a box to tick. It is now framed as crude examples of an idea, with the test stated as: is this happening, or has it finished happening?

Both abandoned the second location. Each plated the opening place, moved the story elsewhere, gave the new place no plate, and justified it with a rule that does not exist ("to avoid conflicting with the frame pin of the new space"); Qwen cited "rule 8/9", which does not say that. In the lighthouse plan that left the lamp room -- four of six hops -- on beat text alone.

check_place_handoff has two arms, and both were narrowed by real plans

1. Handoff. Shot N names a place tag shot N-1 never mentions, and shot N's own beat does not carry the journey. The arrival vocabulary had to widen: the Showcase's shot 6 ("walks back along the hallway and through the doorway to the counter in @kitchen") is correct and was being flagged.
2. Abandonment, not gaps. Warning on any unplated hop also flagged the Showcase, which deliberately walks her down an unplated hallway on 4-5 and returns the kitchen plate on 6. The rule that survives contact: warn only when the plates stop and never resume, so the film ends somewhere no picture describes.

Both shipped workflows are clean under the final version; the anime plan raises exactly one warning, on shot 4.

Audio, for the record

No background music and no speech, confirmed on the spectrogram: broadband transients and noise, no harmonic bands. Seam levels hold within +/-2 dB on five of seven joins, and the two exceptions are drops the beats themselves ask for. The real audio issue is range, not seams: peaks reach -1.2 dBFS during the fight while hop 8 averages -42 dBFS. There is no audio equivalent of HTCToneCompensate. Left open.

20. Seven features built blind (2026-08-30)

Built in one pass with no browser and no GPU render available -- the user was away and explicitly asked for the work anyway. Everything below was verified by offline execution only. Section 21 is what happened when it was finally opened in ComfyUI: two of the seven shipped broken in ways no offline test could have caught, and the rest measured out. Read section 19 first for the measurements that motivated most of it, and 21 for what survived contact.

What shipped

#	thing	where
1	tone_compensate=anchor + tone_anchor strength	tone.py, wired in h3_ref_chain.py
2	dry_run -- compile every prompt, render nothing	h3_ref_chain.py
3	contact_sheet -- a fourth IMAGE output	new sheet.py
4	render_through -- stop after hop N	h3_ref_chain.py
5	quality=draft -- 0.3 MP, 6 steps	h3_ref_chain.py
6	H3 Seam Report node	new seam.py
7	over-delivery lint	plan.py

Five new widgets, appended LAST (29 -> 34 values). One new output, appended LAST (3 -> 4). Both rules are in section 9; both were obeyed.

The anchor, and why it is not just another tone mode

frame_shift/gain_bias/lut are seam-local: they cancel the denoiser's tone bias on the overlap, which makes each join exact. They cannot see the exposure falloff inside a hop, and that is what compounds -- hop N darkens across its own frames, hands the darker tail to hop N+1, and every individual seam stays perfect while the film dims. Section 19 measured 46 -> 11 across hops 2-6.

Worth stating plainly because it is counter-intuitive: a synthetic 8-hop chain showed frame_shift making the total slide WORSE (66/255 vs 35/255 with correction off). That is correct behaviour, not a bug. The denoiser's per-hop bias happened to lift; cancelling it removed a lift that had been partly offsetting the falloff. Seam correction fixes seams. It was never a level control and should not be read as one.

anchor = frame_shift + a second stage pulling each hop's mean back toward hop 1's. Two properties make it safe to stack:

• the pull ramps from zero over ANCHOR_RAMP (48f) frames, so frame 0 of a hop is returned untouched and the seam stays exactly as frame_shift left it. Without the ramp a per-hop constant offset re-introduces precisely the step frame_shift just removed -- this is the whole design, and the trap anyone re-implementing it will fall into;
• it is capped (ANCHOR_MAX_SHIFT, 0.06) and scaled by tone_anchor (0.35), so a slide is corrected across several hops instead of one hop snapping back.

The correction needs no carry variable between hops: because it is applied before prev_imgs is taken, the next hop's seam correction matches the already-corrected tail and the offset propagates on its own.

On the synthetic chain: slide 66 -> 18/255, worst seam step 2.22 -> 2.13/255. The seam did not regress, which is the property that mattered.

Intent is indistinguishable from drift from the inside, hence the per-shot tone field: "free" skips one hop's pull, "rebase" moves the anchor onto that hop. A deliberate walk into a cellar needs rebase or the chain spends the rest of the film brightening it back.

dry_run: what it must not touch

The value is that it costs seconds, so every expensive thing is guarded: MiniMaxH3SigmaShift, KSamplerSelect, BasicScheduler, _model_fingerprint (it hashes patched weights), the hop store, and -- the big one -- the master preallocation. master_imgs for 8 x 15 s at 1280x736 is 2742 float frames, about 31 GB. A dry run that allocated it would be worse than useless.

Hop 2+ needs a prev_imgs to compute <Picture N> ordinals. Content is irrelevant to the compiled text, so a [overlap, 8, 8, 3] zero tensor stands in and the text is byte-identical to a real run's.

The smoke test (tmp/t_dry.py) replaces all five sampler entry points with objects that raise on any attribute access, so "did not touch the sampler" is asserted rather than assumed. It caught one real bug: the dry block referenced pin_mech_pred before its assignment, ~40 lines later. Which pin a hop gets is decided at render time from whether a sampler latent exists, so a dry run genuinely cannot know it -- the sheet reports the pin_to_qwen setting instead. Reporting AddGuide for every hop would have been a lie.

The over-delivery lint

The one defect class every other check structurally misses: both shots are individually well-formed, the directives are individually legal, and only the JOIN between them is wrong. tail=settle|hold promises rest; a following beat that opens "She continues...", "Walking to...", "Mid-sentence..." asks the model to carry on what the hop before was told to stop.

Narrow on purpose. Trailing spaces in _MID_ACTION are load-bearing ("keeps " not "keepsake", "still " not "stillness"), and _MID_ACTION_LEAD is only checked at position 0, which is what stops "Morning light..." and "Nothing moves..." from firing. Verified against those exact traps, and both shipped plans stay quiet.

It will miss a beat that opens mid-action without saying so. That is accepted: a false positive that blocked a render would be worse than the defect.

Notes for whoever picks this up

• sheet.py and seam.py catch every exception and return a placeholder image. A picture must never lose a finished chain. Do not "clean up" those handlers. The placeholder was 1x1 until section 21 -- see there for why an inert-looking image is not inert.
• The contact sheet stores frames through sheet.small() (168px tall). Two full frames per hop across eight hops is 180 MB held for the whole render for no reason.
• The sheet shows imgs[overlap_n] for hops 2+, not imgs[0]: the first overlap frames are trimmed at the join, so imgs[0] is a frame the master never contains.
• tools/check_workflows.py derives the expected widget list from the live INPUT_TYPES, so it needed no edit for the five new widgets -- only SaveImage added to CORE, for the Starter's new contact-sheet node. (Section 21 added PreviewAny, PreviewImage and HTCSeamReport to those allowlists when the seam report was wired into the Starter.)
• The Starter now ships contact_sheet=on with a SaveImage wired; the Showcase ships it off. Starter is the teaching graph, so the feature is on the canvas where it will be found.

Unverified, in priority order

All five items that stood here were closed on 2026-08-30. See section 21.

21. What the first ComfyUI session measured (2026-08-30)

Section 20's seven features, opened in a browser and run on a GPU for the first time. Five measured out. Two were broken, and neither could have been caught by any offline test that existed -- both failures lived in the gap between "the Python is correct" and "the graph runs".

Bug 1: 0.4.0 never touched js/

git show --stat on the 0.4.0 commit lists twenty files and not one under js/. The five new widgets were declared in INPUT_TYPES and never added to GROUPS in js/editor/run_panel.js, so the run panel did not draw them.

It did not look broken, which is the interesting part. The panel hides only the widgets it successfully drew -- a deliberate design so an undrawable dial never vanishes from the node -- so all five fell through to native dials and worked fine. tools/check_workflows.py passed throughout, because it derives from INPUT_TYPES and GROUPS is display-only.

The lesson: a Python-side widget list and a JS-side widget list are two sources of truth, and nothing checks that they agree. Adding a widget means editing both. There is still no checker for this.

Bug 2: a 1x1 image is not inert

A dry run returned sheet.placeholder() on images -- a 1x1 black frame. The Starter wires images into CreateVideo -> SaveVideo. libx264 in yuv420p subsamples chroma by 2 and cannot open a codec context on an odd dimension, so every dry run died in avcodec_open2 before writing a frame, with a traceback naming ComfyUI's video node and nothing of ours.

Reproduced in isolation: 1x1 throws, 2x2 encodes. placeholder() now takes a width and height, floors at 2x2, and rounds odd dimensions down to even; the dry run passes the geometry the plan resolved to, so a dry run yields one black frame at the real resolution and downstream video nodes are happy.

tools/check_features.py had asserted shape == (1, 1, 1, 3) -- the offline suite was pinning the bug in place. It now asserts an encodable() contract instead. A test that encodes an exact wrong value is worse than no test.

tone_compensate=anchor, measured on a real chain

Three hops, 8 s, 0.3 MP, 6 steps, one seed, one cache. Because the hop store writes before the tone block runs, flipping tone modes re-grades cached renders in ~14 s instead of 164 s -- so the whole sweep is nearly free. Drift is hop 3 mean minus hop 1 mean; seams are the step across the join.

tone_anchor	drift	seam @192	seam @362	flicker
off	13.5/255	+0.9	+2.1	0.4675
0.15	7.4 (-45%)	-1.3	-1.0	0.4566
0.35	5.1 (-62%)	-1.9	-1.6	0.4618
0.60	2.9 (-78%)	-2.6	-1.8	0.4661

Seam figures are seam.measure(window=6) -- the shipped node's own method, not an ad-hoc frame difference -- so the docs and the instrument a user runs agree.

Drift removal is even: 45 / 62 / 78% of the uncorrected slide, ~16pp per step. The seam is not monotonic. 0.15 pulls it tighter than the uncorrected chain (2.1 -> 1.3) before it grows again, so there is a shallow optimum below the default rather than a straight trade. From 0.15 up it costs ~0.6/255 per step. Note also that the seams flip sign: uncorrected they are positive, and every corrected run overshoots slightly negative. Hop 1 is byte-identical across all four, as the design requires. The shipped 0.35 default stays -- it halves the drift while every seam still reads marginal or better.

The propagation claim in section 20 -- that no carry variable is needed -- is visible in the logs: hop 3's frame_shift grew with anchor strength (r+0.0185 -> r+0.0217 -> r+0.0256) because hop 3 measures against hop 2's already-corrected tail. It self-propagates, exactly as designed.

Caveat that limits this measurement: the test scene walks the subject toward a bright window, so some of that 13.4/255 is light a real camera would also produce. Anchor cannot distinguish motivated light from drift -- that is what the per-shot tone field is for. A camera=hold scene is the run that would justify moving off 0.35.

The seam report node, validated

Never executed before this session. Wired into the Starter and checked against an independent decode of the mp4: agreement to ±0.07/255 across six seam readings under two different hop geometries. Its arithmetic is right.

A better result came out of the cross-check. On a 5-hop master the eight largest frame-to-frame luma jumps were at f289, f368, f409, f412, f463, f464, f482, f497 -- not one of them a seam. Every join is quieter than ordinary scene motion. That is the pack's central claim, measured.

Trap, and it cost a wrong diagnosis. 5 hops x 124f and 3 hops x 192f both total 532 frames at overlap 22. The node derives hop length from frames, hops and overlap, so a wrong hops yields a plausible length and four confidently wrong seam positions. There is no way for it to know better from images alone -- but the chain's info output carries the real geometry, so an optional info input that cross-checks would turn this class of mistake into an error message. Worth doing.

quality=draft is close to a no-op here

Draft's two levers are resolution -> 0.3 MP and steps -> 6. In the turbo regime this pack targets, a "final" run is already 0.3 MP at 6-8 steps, so the first lever does nothing and the second saves one step:

• draft, 6 steps: 42.1 s/hop
• final, 7 steps: 43.3 / 45.2 / 50.2 / 44.1 s/hop

About 7% apart. Draft only earns its place if final is genuinely heavier -- 1.0 MP at 14 steps. Kept, because that configuration exists, but it is not the fast-preview button it sounds like. dry_run is the fast-preview button.

The rest

• Contact sheet: correct and genuinely useful on real renders -- first/last thumbnails per hop, directives, beat, tone line, seed, cached, pin mechanism. Legible at 1:1; not legible in a node preview, where a 1280px sheet scales to ~0.25 and 15px body text renders at ~4px. It is a click-to-enlarge document. Fonts left alone deliberately.
• render_through: truncates correctly (rendering hops 1-1 of 2), and re-extending works -- a 3-hop chain extended to 5 loaded hops 1-3 from cache and started rendering at hop 4.
• Over-delivery lint: exercised offline; never fired in ComfyUI because both shipped plans and the test plan stay clean. Unproven against a real positive.

22. Two models, one prompt, the same two mistakes (2026-08-30)

A 3-hop / 10 s brief was written to load six traps into thirty seconds, and handed to two local models in LM Studio with prompt_pack/SYSTEM_PROMPT.md in the system box, temperature 0.4, and nothing else. EXAMPLE_6_HOP.md was deliberately withheld -- it argues for six hops and would have contaminated a 3-hop test. Grading ran every reply through the real parsers rather than by eye.

	qwen	gemma 26b-a4b
FAIL	4	2
after the shared prompt bug	2	0

Both models made the same tag mistake, which makes it the prompt's. Each wrote @kitchen in the beat -- correctly, that is rule 10's own example -- and then invented "tag": "kitchen_plate" for the register. The string _plate appears nowhere in the prompt; they arrived at the same convention independently. The cause was in the file: rule 10's only concrete place tag lives in a beat, the register example held one ref (hero_face, a person), and the two were never shown together. The invariant was stated, in a field bullet 150 lines later -- and models copy examples, not bullets. PROMPTING.md, the human guide, has had a three-ref example including kitchen all along; the machine prompt was trimmed and lost it.

The silent one. qwen wrote "name": "@cook_face" into subjects. That parses, resolves, renders, and is wrong: name is what resolve_tags substitutes for a subject's tag from hop 2 on, so the tag resolved to itself and a literal at-sign reached the encoder on two of three hops. Nothing caught it. check_prompts.py would have, but only for the two shipped workflows.

Where the models actually differed is invisible to any parser. Both lifted rule 2's worked answer verbatim ("water runs in slow threads down the window glass"). But hop 3 moves to a hallway, and qwen also copied rule 4's example object -- putting "a single click from the refrigerator" in a corridor, the kitchen appliance following her out of the room. gemma copied rule 4's method and wrote "the low hum of a hallway light". Recitation versus transfer, and only one of them survives a change of location.

Both also left tail off hops 1-2, describing the arrival at rest in prose instead of directing it -- so the over-delivery lint, which only arms after a settle, still has not fired on a real positive.

Fixed here: the register example carries a place tag on both sides of the round trip and says the two spellings are one string; refs.py rejects an @tag in name, locked or context. Not fixed, because it is a brief-writing lesson rather than a bug: ending a chain in a location no plate describes earns the place-handoff warning, and that was the brief's fault, not either model's.

23. The hop cache stops shelling out (2026-08-30)

The Comfy registry flagged all three published versions. The reason is not in the web UI and status_detail on the node is empty; it is behind https://api.comfy.org/versions?nodeId=<id>&include_status_reason=true, which returns the actual findings:

scanner      yara_scan
issue_type   python_command_injection_risk
file_path    store.py   lines 131 and 215
description  "Detects all os.system and subprocess usage"
severity     info
recommendation  null
admin_tags   any-code-execute

Two findings, both the subprocess.Popen calls that ran ffmpeg for the FFV1 hop cache. The rule does no taint analysis, so a static argument list built from shutil.which and run with shell=False matches exactly as hard as a shell injection would. Its 95% confidence is confidence that the call is a subprocess call, not that it is exploitable.

Appealing looked like the wrong move. plaguekind-nodes -- 22.5k downloads -- has 1.3.8 through 1.4.0 flagged with the same two findings and 1.4.1 onward Active with status_reason = "Passed automated checks", the string the scanner writes when it finds nothing. That is a code change, not an admin override.

But the registry is the weakest reason to have done this. _ffmpeg() raised if no ffmpeg binary was on PATH, and ComfyUI never requires one -- so the feature that makes a tone A/B cost 14 s instead of 164 s hard-failed for a large share of users, on the pack's fastest path, at the exact moment a CivitAI post would send new people at it.

PyAV is a hard dependency of ComfyUI itself (SaveVideo and CreateVideo are built on it) and its ffv1 encoder lists rgb48le among 61 pixel formats, so the format did not have to change: ffv1 / rgb48le / level 3 / coder 1 / context 1, in matroska. Verified before writing any of it, and again through the real HopStore:

• PyAV encode -> PyAV decode: bit exact, including 0, 65535 and midpoints
• ffmpeg encode -> PyAV decode: bit exact -- existing caches on disk still read, which is the part that protects users
• file sizes within 44 bytes of each other (145,780 vs 145,824)
• a frame-count mismatch still raises rather than returning a short clip

The decode path also got slightly better on the way: it decodes into one preallocated (n, h, w, 3) array instead of building a list of frames and stacking, so there is no second full-size copy. Five documents claimed ffmpeg was required -- CLAUDE.md, PROMPTING.md, README twice, and the on-canvas card in the Starter workflow via tools/notes.py. All corrected. README's existing "No dependencies to install" line, which already listed av, is now true rather than nearly true.

24. The panel learns to write its own plans (2026-08-30, ALPHA)

prompt_pack/README.md step 7 has said the same thing since the pack shipped:

If the node rejects the plan, paste the error straight back into the chat -- every message names the shot or reference it came from, and one round trip usually fixes it.

Section 22 measured how often that is needed. Two unrelated model families, one prompt, and both wrote a beat citing @kitchen while the register declared only the people -- so resolve_tags raised and the queue stopped. Both were fixed by one round trip. An instruction that reliable is a feature that has not been written yet, so this section writes it.

What was built. llm.py talks to any OpenAI-compatible server; planner.py generates, validates with the node's own checkers, feeds any error back, and tries again up to three times; routes.py gains GET/POST /h3_ref_chain/llm and POST /h3_ref_chain/plan; js/editor/writer_bar.js is a collapsed WRITE section at the top of the panel. About 900 lines including the tests.

What was deliberately not built. The prior art is the author's other pack, PromptMasterLD -- 52k lines, an LTX shot writer with 47 accents and a dial system, driving llama-server through backend.py. Three of its decisions were copied without re-litigating them, because its comments record why: the LLM never runs during a graph execution, INPUT_TYPES makes no network call (a GGUF scan once fed ComfyUI's Missing Models panel and offered to download weights for users touching no local file), and there are no API keys anywhere.

Its process management was not copied. cpld_conn.json carries llama_exe, and backend.py:353 shells out to lms unload --all. That pack has no pyproject.toml and is never scanned; this one was Flagged under python_command_injection_risk for 0.4.1-0.4.3 and only cleared it in section 23 by migrating store.py off subprocess.Popen. Same code, different consequence. Every rung of the unload ladder here is HTTP, which leaves four of its five. Its urllib.request was not copied either -- these calls are awaited inside aiohttp handlers, where a blocking read freezes the whole ComfyUI UI for the length of a generation.

The part that matters is the loop, and the part that matters about the loop is that it was tested. write_plan() takes its completion function as an argument, so tools/check_planner.py drives it with a scripted model: attempt 1 returns the real A/B fault, attempt 2 returns a clean plan, and the test asserts that the node's own error text reached the model, that the rejected reply stayed in the conversation, and that it converged in exactly two attempts. It also asserts the loop gives up rather than returning an unvalidated plan. No server, no GPU, 25 assertions.

That test immediately earned itself. validate() first passed an empty set as wired_slots, so no ref was ever active on any hop and resolve_tags rejected @kitchen -- a tag that was declared correctly. Every good plan looked broken, and the failure was indistinguishable from the bug the loop exists to fix. wired is now derived from the file list, which is what the node does with files it actually decoded.

Three LM Studio facts found by running it. First, /v1/models lists what is installed, not what is loaded: the first live call picked a model straight off that list and came back HTTP 400: Model unloaded by user or API request. The dropdown now reads /api/v0/models for a state field, marks loaded models ●, sorts them first, and the 400 is translated into a sentence naming the fix. Second, ttl is still not sent, for the reason recorded in backend.py:791 -- handing lifetime to LM Studio unloaded a 26B model thirty seconds after the prompt finished, while the panel still said the writer was warm.

Third, and this one nearly shipped as a wrong diagnosis. max_tokens started at 4096 and every live run came back with an empty content, so the code announced "this model answers with reasoning only and ignores both thinking switches". It was wrong. Measured against the shipped prompt:

max_tokens	finish_reason	completion	of which reasoning	content
4096	length	4096	4093	0 chars
12288	stop	8868	8010	2958 chars

The model was not refusing to answer, it was still thinking when the budget ran out. A short prompt to the same model returns content and reasoning_content together, which is what proved it. MAX_TOKENS is now 12288, and an empty content is split three ways: finish_reason == "length" names the truncation and the token counts, a clean finish with reasoning still triggers the /no_think retry, and neither is reported as the other.

The A/B, re-run through the loop. Section 22 graded these two models by hand and gave gemma the win on 2 FAIL against qwen's 4. Through the repair loop that verdict inverts, and then stops mattering -- 3 trials each, same brief, same 31-file reference folder:

model	converged	attempts	wall clock
gemma4-26b-a4b	3/3	always 2	58-97 s
qwen3.8-27b	3/3	always 1	105-130 s

qwen writes an acceptable plan first time and is slower doing it; gemma is roughly twice as fast per attempt and reliably spends the saving on one repair. Both land in about the same place. The loop is what makes the model choice uninteresting, which is the strongest argument for it -- section 22's careful grading was work that no longer has to be done by a person.

gemma's repair is not one fixed mistake: across runs it put join at shot level instead of inside directives, and invented hallway_window.jpg against a folder whose real names are jFJ7P.jpg and h3_stress_kitchen_1.jpg. The second is worth naming -- the invented-filename error used to print all 31 available names inside every retry turn, burying the one sentence that said what to do. It now shows twelve and a count.

Known limits, all documented rather than discovered. A headless or API-submitted run gets no plan writer, which is the price of keeping the model off the execution path. Structured output degrades to plain-text extraction on llama.cpp builds that reject response_format. And the loop only catches what the parsers can decide -- a beat that is merely bad still passes, so the WARN tier is shown and never auto-retried.

25. The seam report had the sign backwards (2026-08-30)

Two 2-hop renders of the same kitchen scene at 736x416, 7 steps, seed fixed: one at 5 s (124f) with tone_compensate=frame_shift, one at 8 s (192f) with anchor. The seam reports called them invisible and marginal. Both were wrong, and not in the direction the docs already warned about.

run	seam report	true per-hop drift (hop cache)
5 s, frame_shift	-0.31/255 invisible	+2.17/255
8 s, anchor	-1.05/255 marginal	+2.63/255

CLAUDE.md's tone notes record that seam readings come in about a third low, because the frames either side of a cut are ~0.9 s apart in scene time and the content change partly cancels the drift. On this scene it does not partly cancel it -- it reverses it. The beat has the cook set a knife down and turn toward a window, so the scene darkens across the cut by more than the generator's +2.6/255 brightening, and the seam lands negative. invisible was sitting on top of the largest per-hop drift measured on this scene.

So the existing rule is not conservative enough. "Never use a single seam reading to decide" is right; the reason is stronger than stated, because the error is not bounded in magnitude or direction. tone_probe against the hop cache stays the only honest instrument, and its standing caveat applies -- temp/ is wiped on ComfyUI start, so probe before restarting.

anchor behaved exactly as specified, on the scene type that had never tested it. Shot 1 was camera=hold -- the case section 21 named as "the run that would justify moving off 0.35", open ever since. Logged: anchor r-0.0050 g-0.0047 b-0.0053 (gap -3.6/255, ramp 48f). The arithmetic closes -- 3.6/255 x 0.35 = 1.26/255 = 0.0049 against the logged 0.0050 -- so the strength is doing what it says and the held camera did not perturb it.

Nothing here argues for moving off 0.35, and a 2-hop chain never could. Both drift figures sit in family with the measurement behind the linear model in CLAUDE.md (~5/255 by hop 3, ~10/255 by hop 5). At two hops there is not enough cumulative drift for the strength to matter; a 35% pull on a 3.6/255 gap is ample. The test that could decide it is 4-5 hops, where cumulative reaches 8-13/255 and an under-strength anchor would visibly fail to keep up.

One thing that makes that test cheap: tone_compensate is in neither chain_salt nor the per-hop key. Re-queueing the same graph with a different mode cache-hits every hop -- no DiT load, no resample -- and yields a master differing only in the correction. That is the same-seed-same-cache condition CLAUDE.md demands, and it costs about 18 s rather than a full render.

The probe itself needed fixing before any of this could be read: with both runs in the cache it differenced across renders and reported -30.37/255. See the tone_probe commit.

26. The texture metric everyone reaches for is the wrong one (2026-08-31)

Numbered 26 because 24 and 25 are on the llm-plan-writer branch, which is on hold. Nothing here depends on them.

A user running H3 chains on a different rig -- MiniMaxH3SongMaskedAVContext, source_latent, context_length 39 -- reported "saturation and overbaking on close shots": skin blotchy, hair frizzed into noise, the face restructuring by segment 4. They came with a measured report over 81 chained clips and a fixed-seed harness, and with a question aimed at this pack: is the latent hand-off amplifying high-frequency energy, or is the sampler over-sharpening the generated region to match the sharpened context it was handed?

Their metric was mean |Laplacian| over the frame, end of last segment over start of first. It gave 1.060 / 1.180 / 1.204 for 2 / 3 / 4 hops.

On the two clips they sent, that metric reads 0.961 and 0.973. Both faces are visibly destroyed by the end -- frame 5 against frame 1045 is not a close call. The metric says one of them got slightly better.

It is confounded twice.

It is an area average. A face is about 6% of a 736x1312 portrait frame, and these clips are a talking head against wood panelling, a fleece throw and two sconces. The background does not change; it outvotes the face roughly sixteen to one.

It sums every spatial frequency into one number, so energy moving between bands cancels. Measured on the same clips:

	luma	global sigma	fine <1px	mid 1-2.5px	coarse 2.5-6px
TEA2	92.2 -> 90.1	59.7 -> 58.0	x1.09	x1.17	x1.03
TEA3	106.0 -> 104.1	56.9 -> 54.4	x1.33	x1.35	x1.30

Global contrast falls while mid-band energy rises. No single scalar can represent that, and a correction tuned against one is tuned against noise.

Three things follow, and each changes what a fix should do.

The band is mid, not high. "Blotchy skin" is mottle at 1-2.5 px, not grain. A fix aimed at high-frequency sharpening aims past it.

The climb is continuous, with no step at the joins. TEA2's background mid-band, in 60-frame bins: 1.57 1.55 1.56 1.56 1.57 1.60 1.68 1.66 1.61 1.64 1.71 1.71 1.72 1.77 1.85 1.85 1.93. A ramp, not a staircase. So the hop boundary is not where the damage is injected -- it is the ratchet pawl. It carries the degraded state forward instead of resetting it, and h3_ref_chain.py hands forward imgs[-tail_n:], which by this finding is the most degraded stretch of the hop. Every hop is seeded from the worst frames available to it.

It is global, not face-local. TEA2's background ratcheted more than the head (x1.21 vs x1.17). The face is where it becomes objectionable, not where it happens -- we are simply far better at reading skin than wood. So a correction can be global, but the measurement must still report a subject box, because that is where the acceptance threshold lives.

Their exposure anchoring was on and working: luma holds at 92 -> 90 across 44 seconds. The texture ratchet is independent of it. That matches the table -- coarse band roughly flat, mid climbing -- and it is why the existing tone work never touched this.

What got built

tools/texture_probe.py. Three Gaussian-difference bands, a subject box against a background control, and the within-hop slope as well as the per-hop step. It reads the hop cache's pre-correction FFV1 frames, or any video via --video, which is what makes it usable on someone else's rig. It prints mean |Laplacian| next to its own numbers, because "the head gained 34% mid-band and the Laplacian says 0.973" is a better argument against that metric than a paragraph is.

tools/check_texture.py drives it against a synthetic cache with a ratchet of known amplitude injected. This is not ceremony. §21's instrument shipped a confident wrong number for weeks because nothing had ever read it against a signal whose answer was known in advance, and this one caught two defects while being written: slope_pct reported percent-per-frame under a per-100-frame label -- a hop that doubled read as "+2.4%" -- and the first fixture's "mid-only" injection was a full-window difference of Gaussians whose tails landed squarely in the coarse band, so the test was measuring its own spectral hygiene rather than the probe's.

tools/hopcache.py now holds the cache reader and the chain segmentation, shared with tone_probe instead of copied. That segmentation is precisely what was wrong in §21; it must not exist in two places. latents.py lifts the NestedTensor shim out of h3_ref_chain.py so a tool can read a cached latent without importing ComfyUI -- the same reason plan.py and tone.py have no ComfyUI imports.

What is deliberately not built yet

The lever. _condition_pin_latent's pin_renorm matches one scalar sigma per latent component, and the pixel evidence says sigma and the damaged band move in opposite directions -- so a band-aware rescale is the obvious next move. But that is an argument about pixels, and the lever acts on latents. Whether the latent's band structure drifts the way the pixels' does is unmeasured, and texture_probe now prints exactly that (latent [0] sigma ... hi ...) from a cached hop.

Measure first. A 4-5 hop chain with cache_hops=on, probed before the restart that wipes temp/. Two hops cannot show this: the reporter's own numbers only separate at three.

Also found, by reading

_condition_pin_latent is applied to pin_latent = prev_sampled, which only the motion_context branch of _pin_continue consumes. The addguide_pixels fallback takes raw prev_imgs and gets no conditioning at all -- and a cache hit whose latent did not serialise lands there silently. AddGuide also re-encodes decoded pixels, which is the decode/re-encode round trip the reporter measured at 1.530, "much worse", on their own rig. A chain that quietly fell back has both levers dead and the worse hand-off. The log says which pin ran; it is worth reading before trusting any A/B.

Correction, 2026-09-01: it is a staircase, not a ramp

The section above says the climb is continuous with no step at the joins. That was wrong, and it was wrong in the way that matters most -- it is the claim that decides where a correction belongs.

It came from binning the reporter's master at 60 frames without knowing where their joins were. A step function sampled that way, with content noise on top, reads as a ramp if you want it to. The inference was under-determined and I did not say so.

The hop cache settles it, because there the boundaries are known. A 3 x 243f chain, 736x1280, overlap 22, Motion-Context pin, pin_renorm off, head box, mid band, with the regenerated overlap frames excluded:

hop 1   0.00985 0.00976 0.00963 0.00992 0.00981    last/first 0.996
hop 2   0.01050 0.01025 0.01029 0.01033 0.01053    last/first 1.003
hop 3   0.01058 0.01025 0.01044 0.01058 0.01076    last/first 1.018

join 1 -> 2   tail 0.01006 -> body start 0.01048   x1.042
join 2 -> 3   tail 0.01068 -> body start 0.01113   x1.042

Flat inside every hop. The same +4.2% at both joins. Those two frames are adjacent in scene time -- hop N+1's frame 22 continues from hop N's last -- so it is a genuine discontinuity and not a gap the scene moved through.

Re-reading the reporter's bins with this in hand, theirs is a staircase too: 1.57 1.55 1.56 1.56 1.57 | 1.60 1.68 1.66 1.61 1.64 | 1.71 1.71 1.72 1.77 | 1.85 1.85 1.93 -- four plateaus at ~1.56, ~1.64, ~1.73, ~1.88, stepping +5%, +6%, +9%, on a chain they told us was four hops. Both rigs agree. I had the right data and read it wrong.

This is better news than the original reading. "Self-conditioning drift inside the generation" could only ever be damped; a step injected at the hand-off can be removed at the hand-off, and the hand-off copies are conditioning-only.

And the latent measurement, which was the point

From the same cache, per hop: component [0] sigma 1.0414 -> 1.0376 -> 1.0289, its high band 0.3794 -> 0.3811 -> 0.3809.

Sigma falls 1.2% while the pixel mid band climbs 8%. The high-band fraction -- hi/sigma -- goes 0.3643 -> 0.3673 -> 0.3702, up 1.6% and monotone. So the latent does carry the tilt, and total sigma does not see it.

pin_renorm=on would have multiplied this pin by 1.0414/1.0289 = x1.012, scaling every band up uniformly, on a latent whose high band was already 1.6% too hot. On this chain the shipped lever pushes the wrong way. That is not a small correction to it; it is the wrong statistic, and Phase 2a's band-matched rescale is now evidenced rather than assumed.

One caveat kept in view: 1.6% in the latent against 8% in pixels. The VAE decode is nonlinear, so the two are not expected to be proportional, but the gap is large enough that the lever's gain will have to be fitted against measured output rather than derived from the latent ratio.

Two probe defects the real data exposed

Cached latents did not load at all. torch.load has to import comfy.nested_tensor to rebuild the object; without the ComfyUI root on sys.path, store._get_latent caught the ModuleNotFoundError and the probe printed "none cached for this hop" -- reporting a path problem as an absent latent. hopcache.enable_latent_reads() appends the root and nothing else; the module imports only torch when pickle reaches for it, so it is safe to run beside a queued render.

Band energy was not exposure-normalised. The probe's own docstring claimed band-pass output "does not care about the local mean", which is true of an offset and false of a scale: brighten a frame 5% and every band grows with it. The 3-hop chain's luma rose 4.7%, so whole-frame mid read x1.084 when the texture part was n1.035. Both columns are printed now. The head box was unaffected either way -- the brightening was in the background -- which is exactly the kind of thing a single whole-frame number cannot tell you.

27. The band lever, and why the old one could never have worked (2026-09-01)

Built after §26's correction, on the finding that the ratchet is a step at the join: +4.2% mid-band, twice, identically, on a 3-hop chain. Two identical steps is already a model -- constant multiplicative step per join, geometric in hop count. It predicts hop 3 at 1.042^2 = 1.086 against 1.079 measured. So the shape did not need a 4-5 hop run to pin down, which matters: those runs are expensive enough that the user does not do them.

pin_renorm is now ["off", "sigma", "band"]. "on" maps to "sigma", so pre-0.5 workflows keep their behaviour, and the combo keeps its widget slot -- adding options is safe, adding widgets is not.

The old lever is a no-op, provably

The statistic that drifts is the high-band fraction, hi_sigma / sigma. A fraction is invariant under uniform rescaling, and a uniform rescale is the entirety of what sigma mode does. Driven end to end through _condition_pin_latent with a 12.74% band drift planted in hop 2:

mode=off     ratio after 0.3526 (anchor 0.3128)  err +12.74%
mode=sigma   ratio after 0.3526 (anchor 0.3128)  err +12.74%   x0.9651 applied
mode=band    ratio after 0.3127 (anchor 0.3128)  err  -0.04%   hi x0.8339

sigma applied a real scale factor and moved the drift by nothing at all. This is stronger than §26's "corrects the wrong way": there is no gain, no strength knob and no anchor choice that makes a scale-invariant statistic respond to a scale. The lever was mis-specified, not mis-tuned. It is kept only for the workflows that saved it.

The fixed point that nearly shipped

match_band first computed k = target * sigma / hi_sigma. That is wrong in a way that hides: scaling the high band changes the sigma it is a fraction of, so the target moves while you apply it. It landed at 0.3331 against a 0.3168 target -- 5% short, in the right direction, which is the worst possible signature because it looks like it works.

Now it solves the orthogonal fixed point in closed form, k = r*L / (H*sqrt(1-r^2)), then refines two or three passes against the statistic as actually measured, because a difference of Gaussians is not an exact projection. Lands at 0.3167 against 0.3168.

The fixture was also wrong, and would have hidden it

The first test used torch.randn for the latent. White noise has a high-band fraction of 0.966 -- pinned against its ceiling of 1.0, where lifting the high band moves the statistic by 0.6% and the clamp does all the "correcting". Every assertion about the lever would have been measuring the clamp. Real latents sit at 0.3643, so the fixture is now built to land near there and an assertion holds it in that regime.

The safety property is asserted as "the entire change lies along the high band" (cosine with hi > 0.99), not as "the low band is unchanged" -- re-splitting the result does not hand back the same lo, because the split is not a projection. The first version asserted the false one and failed correctly.

One cache key narrowed

pin_cond was in every hop's key including hop 1, which has no pin -- _pin_mech_for returns "none" at index 0 and the conditioning branch is elif i > 0. So flipping a lever discarded a byte-identical cached hop 1 and re-rendered it. That is a third of the cost of every lever A/B, on the one hop that provably could not have changed. Now keyed only from hop 2.

Still unknown

The latent's band fraction moved 1.6% across the chain while the picture's mid band moved 8%. The decode is nonlinear so they are not expected to be proportional, but a full match to hop 1's fraction may therefore under-correct the picture. That is one A/B to find out, and it is readable off a 3-hop run: texture_probe reports each join separately, so two joins is two data points. If band shrinks the +4.2% step but does not close it, the next move is a gain above 1.0, fitted -- not guessed.

28. A music bed that does not bury the dialogue (2026-09-01)

(Numbered 28 because 24-25 are on llm-plan-writer and 26-27 on texture-ratchet, both unmerged. Section numbers are cheap; renumbering a merged history is not.)

A user asked for a soundtrack over the whole chain -- not an audio reference, which H3 already takes as a voice, but a track laid under the finished thing.

The first decision was where it goes, and it decided everything else. H3 writes its own audio per hop and _xfade_audio joins it at each seam, so the bed is applied ONCE, after the last hop, immediately before master_audio is built. It is therefore downstream of every latent, every pin and every cache key: it cannot move a generated frame or sample, only decide what is laid over them. The same property that made the texture work safe -- correcting something nothing renders from -- is what makes this safe, for the opposite reason. It also means a cached chain can be re-mixed at a new level for the price of the mix alone.

Three things in music.py are there because the obvious version is wrong:

Resample explicitly. A 48 kHz track dropped into a 44.1 kHz master plays 9% fast and a semitone sharp. That reads as "the model generated bad music", not as a bug in the node, so it would have been reported as anything but what it was.

Crossfade the loop wrap. Butt-joining a loop leaves a step discontinuity, i.e. a click -- and a click on a fixed period is the most audible artifact available, worse than the seam it came from. Equal-power cos/sin, the same law _xfade_audio already uses; two different fade shapes in one output is an argument waiting to happen.

Duck against the 95th percentile, not the peak. A single shouted word would otherwise set the scale and leave ordinary dialogue barely ducking at all -- which is the common case in the podcast clip this was asked for. Fast attack, slow release: the reverse lets the first syllable of every line collide with the music, and the first syllable is the one a listener needs to follow a sentence.

The envelope runs at a 1 kHz control rate. A one-pole attack/release filter is sequential, so at 44.1 kHz a 40 s master is 1.8M Python iterations -- about a minute of dead time on a node whose whole job took ten. At 1 kHz it is 40,000, and 1 ms resolution is far finer than the 10-400 ms attacks that matter.

The peak guard trims the whole mix rather than only the bed, and says so in info. Ducking the bed further to fit would change the balance the user set, by an amount they cannot predict, without telling them.

tools/check_music.py is 31 assertions on synthetic material, because every defect here is inaudible in a still and invisible in a frame count. The one that matters is the last: with nothing wired, apply() returns the master object itself. That is the whole claim that the feature is opt-in.

Four widgets, appended. widgets_values is positional, so they go at the bottom of optional and the two shipped workflows grew four values. The AUDIO socket costs no widget slot -- check_workflows.py already knew that, and caught the count mismatch before the workflows were updated.

29. The writer stays warm until the render asks for the card (2026-09-01, ALPHA)

(29 because 26-27 are on texture-ratchet and 28 on soundtrack, both unmerged. Numbers are cheap; renumbering a merged history is not.)

unload_after handed the VRAM back the moment a plan was written. That was right when there was nowhere else to put the eviction, and wrong for the way the feature is actually used: nobody writes one plan. They write one, read it, change the brief and write another -- and every one of those paid a full model load, tens of seconds on a 27B, to free memory that nothing was waiting for.

The card is contended at exactly one moment, and it is a moment we can see coming. So keep_warm is the default now and the eviction moved to the top of run(), where the render is about to need the memory. unload_on_run is what makes that safe rather than merely convenient; keep_warm off restores the old behaviour for a machine too tight to hold the writer at all.

free_for_render blocks, and that is correct. The rule at the top of llm.py -- never block -- is about aiohttp handlers, which run on ComfyUI's event loop where a stall freezes the entire canvas. run() is the execution worker thread, nothing waits on it but the render, and the render is what the VRAM is being freed FOR. The docstring at the top now names this as the single exception, because otherwise the next reader "fixes" it.

It costs nothing when it does nothing, which is the majority of renders. The first gate is configured(): a filesystem check for a settings file that has never been written. No socket, no DNS, no 4 s timeout against a port with nothing behind it. The settle is skipped whenever the eviction found nothing resident, and shares_this_gpu still refuses a writer on another machine before any of it.

The settle is a guess about someone else's hardware. The unload endpoint returns when the server drops its reference, not when the driver has released the allocation, and on a slower card those are not the same instant. Default 5 s, settable, capped at 60 -- a pause long enough to look like a hang is worse than an OOM you can read -- and announced in the console, because it lands right after the queue button, the moment a user is most primed to read a stall as a crash.

check_planner.py proves the quiet paths without waiting for any of them: free_for_render takes a settle_sleep callable, so a test can assert that nothing slept. It also redirects _conn_path at a temp file first -- a checker that overwrites the user's real writer settings as a side effect of passing is not one anybody should run.

Suggest, don't set. 2450d96 wrote shot_plan and ref_plan the moment a draft converged. A plan silently rewritten under you is worse than no plan, so the bar now holds the JSON until Accept. Discard leaves the cards as they were. The route is unchanged; only the last inch of the panel moved.

asyncio.run cannot nest. ComfyUI's execute path is async, so run() is already inside a running loop when it calls free_for_render. asyncio.run (unload_all(...)) then raised RuntimeError and left the coroutine un-awaited -- keep_warm + Queue printed that, and the 27B stayed resident. _run_coro uses a side thread with its own loop; the function is still blocking, just not on the UI loop. Proven in check_planner.py by calling free_for_render from inside asyncio.run.

The rail is the scene. Write plan used to POST only {brief, hops} and then list every file in h3_refs, so a user who had already put two pictures in the boxes got a register full of files they never chose and an empty subject card -- the model never saw the stills. The bar now sends the filled rows; those tags and filenames are locked; the stills ride the first user turn as vision parts (768 px JPEG, executor, not a widget). A text-only model that 400s on image_url falls back to filenames and says so. Missing subjects.{n}.name/locked is an error for the writer, so the repair loop fills the box instead of Accept writing an empty one.

qwen 3.8-27b then wrote a correct script and kept the rail's files, and still emitted "subjects": {} on all three attempts -- structured output treats an empty object as valid, and "rewrite the whole plan" never added the block. A subjects-only repair overlays the last register; if that still comes back empty, name/locked are filled from each ref's desc so the draft is not thrown away. The panel shows a partial draft on give-up.

The next live run tagged the rows correctly, then a repair that re-emitted the refs without desc and with subjects: {} wiped the describe-this-photo and current-standing-state boxes. Empty values no longer win a merge. Pinned writes now require desc on every ref and name/locked/context on every subject -- those three fields are the point of attaching the stills, not optional flavour.

30. Which nine seconds? (2026-09-01)

The soundtrack shipped and worked, and using it for ten minutes found the hole. The track was 173 seconds, the chain was 9.4, and music_fit=loop takes the first 9.4 seconds -- which on a mastered track is the intro. There was no way to say which nine seconds.

The same hole was on the other two media inputs. On one of them it is not a convenience issue at all. MiniMaxH3ReferenceToVideo passes the whole voice file to _encode_ref_audio with no cap, and every latent frame that produces is a token the DiT attends over on every step of every hop. An untrimmed three-minute voice reference is a large, silent, permanent tax that nothing in the UI ever mentioned. The reference clip was truncated to the hop length, but only from frame 0, so you could not point at the motion you actually wanted.

Peaks are computed on the server. The first design decoded the file in the browser with decodeAudioData. For this track that is roughly 66 MB of Float32 held in the tab, per control, to draw a picture 240 pixels wide. PromptMasterLD has four separate trim controls and not one decodeAudioData between them -- it sends 240 numbers. So do we. The decode runs in an executor, because these handlers share ComfyUI's event loop and 1.68 seconds on it stops the canvas, the queue and the progress bar together.

Bucket by max, not mean. A mean flattens transients into a smooth sausage, and transients are the only landmarks you can trim against. The whole reason to look at the picture is to find the downbeat.

seconds comes from the decoded sample count. MP3 Xing/LAME headers routinely report double the real duration, and a duration that lies makes every position on the bar lie with it. We already decode, so the honest number is free. Measured on the file that started this: 173.49 s, matching the samples.

end == 0 means "to the end of the file", and media.clip_window is the only definition of what a window is. Four readers have to agree -- the voice, the clip, the soundtrack and the peaks route -- and four copies of that arithmetic would eventually disagree by a rounding rule. It can never return an empty span: reversed, negative, past-the-end and shorter-than-50 ms all fall back to the whole file. A trim that did not take is a puzzle; an empty tensor is a crash from inside the model naming neither the file nor the widget.

Per-reference megapixels, and where they are not. H3 scales each reference down from its native size and each becomes latent_h * latent_w entries in the DiT payload, so a location plate costing what a face costs is waste. That is a token dial and it is now a field in ref_plan. It is deliberately not offered on the first frame: MiniMaxH3AddGuide does _resize(image, width, height, "center"), so whatever you feed it becomes exactly the canvas, and the control would have been wired to nothing. The control the first frame actually lacks is a crop box -- a 9:16 source on a 16:9 canvas silently loses both sides -- and that is still open.

The hop cache needed no change, which is worth recording because it looked like it would. chain_salt digests the loaded tensors, not the filenames or the settings, so a trimmed voice is already a different key and a downsized reference is already a different key. Keying on pixels rather than on parameters paid for itself here without anyone planning it.

tools/check_waveform.py: 38 assertions, green first run. widgets_values went 39 -> 45; check_workflows.py caught it, which is the third time that checker has earned its place.

TASK 2, verified 2026-09-02. Header-lie, soundtrack trim, and per-ref mp were signed off in the GUI. Voice trim reaches the encoder (hop-cache miss); male timbre will not override a woman in frame at 8-step turbo. Null check: every window 0/0, empty voice_file / soundtrack_file, A's graph vs efd6a3e — hop 1 and hop 2 FFV1 frames and .npy audio bit-identical (contact_sheet_00039 vs 00043; pin σ 0.9578/0.4434). Hop keys differ because this branch added voice_on; that is a key-field change, not a generate change. Old workflows: widget names from 0.4.5 (34) and efd6a3e (39) are a prefix of this branch (45); Starter.json from both revs maps seed / steps / shot_plan onto the same widgets. user/default/workflows still use the legacy H3RefChain id, on purpose.

31. The lints that cried wolf, and the field the writer ate (2026-09-02)

A day of GUI renders against two writer models. Nothing in the renderer was wrong. Four things in the plumbing around it were, and three of them had been telling the author to fix work that was already correct.

A Write plan silently deleted every reference cap. railRefs() and _pinned_refs() both built their five fields and dropped mp; the model cannot author one (it is not in the prompt's valid-field list); and Accept overwrites the register wholesale. So the caps survived exactly until the next write. chain_00047 ran three plates at 0.54 MP -- 1.58 MP of stills against a 0.72 MP canvas -- and came back coherent. One rewrite later the same three were at native size, 3.23 MP against the same canvas, and the render opened on the kitchen plate reproduced almost verbatim and warped the subject in. The ratio tracked the result across four renders: 2.2x coherent, 3.4x coherent picture with gibberish audio, 4.5x cooked. load_image's own docstring had said why for weeks -- "a location plate costing as much as a face is waste" -- and nothing enforced it because nothing kept it.

The dial was also invisible. REF_MP offers 0.3/0.5/0.7/1.0/1.5/2.0, select assigns a value matching no option, and a blank control is labelled full. A row capped at 0.54 read as uncapped while it was working. Two hours were spent tuning megapixels that had already been erased.

The schema never required the ref_plan. properties listed both documents and there was no top-level required, so {"shot_plan": ...} alone was valid. qwen3.8 volunteered both and hid it for the whole life of the feature. gemma4-26b emitted only the shot plan, on every attempt: the register stayed empty, _remap_pinned_tags bailed on the falsy ref_text before it could restore the rail's names, and each repair turn was told its beats cited undeclared tags -- so it rewrote the beats it had already got right and never emitted the document that was missing. Three attempts, no convergence. With the requirement in place: two attempts, correct register, zero warnings.

check_coherence tested "framing is named" where it meant "framing changed". Its own docstring says a framing CHANGE fights a continuous join with a held camera. The test never compared against the previous shot, and models restate the framing on every shot because the axis describes the shot rather than a transition -- so medium/medium/medium tripped it on every hop after the first while the framing never moved. Both writers hit it on essentially every plan. chain_00052 carried the banner and seamed at -0.31/255, one of the cleanest joins measured here. That was the evidence, and it read as a curiosity for hours before it read as a bug.

check_place_handoff fired on chains that never leave. The abandonment half is about a destination the film moves to and then holds with nothing. It tested only whether a place plate rides the last shot, so a two-hop kitchen scene that drops the plate after hop 1 was called a defect -- when that is the pin-only recipe the renderer is built for. Distinct places cited in beats is the test now; under two, the film never leaves.

What the renders actually taught, separately from the bugs. A continuation hop carries a small motion, not a relocation. Three pin configurations -- plates on hop 2, plates off hop 2 (0 identity stills), and overlap raised from 0.9 s to 1.6 s -- all produced the same hard cut at frame 192 for a beat reading "gets off the counter and stands to face the window", while a beat reading "stays seated, shifting her weight" continued cleanly at -0.31/255. The pin length is not the lever; what the beat asks of the first frame is.

overlap moved out of chain_salt into the per-hop key from hop 2, for the reason pin_mech was never in it: the trim and the pin are both hop-2+ work, so hop 1's pixels cannot depend on it, and keying it chain-wide made every overlap A/B re-render a byte-identical hop 1.

The writer was never told the hop length. The prompt ships a five-row length table and instructs the model to ask when it has not been told, which a button cannot answer. The node has known the duration all along and nothing carried it, so beats were sized to a guess -- 75 words into 8 s hops, one spoken line where the row allows two, 26.7% voiced. The panel sends duration now and the band is named outright rather than left as a table to look up. beat_table() parses it out of SYSTEM_PROMPT.md rather than restating it, the same reason schema() reads SCHEMA.json.

Still open. A desc can be confidently wrong about its own photograph -- gemma4-26b called a white ribbed crop top "a dark top" and a daylit wooden kitchen "a dark kitchen interior with blue light and tiled surfaces", and no lint can check prose against a picture. qwen3.8 did not make that class of error on the same three plates.

32. A silent pin does not buy you a silent opening (2026-09-02)

Hop 2 opened on invented speech -- a burst of nothing-words over the walk, before the line it was actually given. The chain was clean everywhere else and the seed was fixed, so the first guesses were all mechanical, and all wrong.

Ruled out, in order. The LoRA: exonerated by the user across a run of low-res A/Bs. pin_renorm=band: it skips the audio component outright -- "an audio component has no bands; leaving it alone is correct, not a fallback" -- so it never touched the track. A mid-utterance handover: the hypothesis was that one second of audio context caught hop 1 mid-word and hop 2 finished it. Hop 1 ends silent. There was no word to finish.

What was left is the beat. SPEECH_MIN_SHARE's comment had already written the mechanism down for the whole-hop case -- "the model fills them itself, as fragments or as invented dialogue" -- and rules 3 and 6 of SYSTEM_PROMPT both say to give silence a sound. Both are stated per hop. Hop 2 was walk-then-talk: it had dialogue, so rule 6 did not reach it, and its opening seconds carried a picture with no audio assigned. Rule 5 covers the join -- arrive silent before the previous shot ends -- and the user had done exactly that. Ending hop 1 quiet gets you a quiet pin. It does not write hop 2's first two seconds.

So the hole was granularity: every rule about unassigned audio was whole-hop, and the failure was sub-hop. Rule 3 now says so in both prompt documents, the checklist gained a line, build_user_turn names the case, and validate warns when more than LEAD_IN_MAX_WORDS of action run before the first spoken line with no sound named anywhere in the beat. spoken_spans() is split out of count_beat because where the first line starts turned out to be its own question.

The user's own fix on hop 1 was the same shape, arrived at independently -- "she silent smiles at the camera and waves, after a pause she says". Worth noting which half did the work: check_templates bans "silent" and "silence" in a beat, because at cfg 1.0 with no negative branch nothing subtracts. The smile and the wave are what filled the frames.

Still open. SPEECH_WPS = 2.5 rests on one measurement (chain_00059 hop 1, six words, 1.8 s voiced). Hops 2 and 3 of chain_00060 are confirmed-good dialogue and would make a better basis. LEAD_IN_MAX_WORDS = 8 is reasoned from the length table, not measured at all.

33. The word rate is an English number (2026-09-02)

The first live write after section 32 was the proof it wanted: asked for a three-hop Korean vlog, the writer opened every hop with a named sound before the line -- "The sound of heavy footsteps and distant city traffic fills the air before she speaks" -- and the lead-in lint stayed quiet on all three, correctly.

The same run broke something else. SPEECH_WPS counts whitespace tokens, which is only a speech rate in a script that puts spaces between words. The Korean line was 8 tokens and 27 syllables: the lint called it 3.2 s against a real 4-5 s, warned on all three hops when two were fine, and -- the harmful half -- told the author to write "roughly 25 words", which in Hangul is about 85 syllables and three times the hop it has to fit in.

speech_seconds() now counts CJK by syllable at SPEECH_SPS = 5.5 and everything else by word, adding the two so a mixed beat is estimated correctly rather than in whichever script dominates. Punctuation stranded by the split stops counting as a spoken word, which was quietly buying every CJK line most of a second. The shortfall warning and build_user_turn both name the target in the unit the line is written in.

Nothing here is measured on this model. 5.5 syllables a second is a reference figure for conversational Korean, Japanese and Mandarin alike, and SPEECH_WPS still rests on the one English measurement in section 32. Both are honest starting points and neither is evidence.

34. The dropdown was showing a model nobody had chosen (2026-09-02)

An Arch user, one day after 1.0.0: the node "isn't auto loading the model even if it sees it, jit is enabled"; selecting one and pressing WRITE "says no model selected even though it is"; and "i can eject the model which is odd".

Three symptoms, one empty string, and nothing to do with Linux.

CONN["model"] starts as "". The panel builds the dropdown and marks an option selected only when m.id === conn.model, which never matches "", so no option was selected and the browser fell back to displaying option[0]. Falling back is not choosing: no change event fires, and change was the only thing wired to save. The panel therefore displayed a model the server did not have.

Everything downstream followed from that one value:

• _plan refuses on if not conn.get("model") with the exact words the user quoted back.
• Nothing is ever asked of the server, so JIT has nothing to load. "Sees it" is /v1/models, which lists what is installed, not what is resident -- the distinction section 29 already had to make once.
• Free VRAM still worked, because unload_all() ignores the configured model by design (section 29 again: the button exists for when JIT loaded something other than what was asked). The user read that as odd. It was the clue: the fault was in the saved value, not the server.

It is guaranteed for the ordinary case, not a corner. models() sorts loaded models first, so the model you have loaded is option[0] -- and clicking the entry already on screen fires nothing. Anyone running one model hits it on every fresh install. It escaped a release only because the machine it was developed on has had a populated htc_llm.json since 0.2.

loadConn() now adopts what is on screen when the stored value is empty, and only then. The comment guarding this spot was right that option[0] must not overwrite a working setting; it had over-corrected into never writing one.

And a second hole, found underneath it. save_conn() wrote htc_llm.json into the pack directory, swallowed OSError with a print, and returned as though it had saved -- the route answered ok: true. A read-only or root-owned custom_nodes, which is how a system-wide ComfyUI or any container image is laid out, produced the identical "no model is selected" from a completely different cause, with the only evidence in a console nobody was reading. It now returns saved and save_error, and the panel says "set for this session, but not written to disk" -- which is true, because CONN is a live module global and the setting really does work until a restart. Whether that file belongs in the pack directory at all is still open; ComfyUI's user/ survives a reinstall and this does not.

The lesson is the older one, in a new place: a control that displays a value it has not committed is worse than one that displays nothing. Section 31 caught a lint that cried wolf; this is a dropdown that cried yes.

35. The rail already had the answer (2026-09-02)

The Arch reporter from section 34, writing their first plan once the panel worked:

attempt 1: subject 1 is missing name, locked, context;
           @hero_face must keep file 'gibsonlethal.webp', not
           'hero_face.webp'; @hero_face needs desc
attempt 2: subject 1 is missing name, locked, context;
           @hero_face needs desc; @hero_outfit needs desc
repair turn: desc and subject prose are required by the schema
wrote a 3-hop plan in 3 attempt(s)

It converged, one attempt from failing. The interesting line is the middle one on attempt 1, and not for the reason it looks like.

_only_register_prose_gaps fires the tightened-schema repair -- the one that removes the empty path from the grammar, because section 31 established that while "subjects": {} is legal it is also the cheapest legal completion and no amount of repair prose outvotes it. That gate requires EVERY error to be a prose gap. A file mismatch is not one. So attempt 1 got the weak generic "change only what the errors name" turn, attempt 2 produced the same subject error again, and only then -- with the file error gone -- did the mechanism that actually works get to run.

One misnamed file cost two attempts: its own, and the round it kept the real repair from firing in.

It was never the model's field. The rail pins a tag to a picture, and validate is holding the correct filename in by_tag at the moment it rejects the plan for not having it. This is the argument already written down for mp in _restore_rail_only -- spend an attempt on a rejection the rail already had the answer to -- and file is a stronger case than mp ever was, because the model is not even guessing: it is renaming a real file to match the tag it was given. gibsonlethal.webp becomes hero_face.webp. Tidy, and wrong.

_restore_pinned_files now puts it back before validate sees it, keyed on a real tag match, and prints what it changed.

Why it is not simply another RAIL_ONLY_FIELD. That loop drops a field the rail cannot supply, which is exactly right for mp -- an invented megapixel cap is never wanted -- and destructive for file. On a brief-only write the rail is empty and the filename the model read off the folder listing is the only one there. The repair has to touch pinned rows and nothing else, which is the whole difference between restoring a field and owning one.

Checked against the reported errors verbatim: three errors give the weak turn, the same three minus the filename give the tightened one. The plan that took three attempts should now take two, and a rail whose filenames do not resemble their tags -- which is most rails, since photographs arrive named by the camera or the download -- stops being a hazard at all.

The older lesson underneath: every field the node can determine and chooses to reject instead is an attempt spent, and attempts are a budget of three.

36. A generator that fails quietly is worse than one that dies (2026-09-02)

A ComfyUI dependency install, run to satisfy some other pack's requirements, uninstalled Pillow and did not finish putting it back. About 180 of the 211 files in its manifest were gone, __init__.py and Image.py among them, so import PIL resolved to an empty namespace package. Four checks in the suite died on it, which is the suite working.

What the suite did not catch is what gen_schema.py did next. It reads the duration table off the node, and that import needs comfy.model_management, which needs PIL. The import raised, and this was the handler:

except Exception:                                # pragma: no cover
    durations, frames = [], {}

So a routine regeneration wrote a SCHEMA.json whose duration enum was [] and whose x-duration-frames was {}. The schema that exists to constrain the writer's duration field stopped constraining it, in a file that is committed, published, and fed to the model as a grammar. Nothing downstream complains about an empty enum — that is precisely what an empty enum means.

It was caught by git status, run for an unrelated reason. That is not a control. Ten minutes either way and it ships.

build() now raises, with the cause and the instruction to fix the environment rather than the file, and main() refuses to emit a schema with no duration table at all — belt and braces, because the enum could empty for a reason nobody has thought of yet. Verified by reproducing the original condition rather than trusting the reasoning: a PIL package on PYTHONPATH that raises ImportError on import, then both entry points checked. Both exit 1 with a readable message; the file's hash does not move.

A correction worth recording, because the first diagnosis was wrong. The note written at the time blamed --check for rewriting the file. It does not; it only reads and compares, and always did. The corrupt write came from gen_schema.py with no arguments, run by hand in a diagnostic loop. The distinction matters: the fault was never in the comparison path, it was in build() returning a plausible-looking empty answer to a question it could not answer. Fixing --check would have fixed nothing.

The general shape, and section 34's lesson one level down: a control that displays a value it has not committed is bad, and a generator that emits a value it could not compute is the same bug wearing a different hat. Neither one fails; both produce something that looks like an answer.

37. Two ways to hand a model a photograph and not say why (2026-09-03)

A user: "pinning outfit to anything but first hop throws the actual image in." The obvious suspect was the image ordering -- something prepending the still ahead of the continuity frame. It was not. _attach_pin_to_qwen builds [last_frame] + refs, and still_shift moves the text ordinals to match. The pictures arrive in the right order with the right numbers.

What was wrong was that nothing said what the picture was for.

retention_analysis: is the block that does that -- <Picture 2> (denim apron over a grey tee): the garment and its cut carry over. It is produced by subject_prose, and subject_prose is gated on i == 0. That gate is correct for its other half: subject_definitions: introduces <Subject N>, and a subject token first introduced on hop 4 has no antecedent in its own encode. But retention has no such problem, and it went out with the gate. A still scheduled onto hop 3 therefore reached the encoder as ref_image_2 with no retention line, no desc, and no subject entry. If it also had no subject number, id_ords came back empty, _identity_lock returned "", and the photograph was never named anywhere in the prompt at all.

The second defect is worse because it is confidently wrong rather than silent. _identity_lock decides who is a person by subject is not None and has never read retention. The canonical outfit reference in the README carries subject: 1 and retention: partially_copy -- it is a garment belonging to person 1, not a photograph of their face. So hop 3 opened with "<Picture 2> is the only identity. That face, bone structure, and hairstyle match the photograph exactly", asserted about an apron. And because lock was then non-empty, the closer became "Faces and hair follow the identity photographs. Clothing follows whatever is already on them in the live frame" -- which contradicts the wardrobe plate riding that very hop. At cfg 1.0 there is no negative branch, so both instructions are additive and the encoder gets each at full weight.

Three changes. retention_prose splits out of subject_prose and takes an explicit ordinal map, because on a continuation hop the live frame is <Picture 1> and every still shifts up -- deriving the map a second time is exactly the drift the hop_ords comment warns about. The identity filter requires fully_preserved, which refs.py already defaults subject-bearing refs to, so ordinary face plates are untouched and only garment and setting plates stop being called people. And the closer points clothing at the plate when one is actually present.

Hop 1 escaped all of this because subject_prose runs there, which is precisely why the report said "anything but the first hop".

The same shape turned up a third time while writing this. The author's reference clip has always gone in as <Video 1> with nothing naming it -- _live_cite covers the pinned tail, which is a different video. Same failure mode, same fix: a description field, and a note printed when a clip is wired without one. It is gated on the field being filled and asserted as such, so no existing workflow has its prompt quietly rewritten by upgrading.

The lesson is not about pinning. It is that an uncited reference is not neutral. A Ref2VA model handed a photograph and no reason for it will find a reason, and the reason it finds is "render this".

38. Fifteen tuples, of which the formula gets nine (2026-09-03)

The output canvas was a hand-authored table: five resolution labels by three aspects. Adding eight more aspects would have made it fifty-five, so it became a function -- mirroring core's adapt_canvas, nearest 32 per axis, under the 768*1344 cap.

The interesting part was checking it against what it replaced. I predicted the formula would reproduce thirteen of the fifteen old tuples and wrote that into the plan. It reproduces nine. Two cells I had done in my head were simply wrong -- sqrt(200000/1.7778) is 335.4, which rounds to ten 32-blocks and not eleven -- and I had also forgotten that every landscape divergence has a portrait twin.

Six diverge, all in the 16:9/9:16 column, and the pattern says why: that column was hand-tuned for ratio fidelity rather than derived from area. 1280x736 is 1.739:1, closer to 16:9 than the 1344x736 (1.826:1) the area allows. So the old table was not sloppy; it was optimising something else.

They are pinned rather than recomputed, because width and height are in chain_salt: resolving them differently would re-render every chain a 1.0.x user has on disk and change the pixels of a graph they already signed off. check_canvas.py asserts both halves -- that the six stay pinned, and that the other nine still need no pin. A compat shim nobody re-checks becomes a bug the moment the thing it was shimming moves.

I also tried a small grid search to beat per-axis rounding on ratio fidelity. Weighting ratio twice as heavily as area took the worst ratio error from 3.3% to 2.1% and pushed the worst area error from 2.7% to 3.8%, and produced identical sizes for 16:9 at every rung. Not worth diverging from core's arithmetic for. Matching adapt_canvas exactly is worth more than a point of ratio error on one cell, because the two agreeing is a property somebody can rely on.

Separately: media._mp_cap_size rounded reference stills to a multiple of 16 on the stated grounds that "that is H3's canvas grid". It is not. CANVAS_MULTIPLE is 32; 16 is the VAE's spatial factor, a different number that happens to divide it. Core re-snaps every reference to 32 on the way in, so nothing wrong ever reached the model -- the only casualty was that the size printed in the log was not the size the encoder saw, which is the one job that rounding has. check_waveform.py asserted the wrong number and had been passing on it since it was written.

39. Four thousand lines with nothing in front of them (2026-09-03)

There is no Node in this environment and no build step in this pack, so js/ had no check of any kind between an edit and a browser. That matters more than it sounds: the browser reports a bad import as a node with no editor, which looks exactly like the pack failing to load, and the console line is one console.warn among ComfyUI's own.

tools/check_ui.py is not a parser and does not try to be. It checks four things that have gone wrong or could go wrong silently: delimiters balance per file; every named import resolves to a real export in the file it names; every var(--h3-*) the stylesheet reads is declared in it; and no rule targets a class the JS never sets.

It found three things on its first run, before it had checked any new code. --h3-line was read in two rules and declared nowhere, so the trim bar's and the draft list's borders had been resolving to nothing. --h3-fg fell back to a literal #fff that no longer matched the palette. And two classes had rules but no setter -- .h3e-drag-over, left behind when the drop target was renamed .h3e-drop, and .h3e-card.h3e-dragging { opacity: .45 }, which is feedback the stylesheet was clearly written for and the drag reorder was never wired to. The first is deleted; the second is now wired.

Its own first run also caught a bug in itself, which is the honest way to calibrate one of these: the import scan ran against the string-stripped source, and the module specifier of an import is a string literal, so it found zero imports and reported success. The "something was actually imported" assertion exists because of that, and it is the more valuable line -- a checker that silently checks nothing is the failure mode every checker has.

40. The range that only had one end (2026-09-03)

render_through has stopped a chain after N hops since 0.4. There has never been a way to start at one, so re-rendering shot 5 of an eight-shot chain meant re-rendering shots 1 through 4 first, or accepting a chain that began at 5 with nothing before it.

The obvious implementation is to seed prev_imgs, prev_audio, prev_sampled and prev_key from the hop store before the loop starts. HopStore.get already returns all four, so it is maybe fifteen lines.

It is the wrong fifteen lines. The cache-hit branch inside the loop already carries exactly those four forward, and a second implementation is a second thing to get subtly wrong -- the sampler latent especially, which is what decides whether the next hop joins by Motion-Context or falls back to the weaker AddGuide pin. Getting that wrong produces a chain that renders fine and joins badly, which is the hardest class of bug to attribute.

So render_from truncates nothing. The leading hops run through the loop like any other hop and are simply required to hit the cache; a miss names the hop and says why it might be gone. One code path carries continuity, and it is the one that was already carrying it.

Two things fell out of writing the guards. Every misconfiguration is refused before the master tensor is allocated, which on an 8x15s plan is ~31 GB -- the first draft checked hop_store is None, which meant the check sat after the allocation, so a typo cost 31 GB before being told it was a typo. And the inverted-range check has to run against the original render_through, because n has already been truncated to it by then: testing start_at > n first reported "past the end of the plan" for from=5, through=2 and then rendered the whole thing.

The cache change shipped alongside is the one that will be felt more. chain_salt digested every wired reference chain-wide, so swapping the file behind @outfit moved hop 1's key even when @outfit rides only hop 5 -- and the key is chained, so that re-rendered everything. References are keyed per hop now, from base_images, which is the right set on both paths: this hop's scheduled stills when there is a ref plan, every wired reference when there is not, and the pin frame it excludes is already covered by prev_key.

And the nine-reference ceiling turns out to be per encode, not per plan, while the check counted the whole rail. Twelve references at three per shot across four shots was refused against a limit no shot came near.

41. Asking the OS who we are (2026-09-03)

1.0.1 came back Flagged from the Comfy registry with one finding, down from 1.0.0's three: the .comfyignore that stopped shipping tools/ cleared the subprocess.run and importlib hits, which is the first hard evidence that the exclusion is honoured inside the published zip.

What is left is python_network_operations, matching the literal string aiohttp.ClientSession four times in llm.py. 0.4.5 is still Active because that file had no HTTP client at all until 1.0.0 -- the WRITE panel brought one. So this is new code meeting an old rule, not a scanner that moved.

That finding cannot be coded away. The rule has no taint analysis and never looks at a destination, DEFAULT_BASE is 127.0.0.1:1234, shares_this_gpu refuses to send an unload anywhere but this machine, and every alternative client -- requests, httpx, urllib -- sits in the same rule family. Rewriting to dodge a string match would be worse code in exchange for nothing.

A user's tip is what made this release worth cutting anyway: "don't include Claude's test workflows, or os probing." The first half was already done. The second half was true and I had not looked for it.

shares_this_gpu answered "is the writer on this machine" by asking the OS for our own name, resolving it to every address behind it, resolving the target, and intersecting the two sets. The intent is local and the function exists to prevent reaching across a network -- it was added after someone's laptop had its model evicted by a desktop. None of that is visible to a static scanner, which sees a program enumerating its own host's identity, and that reading is fair. It happened not to fire this round. It is exactly the shape that does.

It binds instead. An address binds only if this machine holds it, which is the question, asked directly rather than by comparing two resolver results. It is also the better implementation: no name lookup, correct for addresses a name lookup would never have returned, and immune to a stale hosts-file entry. The LAN case that motivated the original -- LM Studio local, typed in as 192.168.x.x rather than localhost -- still works, which a loopback-only rewrite would have silently broken.

Two things worth keeping from how this went. The first draft removed the call and then explained the removal in a docstring that used the function's name twice, leaving the string in the file for a scanner that matches strings; the count went from two to zero only after rereading. And the guard in check_planner.py is a source-level assertion rather than a behavioural one, because both implementations agree on every input a checker can name. The difference only exists in the text, so the text is what gets asserted.

42. The label was never an area (2026-09-03)

A user, flatly: "768p Tier: Uses a 768-pixel short-edge baseline (such as 1344 x 768) ... this is the stated native resolution for minimax h3 (which people also coin as 0.98mp)."

Section 38 in this file describes replacing a hand-authored canvas table with a formula, measuring it against the old tuples, and running a small grid search to justify per-axis rounding. All of that was careful work on the wrong algorithm.

Core's adapt_canvas has a one-line docstring: "768-short-edge canvas with 7681344 area cap, per-axis round to 32."* It pins the short edge and derives the long edge from the ratio. It does not work from an area budget. What v1.1 shipped derived BOTH axes from a megapixel figure, and the two agree at no aspect ratio at all -- 16:9 came out 1312x768's worth of pixels shaped 1312x736 against core's 1344x768, and 4:3 came out 1152x864 against 1024x768. The comment above the function claimed it mirrored core. It mirrored the rounding.

The error was upstream of the code, in reading "0.98 MP" as 980,000 pixels. 1344 x 768 = 1,032,192, and 1,032,192 / 1,048,576 = 0.984. The number everyone quotes is a MEBIpixel count of a short-edge tier -- 1024*1024, not 10^6. So the label was describing the thing I had decided it could not describe, and a decision was put to the user ("pure maths, accept 1312x736") on a premise that was simply false. They accepted it. It was still wrong.

The replacement is core's function with the short edge as an argument, so the draft tiers run the identical path rather than a second implementation that agrees at one rung. And check_canvas.py now imports adapt_canvas and compares against it directly, instead of against numbers copied out of it. The old assertion -- "area is within 5% of the label" -- passed the entire time the sizes were wrong, because it was checking the formula against its own premise. That is the whole lesson: an assertion derived from the implementation cannot falsify the implementation.

All fifteen 1.0.x cells are pinned now rather than nine, since no short-edge formula reproduces an area table by accident. The five v1.1 pre-release labels alias forward onto the tier they were trying to name, rather than to the sizes their arithmetic gave them -- they named the right thing badly, and a graph saved mid-development should land where its author meant.

43. Three times in one day (2026-09-03)

1.0.2 shipped to clear a scanner finding. It doubled it.

The change removed a hostname lookup from shares_this_gpu and replaced it with a bind test -- better code by every measure except the one being optimised. The scan came back with two findings where 1.0.1 had one. The bind matched three patterns at once, and the second finding was in docs/DEVLOG.md, on the line of section 41 where the aiohttp client class was quoted while explaining that the aiohttp client class was the finding.

That is the same mistake three times in one day. The first draft of the new docstring used the removed function's name twice while explaining its removal; that one was caught by rereading, and the count went two to zero. The devlog one was not caught, because prose does not feel like code. The third was the replacement docstring quoting the two patterns that had just flagged it.

Reading is not a control. tools/check_publish.py reads the set comfy node publish actually uploads -- git-tracked, minus .comfyignore -- and fails on any token this pack has been Flagged for, wherever it appears. Its first run found eight occurrences, six of which predated the day's work, including one in .comfyignore itself: the file explaining which trigger words were being excluded had quoted them, and it ships.

Two consequences beyond the fix. CLAUDE.md and docs/DEVLOG.md stop shipping -- they are developer material, they are on GitHub, and they are where a discussion of scan patterns naturally lives. And shares_this_gpu is loopback only. The LAN-address case genuinely regresses: a writer on this machine addressed as 192.168.x.x no longer gets its model evicted automatically. The message says so and names the fix, which is to type localhost. A courtesy feature is not worth every user who reads the scan seeing a socket call.

The aiohttp finding itself remains, and no release will clear it. The rule has no taint analysis, never looks at a destination, and every alternative client is in the same family. It needs a reviewer.

44. Decoding a plate to throw most of it away (2026-09-03)

A user, relaying another: "for reference clip, someone was mentioning the ability to do a resize on the input -- to save on memory and speed. LD promptmaster has this feature as well."

Section 40's closing note said reference-video resizing was deferred because "core already scales ref video down, so the cost is disk and load time, not quality." The first half is true. The second half looks at the wrong place.

Core does resize -- but at the far end, in MiniMaxH3ReferenceToVideo.execute, after load_video has decoded every frame at source resolution, stacked them, and converted the stack to float32. For a 10 s 4K plate that is about 36 GB of system RAM spent to deliver about 4.5 GB of pixels that core then discards. Nothing about the output changes; the memory is simply spent before anyone looks at whether it was needed. That is not a missing feature, it is a defect, and it was sitting behind a sentence I had written to explain why there was nothing to do here.

So there are two changes, and only one of them is the requested feature.

load_video now computes the decode size before the loop and hands it to frame.reformat, so libswscale scales inside the decoder and a full-resolution RGB array is never built. The default, "match H3", asks core's own adapt_canvas what it would have resized to and never scales up -- a clip already below the tier is left exactly alone, which is what core does too. On the default path the model therefore sees the same pixels through a different resampling kernel, and nothing else moves.

The requested part is the rungs below that: 640p through 384p, trading reference fidelity for memory. Measured on a 226-frame 960x544 plate, which is already under the tier and so gets nothing from the defect fix: 1.42 GB and 6.1 s at source, 0.70 GB and 2.0 s at 384p. Three times faster is more than the pixel count explains -- the RGB conversion and the float32 cast cost more than the decode does.

Third, free: load_video has accepted max_frames since it was written and nobody passed it. Core truncates a reference clip to the hop's frame count, so a 60 s plate on a 10 s hop decoded 1440 frames to use 243. It is passed now, bounded by the LONGEST hop -- bounding by the shortest would cut frames core might still have wanted.

The lesson is the one from section 42 wearing different clothes. Both times a conclusion was reached by reasoning about what the code must be doing rather than reading where the cost actually lands, and both times the reasoning was written down confidently enough that it stopped anyone looking again. A user asking "possible?" was what reopened it.

45. A mean cannot see a colour (2026-09-05)

An outside tester ran ten controlled 9-hop chains -- 65 s each, one variable per run, same model, LoRA, references, locked audio and seed -- and measured them with her own instruments rather than ours. The result that matters here is not which lever won. It is her section 5, which explains in our own code why none of them could have.

The relay chain loses about a fifth of the skin's colourfulness over nine hops (chroma 33.6 in the reference still, 30 at hop 1, 23.8 by hop 9) and darkens it (L* 52.3 -> 45.0), while the HUE ANGLE DOES NOT MOVE. It is not a cast. It is a loss of chroma and a loss of level, arriving together.

tone_compensate=anchor was built to hold exactly this and did not, for two reasons. The first is a plumbing problem -- under the latent join the corrected frames never become the next hop's pin -- and it is the pin anchor's to fix. The second is this one: anchor_pull matched a per-channel RGB MEAN. Three channel means cannot distinguish "less colourful" from "differently coloured", because a hop that has greyed out can have all three of its means sitting exactly on the reference. The correction had nothing to correct with.

So the anchor now measures and corrects in CIE Lab, and pulls four numbers rather than three: mean L*, mean a*, mean b*, and the SPREAD of L*. a* and b* are the colour on its own, which is the thing that was being lost. The spread is the contrast, which is what hardens when a face bakes -- her section 3.2 measured mid-scale contrast rising x1.07 to x1.37 across the ten runs while fine detail fell to 0.76-0.96 of the still, the combination that reads as waxy. A per-hop cap and the existing ramp are unchanged in spirit; the spread has its own cap (ANCHOR_MAX_GAIN) because it is a ratio, and a ratio applied to a hop whose contrast genuinely collapsed -- a fade, a cut to a flat wall -- would stretch it hard.

The cost is real and worth naming. Lab is a non-linear round trip over every pixel of every frame, and the first working version cost 32 s on a 362-frame 1344x768 hop. Three changes took it to 15 s: the statistics are read from 24 evenly spaced frames rather than all 362 (they agree to 0.005 Lab units, and it is four moments over twenty million pixels either way), frames past the ramp skip the blend they would multiply by 1.0, and every linear stage -- both colour matrices and the f()->Lab assembly -- is a matmul instead of three expressions and a torch.stack. That last one alone was 9x on the stage it touches: 0.032 s to 0.003 s on a full frame, measured, because BLAS does in one call what the stack form does in nine multiplies, six adds and a copy.

A 3D LUT was tried first and rejected on its own numbers: 33^3 lattice with trilinear interpolation came out SLOWER than the direct conversion (0.301 s against 0.256 s on the same chunk) and carried 2.1/255 of error. The intuition that a lookup must beat a transcendental is a CPU-era one; on a vectorised backend the eight gathers cost more than the two pow calls they replace.

The seam guarantee is unchanged and is still checked: frame 0 comes back bit-identical, because the ramp blends against the untouched source in RGB rather than in Lab. Through a non-linear round trip that distinction is the whole guarantee -- a Lab-side blend of zero strength still returns the pixel that survived a forward and inverse transform, not the pixel that went in.

Two things this does not fix, both deliberate. It still corrects the DELIVERED frames, so under the Motion-Context latent join it still never reaches the next hop's pin. And it still measures the whole frame at once, so a chain where the skin greys while the background gains edges -- which is what hers did -- gets one compromise correction for two opposite drifts.

46. Anchoring on the first casualty (2026-09-05)

tone_compensate=anchor holds the chain on hop 1's look, and the reasoning was that hop 1 is "the only tone in the chain nobody drifted into". The ten-run study says that is wrong in a way that matters: hop 1 is already not the photograph. Before any relay has happened, measured on the same instrument, the reference still reads chroma 33.6 and hop 1 reads 30; b* 26.6 against 22; fine detail 0.72 to 0.99 of the still. The chain was being held on a target that had already fallen short, and holding it perfectly still meant converging on the first casualty rather than on the reference.

tone_anchor_ref chooses: hop1 is the original behaviour and stays the default, still takes the statistics from start_image instead. Two things follow from the second that the first cannot do. Hop 1 itself gets pulled, which is the only way that 33.6-against-30 gap is ever closed. And the target stops moving with the chain -- a photograph does not drift.

Ramp handling had to change with it. The ramp exists to keep a JOIN exact: frame 0 of a hop must equal the previous hop's last frame, so the correction fades in over 48 frames. Hop 1 has no previous frame, and neither does a restart hop, which opens on the photograph by construction. Both now take the correction whole from frame 0 (ramp=0), because ramping them spends two seconds fading into the look at the exact moment a viewer decides what the shot looks like.

While wiring the key for it, a cache gap that predates this: the tone settings were in no key at all, on the documented grounds that the cache holds RAW hops and tone is applied after, so switching modes need not invalidate them. That is true of the hop being corrected and FALSE of the next one -- the corrected frames are what prev_imgs becomes, and prev_imgs is the pin. Hop 2 rendered under one tone mode was being served to a run using another, with a byte-identical key. Now keyed from hop 2 only, which keeps the half of the original claim that was always true: hop 1 has no pin, so it still survives every tone switch.

47. Choosing the pin, and refusing to pretend (2026-09-04)

The node has always known which mechanism pinned each hop. _motion_context_cls() resolves the upstream class and rejects forks whose apply() differs, run() logs the path each hop took, and the preview shows it per hop. The only thing missing was the ability to choose, which made a whole class of question unanswerable: does the AddGuide pixel path ratchet less than Motion-Context? Its VAE round trip is itself a projection and might scrub the off-manifold latent structure that accumulates -- at the cost of the join quality Motion-Context was picked for. Today the only way to ask was to uninstall a pack.

pin_mech is auto / motion_context / addguide, defaulting to auto, which is exactly what shipped.

The one way to get this wrong is well documented, by the code itself. _pin_mech_for predicts the mechanism so it can go in the per-hop cache key before the pin runs, and its docstring says "Every condition here mirrors _pin_continue". If the predicted mechanism and the executed one disagree, the key stops describing what is on disk -- which is the failure that made cache_hops=on measurably worse than off before the latent sidecar landed. So the override is applied in both, and both carry a comment saying not to change one without the other.

Forcing does not add a fifth condition to the predictor. It removes the four, which is the point. A forced setting that silently degrades to the other mechanism answers a question nobody asked, and worse, poisons the A/B it was turned on to run. So motion_context refuses rather than falls back. The two chain-wide preconditions -- pack installed, and an overlap with a matching context_length -- are checked before any sampling, next to the duration validation, so a bad combination fails on the queue rather than three hops in and names the accepted frame counts. The per-hop precondition, a previous hop that came from a cache entry written before latents were stored, cannot be known up front and raises at the hop it affects, with the two ways out. And if Motion-Context itself raises at call time -- the one thing the predictor was always unable to foresee -- a forced setting re-raises instead of quietly downgrading.

The cache work was already done, years of it in one comment. The mechanism is in the per-hop key and deliberately NOT in chain_salt, so switching re-renders hops 2+ and hop 1 hits cache. That is the ideal A/B and it fell out of the existing design with nothing added. Adding pin_mech to chain_salt would have thrown away a byte-identical hop 1 on every comparison, which is the mistake the comment two lines above it records about overlap.

Two things this cost that are worth writing down. The widget is APPENDED, never inserted: widgets_values is a bare ordered array indexed against the schema, so a widget added anywhere but the end silently reassigns every later value in every saved workflow. Section 27 said it in one line -- adding options to a combo is safe, adding widgets is not. And check_workflows.py caught the other half immediately, 48 widgets against 49, because both shipped workflows carry their own widgets_values array and neither knew about the new dial. That check existing is the only reason this was a thirty-second fix rather than a bug report about a Starter that loads with its dials one position out.

Last, a message. Forcing addguide sets the Motion-Context class to None internally, which walked straight into the existing "Motion-Context not available; install it for a latent join" line -- false, and precisely the line a user would read while wondering why forcing the setting appeared to do nothing. Forced now says it was forced.

48. The restart was still being told it was a continuation (2026-09-05)

anchor: "restart" shipped in 1.2.0-beta1 with a clear contract, written into the branch that implements it: "A restart hop is a chain start. It gets the photograph as its frame-0 anchor exactly as hop 1 does, and NOTHING from the previous hop reaches it -- no sampler latent, no decoded tail."

The first half was true. The second was not, and the code said so two hundred lines apart without anyone noticing, because hop_restart was computed beside the sampler, and almost everything that makes a hop a start rather than a continuation is decided long before that:

• _attach_pin_to_qwen ran on i > 0, so a restart hop was handed the previous hop's last frame as Qwen <Picture 1> and its last 22 frames as a live video reference.
• _assemble_next ran on i > 0, so the compiled prompt opened with "The clip opens already in progress from the pinned frames" -- on a hop whose frame 0 is a studio portrait and which has no pinned frames at all.
• Under hop_script=next the identity stills were dropped as "unscheduled stills stay off this continue", on the one hop that is not a continue and most needs them.
• The voice reference was dropped for the same reason.
• And dry_run never printed the ANCHOR RESTART line, because that print sat past the point a dry run returns. The one tool for reading a plan before paying for it did not mention the feature.

An outside reviewer found the consequence in the tester's own package, and her instruments had already recorded it. Background edge density at the restart hop is 0.0032 and 0.0031 in the two restart runs, against 4.7 to 7.2 at every other hop of those same runs -- a featureless backdrop. Verified here from background_metrics.json rather than taken on report. For several seconds the model renders the reference photograph instead of the room.

The asymmetry is the part that convinced me. Both runs restart at hops 4 AND 7, and only hop 4 collapses; hop 7 reads 6.77 and 4.68, an ordinary room. So this is not "restart is broken".

Correction, from the reviewer's second pass, before anyone builds on the paragraph above. My first reading was that the hop was handed a portrait at frame 0 and rendered it. That is wrong, and the frames say so. Hop 4 OPENS on the couch -- 21.0 to 22.5 s is the room, at 162 to 167 KB a frame -- ghosts at 23.0, sits on the identity still from 23.5 to 26.0 at 61 to 72 KB, and is back on the couch at 26.5 s, inside the same hop. The next hop does not rescue it; it leaves and returns on its own. So the restart's frame-0 anchor worked. What failed is the middle of a pin-less hop, where the eight identity photographs are an attractor with no video pin holding the room.

Two consequences. First, background_metrics.json samples MID-hop frames, so edge_density = 0.003 is a reading of the wander, not of the whole hop -- still a true reading, and still one nobody interpreted. Second, hop index and seed are confounded in this package: hop 4 is seed ...458 and hop 7 is ...461 in both runs, so anything that happens only on hop 4 here also happens only on that seed. The asymmetry cannot be attributed yet.

It is also not restart's invention. Run 02 -- a plain relay, continuous join, Motion-Context pin -- does the same thing at t = 9 to 10 s and comes back by t = 11. Same attractor, shorter, because it had a pin.

What the fix below is, then: the code contradicted its own contract in five places, all of them real, none of them proven to be THIS. The continuation wrapper is the one candidate the reviewer could not rule out, because a contact sheet shows the authored beat and not the block the encoder receives. Whether it was the cause is a render away.

The fix is small and entirely in the ordering: hop_restart is computed at the top of the hop loop, hop_is_start = i == 0 or hop_restart replaces the six i == 0 / i > 0 tests that were standing in for it, and the restart hop's cache key drops the pin levers and the tone settings because its pixels genuinely cannot depend on them.

Three lessons. First: a contract written in a comment is not a contract. The words "NOTHING from the previous hop reaches it" sat six lines from code that passed the previous hop's tail, and reading either one alone made sense. Second: the instruments caught it and the prose did not. edge_density = 0.00 is not a subtle reading. It was in the table, in the shipped package, and the write-up described that hop as "the restart resets every axis at the cut" -- because the number that mattered was the one nobody expected to look at. Someone reviewing measurements they did not take is worth more than one more run.

Third, and it is the one I paid for: having the right defect does not license the first story that explains it. The five contract violations were real and I found them by reading; the causal claim I hung on them lasted until somebody opened the frames and checked when the hop actually breaks. The fix stands. The explanation did not.

49. Four features that already shipped (2026-09-04)

A review pass went looking for missing capability and kept finding the capability already there. Four things users have asked for are implemented, and they fail in four different ways -- which matters, because each one needs a different fix and only one of them is a documentation gap.

README:133 said "Voice stays as a reference every hop." The code says otherwise: hop_voice is true only at i == 0 or under hop_script=verbatim, so on any chain with a shot plan -- which forces next -- the voice is a hop 1 reference and nothing else. That is deliberate, and the comment directly above the line records why: in chain_00038 a second <Audio 1> with no line to attach to put a 1.35 s male take into the final second while the written line still followed the woman's face. The console has been printing voice ref stays off this continue the whole time. So the node was right, the log was right, and the sentence was wrong -- which is the worst of the four, because a user who reads the doc and believes it files a bug against working code. One had already done so.

pin_renorm was worse in a quieter way. The row documented the sigma story and recommended it for 3+ hops. But sigma was measured to be the wrong statistic -- total spread falls across a chain whose picture is baking, so matching it corrects the wrong way -- and band, which matches the statistic the ratchet actually moves, took a 12.74% drift to -0.04%. Section 27 measured all of this on 2026-09-01 and the tooltip has carried it since. The README went on pointing at the inert mode and never named the working one. Documentation that disagrees with the tooltip beside it is not a gap, it is a contradiction, and the tooltip won.

mp was simply absent. The Reference register section documented five sibling fields and omitted the sixth, whose only prior appearance was one clause in the 1.0.0 release note -- despite refs.py carrying it, :1916 consuming it as cap_mp=, and the rail drawing it on every row. It is also the dial people ask for when they ask for a per-reference resolution slider. Now documented, with the trap that makes it look broken: on the default ref_image_size=match every reference is scaled to the output area first and mp only caps further, so at 768p the 1.5 and 2.0 settings do nothing at all. The real control is max plus mp, and that pairing was written down nowhere.

Per-hop duration was the different one. It shipped, it is cache-correct, and it was documented -- in a fields table, as one clause, where nobody found it. It kept being requested as a new feature. The fix for that is not another sentence; it is an example, so there is one now, and the editorial rule that goes with it is in PROMPTING.md: overlap is chain-wide, so short hops cut and long hops flow.

The pattern is worth keeping. Three of these four cost nothing to build because they were already built, and the support cost of the first two was being paid in bug reports against correct code. When a capability is requested, check whether it exists and is merely unfindable before designing it.

50. What the fingerprint could not see (2026-09-04)

Three holes in hop-cache invalidation, none of them live while cache_hops ships off, all of them the same shape: something that changes the rendered frames does not change the key that identifies them. That is the failure mode the fingerprint exists to prevent, and its own docstring names the stakes -- "silently wrong output, which is worse than no cache at all."

The first is the base checkpoint, and it is the one a second person makes likely. _model_fingerprint hashed the LoRA patch keys, the per-key strength scalars and the scalar half of transformer_options. Every one of those describes something patched ONTO the model. Nothing described the model. So an int8 build and a bf16 build of the same architecture, under the same LoRA stack at the same strengths and the same attention settings, produced byte-identical hop keys. ComfyUI re-executes the node because the loader's output changed, run() recomputes the same keys, and the cache serves frames rendered under the other checkpoint. It now hashes the inner model's class, its dtype through ModelPatcher's own model_dtype(), and its parameter count. Two different int8 builds of the same architecture still match; separating those needs digests of fixed weight keys and a state-dict walk per run, which is a worse trade.

The second is the more interesting one, because it is the SLA bug wearing a different coat. That fix -- which lives only in the _closure_scalars docstring, never having been written up here -- taught _scalars to dig settings out of a callable's closure, because H3-SLA-Attention installs its config that way and changing sparsity 0.90 -> 0.50 had been leaving the key unmoved. But a node can also configure itself with a plain object -- set_model_patch_replace(cache, "dit", "block_loop", 0) with a configured instance -- and closure-digging cannot reach that. Worse, such an instance is usually callable, so it went down the closure path and came back as the constant "fn()": an instance inherits neither __qualname__ nor __name__ from its class, and it has no __closure__ at all. Every setting on it hashed to the same four characters as every other. Presence was detected, because installing the node adds a key to patches_replace; configuration was not.

That is not hypothetical. It is the shape of an approximate step cache that is actively recommended alongside this model, whose whole behaviour is three numbers -- a reuse threshold, a window, a step cap -- carried on the instance.

_object_scalars reads an object's public scalar attributes before falling back to its type name. Review then found two more bindings that hide an object behind a callable and lose it just as completely. A BOUND METHOD: vars() on one proxies to the underlying function's __dict__, which is empty, not to the instance, so a node registering self.forward instead of self is the same bug one attribute away. And a functools.partial: no name, no cells, no attributes of its own, everything it carries sitting in func, args and keywords -- the SLA bug one binding away. Both collapsed to the same four characters as a bare instance did. _callable_scalars now unwraps all four shapes.

The tradeoff is worth writing down plainly, because the first draft of this entry got it wrong and review caught that too. A public scalar the node mutates during a run IS hashed. Only mutable containers are skipped, and a step counter is normally a plain int on the instance rather than a dict, so it is hashed like any other setting. A node that counts on itself between queues therefore moves the fingerprint between runs and the cache stops hitting for as long as it is installed. That is wasteful rather than wrong, and it is the direction this pack should err in -- but it is a real cost, and it used to be an invisible one. The run now prints the fingerprint beside the hop-cache line, because a cache that has quietly stopped hitting is otherwise indistinguishable from one that is merely cold.

The third is not a hole but a cost. pin_to_qwen sat in chain_salt, which mixes into every hop -- while _attach_pin_to_qwen is called only under if i > 0. So the setting could not reach hop 1's pixels, and keying it chain-wide threw away a byte-identical cached hop 1 on every pin_to_qwen A/B. That is exactly the mistake the comment two lines above it was written to record about overlap, repeated one field over. It has moved to the per-hop key, from hop 2, next to overlap and pin_cond which already live there for the same reason. Read the comment block in chain_salt as a checklist: any lever whose effect starts at hop 2 does not belong in it.

None of this can be caught by reading a diff, which is why it now has a checker. tools/check_cache_keys.py builds two graphs differing in exactly one thing and requires the digests to disagree -- and requires two identical graphs to agree, because a fingerprint that always moves is a cache that never hits. It carries a regression guard for the closure path as well, so the SLA case cannot come back quietly. Before the fix it fails on the dtype case and the object case and passes the rest, which is the only real evidence that a cache key fix did anything at all.

51. The sidecar was a pickle, and did not need to be (2026-09-04)

store.py wrote the hop's sampler latent with torch.save and read it back with weights_only=False. The comment beside the read was honest about why -- this is our own dict, written by our own put(), into ComfyUI's temp directory, not a downloaded checkpoint -- and it was true. It was also the next thing a registry scanner reaches for after the subprocess work in 0.4.1 through 0.4.3, and being right about a finding is not the same as not having one.

Nothing about the payload needed a pickle. The awkward member is samples, which is a comfy.nested_tensor.NestedTensor, and latents.parts() has decomposed that into plain tensors since the pin levers needed exactly that decomposition. A flat dict of tensors plus a small JSON header is a safetensors file wearing a different name, and safetensors is already a hard dependency of ComfyUI. The sidecar is now .latent.safetensors: components as samples.N, tensor members of the dict as extra.<key>, scalar members in the header.

Three things this had to get right, and they are asserted in tools/check_latent_sidecar.py rather than argued for here.

Bit-identical, not close. A cached hop's latent becomes the next hop's Motion-Context pin, so a chain resumed from cache that differs at all from an uninterrupted one would mean the cache changes the output -- the single thing it must never do. The test round-trips through a real file on disk and requires torch.equal, not a tolerance.

Every member survives, including ones this code has never seen. A latent dict that came back missing a key would be quietly not the latent that was stored, so an unrepresentable member refuses the whole write rather than dropping it. That refusal costs nothing, because the caller already had a correct answer for it: cache the frames, skip the latent, fall back to the pixel pin. That path was built when latents were first stored and it is exercised here rather than added.

Old .pt entries are not read. The extension changed, so they are simply invisible, and _get_latent's docstring already promised what happens then -- entries written by an older build have no sidecar and keep working. Not reading them is the point: keeping a compatibility path would keep weights_only=False in the file, which is the thing being removed.

The interesting part was the first version being wrong in a way only the repository's own tooling caught. It recorded the container's module and qualname in the header and rebuilt it with importlib.import_module, which is more general and reads to a registry scanner as python_bytecode_manipulation. check_publish.py failed on it immediately. Trading the pickle finding for a dynamic-import finding would have been a lateral move dressed up as a fix, and the generality bought nothing: parts() recognises exactly two shapes, a bare tensor and a nested one. The header now names which, and the rebuild is a static import. If core ever moves NestedTensor, that import raises, the existing handler logs it and the hop falls back to the pixel pin -- loud, and already handled.

Worth stating plainly, because the analysis this came from got it backwards at first: the incremental-writer machinery from silveroxides' unifiedefficientloader is not what this wanted. Its cleverness is a reserved header that lets you stream thousands of tensors whose shapes you do not know yet. This is a handful of tensors of known shape written at once. Plain save_file is the whole job. The place that machinery would earn its keep is the master frame buffer, and that is the opposite direction -- one tensor, known shape, contiguous ranges, which wants a memmap instead.

52. Thirty-one gigabytes doing nothing (2026-09-04)

The observation came from outside, from silveroxides, without seeing the code: anything held in memory but completely inactive can be written away while inference runs. The master frame buffer is exactly that shape, and the comment above it has named the number since it was written -- at 8 x 15 s and 1280x736 it is 2742 full float frames, about 31 GB. It is allocated once at full chain length, slice-written as each hop lands, and then not touched again until the final preview frame and the return. Through every sampling pass of every hop it is resident, untouched, and competing with the DiT, the VAE decode buffers, imgs and prev_imgs.

Above 2 GiB it is now a np.memmap in ComfyUI's temp directory, wrapped by torch.from_numpy. Every slice-write is unchanged, the trim still works, and SaveVideo walking frames in order is ideal page locality on the way back out -- the encode may read better off the mapping than out of a cold RAM buffer.

What moves is the peak, not the total. ComfyUI's IMAGE type is a dense tensor, so the whole master still has to exist to be returned. The peak goes from master + inference to max(master, inference).

That sounded like a hedge until it was measured. A 3-hop 8 s chain at 640x1152 was instrumented end to end: peak RSS 49.4 GB, of which the master is 4.4 GB. The useful number is the other one -- non-master residency came out at 41.8 GB and does not grow with chain length. Model weights, the pinned-memory pool and the decode buffers are a fixed cost. The master is the only term that scales, linearly, with frames x area:

  3 x  8 s @ 640x1152    532 frames   master  4.4 GB   peak ~46.2 GB
  8 x 15 s @ 1280x736   2742 frames   master 28.9 GB   peak ~70.6 GB  <-- over 64 GB
 10 x 15 s @ 1280x736   3422 frames   master 36.0 GB   peak ~77.8 GB  <-- over 64 GB
  spilled, any of the above                            peak ~41.8 GB

So the honest claim is scale-dependent, and stating it as a flat percentage was wrong. On a small chain the master is a tenth of the peak and spilling it is a nicety. At the settings the original report came from -- long chains at working resolution -- it is 40% of the peak and it is the term that takes a 64 GB machine past its limit. There the change is not an improvement, it is the difference between a run that completes and one that cannot.

The honest weakness is that the OS decides when pages leave RAM. Under no memory pressure they simply stay and nothing has been bought; under heavy pressure a large dirty flush can stall at an awkward moment. That is not knowable from here and it is why the run prints which path it took -- a silent memory path is the one thing nobody could diagnose from a bug report.

Why a memmap rather than the incremental safetensors writer from section 48's neighbourhood: that machinery exists to stream thousands of tensors whose shapes you do not know in advance, which is why it reserves a header. The master is one tensor, of perfectly known shape, written in contiguous ranges, in order. The right primitive for that is a mapping, and it is nearly a drop-in. The writer earns its place on the latent sidecar, which is the opposite shape -- and that is where it went.

Cleanup is the part that needed thought, and the first answer was wrong in a way that only a real render exposed. The returned IMAGE is backed by its mapping, so the file cannot be removed while run() still has to hand it back. The original plan was therefore to sweep stale files on the NEXT run, relying on Windows refusing to unlink a live mapping as the guard.

It never reclaimed anything. ComfyUI keeps the previous run's output in its execution cache, so the mapping is still open when the next run starts; os.remove raised, and the handler passed on OSError without a word. Two renders left two 9 GB files on disk. The docstring asserted "there is never more than one" and the checker only tested a stale file that nothing held, so both the code and its test agreed with each other and neither agreed with reality. Ten renders would have been 92 GB of silent disk.

Delete-on-close removes the problem rather than policing it. Windows has it natively as O_TEMPORARY; POSIX gets the same by unlinking the name while the descriptor stays open. The bytes then live exactly as long as something is using them, and a hard kill cleans up too, because the kernel closes the handles. The sweep stays as a safety net for files written by the previous build, and it now REPORTS what it could not remove instead of swallowing it -- silence is what let this go unnoticed.

Two things the analysis this came from had wrong, both caught by writing it. numpy was not already imported in h3_ref_chain.py; it is now. And the master is not "never read again until the return" -- master_imgs[-1] feeds the final preview frame. That does not disturb the fp16 argument, because prev_imgs is cloned from imgs and nothing in the conditioning path reads the master back, but the statement was wrong and an fp16 change would have been justified with it.

fp16 is deliberately not in this change. The reasoning holds -- the master is delivery-only, tone_compensate runs before the write so correction arithmetic stays in fp32, and fp16's ten mantissa bits space the top octave about eight times finer than the 8-bit encode downstream. It is a separate decision from where the buffer lives and it should be made on its own. It is emphatically not true of the hop cache, where a resumed chain must not diverge from an uninterrupted one.

What is verified here is narrow and deliberate: that the spilled buffer behaves exactly like the RAM one. tools/check_master_spill.py drives the real access pattern -- the hop-0 write, the later windowed writes, the short-chain trim, the [-1] preview read -- and requires the delivered frames to be bit-identical, because the alternative is a chain whose pixels depend on how much RAM the machine had. The win itself is not testable offline and stays unproven until a long chain runs with peak RSS instrumented.

53. The texture ladder, run (2026-09-04)

Four levers, measured, on one chain. Three of the results contradict something that was written down as guidance, which is the point of running it rather than reasoning about it.

The rig: 3 hops x 8 s at 640x1152, 8 steps lcm/beta_57 under a checkpoint with the turbo baked in, seed 12345 fixed, one location, one subject, a 560x690 face plate on every hop. cache_hops=on, so hop 1 was rendered once and every later run reused it -- which is also the first live confirmation that moving pin_to_qwen out of chain_salt works: run A took 772 s, runs B, C and E about 330 s each because only hops 2 and 3 re-rendered.

The measurement was wrong twice before it was right

First attempt used the probe's default head box. It reported the face's mid band climbing x1.455 across the chain -- a textbook ratchet. Then the box was drawn on an actual frame and it turned out to be sitting half on a yellow sign behind her. Tightened onto skin, the same data reported x0.792. The same chain, measured two ways, gave opposite answers.

Both were wrong, for the reason section 05 already documented and then walked into anyway: the subject moves. camera: hold and framing: keep do not hold the frame, and a fixed pixel box covers mouth-and-nose in hop 1 and smooth forehead in hop 3. Any within-run drift number off this rig is measuring anatomy, not texture.

The fix came from the user watching the videos rather than the numbers: the pose at the END of hop 3 returns close to the pose at the START of hop 1. That pair is matched. Measuring hop 1's first 24 frames against hop 3's last 24 gives a common baseline -- and because hop 1 came off cache in every run, it is literally the same baseline for all four.

What the levers did

Fraction of the reference's face mid-band energy still present at the end of hop 3, and the head/background ratio which cancels frame-wide effects:

  A  baseline                 0.838   ratio 0.609
  B  pin_to_qwen=off          0.781   ratio 0.592      WORSE than doing nothing
  C  pin_renorm=band          0.852   ratio 0.606      within noise of A
  E  pin_mech=addguide        0.954   ratio 0.741      clearly best
  D  ref_image_size=max       untestable

pin_to_qwen=off made it worse. That was the ladder's first rung, the cheapest lever, the one recommended on the reasoning that hops 2+ receive the model's own degraded output presented as a reference picture. Removing it cost texture rather than saving it.

pin_renorm=band did exactly what it claims and it did not matter. The latent high-band fraction it targets drifted -1.90% in A and -0.85% in C, so the lever more than halved the drift in its own statistic -- and moved the pixels by 1.4%, which is noise. The prediction that "band restores the energy ratio without restoring the structure" is now measured rather than argued.

pin_mech=addguide won, and it was never in the ladder. Section 06 justified the switch as the thing that makes the experiment possible -- a way to ask whether the AddGuide VAE round trip scrubs the accumulating latent structure. It does: the pin's sigma climbs 1.0441 -> 1.0612 under Motion-Context and sits flat at 1.0429 -> 1.0409 under AddGuide, and the face keeps 95% of its texture instead of 84%. The lever that was scaffolding turned out to be the only one that worked. This is one chain and it costs whatever join quality Motion-Context was chosen for, which was not measured here.

ref_image_size=max could not be tested at all. H3 only ever scales a reference DOWN. The face plate is 560x690, which is below both the match target (0.74 MP) and the max target (2048 short edge), so both modes hand the model the identical image and the lever is a no-op. Lever 3 needs a genuine high-resolution photograph; a crop from a video frame has nothing to give. Note what this means for the mp dial as well -- its whole range is inert on source material this size.

A second finding nobody was looking for

The background box gains mid-band energy in every run (x1.29 to x1.41) while the face loses it. Detail moves from the subject to the surroundings. That is why a whole-frame metric reads flat on a chain whose face is visibly coming apart -- it averages a rising background against a falling face, which is the exact confound texture_probe was built to replace, caught in the act.

The seams, which the user spotted by eye

Watching the four masters, the user asked whether there were flashes at the joins. There were, and they are the first seam steps this pack has measured across correction modes rather than just asserting.

Mean absolute luma step at the two joins, on byte-identical hops -- every mode after the first is the SAME cached frames re-joined, so nothing but the correction differs:

  off           2.36/255      seams +1.48 and +3.25, both brightening
  frame_shift   1.35/255      -1.80 and -0.90
  gain_bias     0.76/255      -1.50 and +0.02
  lut           0.77/255      -1.49 and +0.04
  anchor        0.68/255      -1.13 and -0.24      best

Three things fall out of that table.

anchor is the mode to use, and frame_shift -- the one the tooltip recommended for regenerated content -- is the weakest of the four corrections, roughly half as effective.

lut does not overfit. It tracks gain_bias to within 0.02/255 at both seams. That warning has been in the module docstring and two tooltips since the modes were written, and it appears never to have been measured. Corrected in all three places, and stated as unproven rather than reversed: one chain is not enough to say lut is good, only that the specific claim has no evidence behind it.

Every mode overshoots, and none of them fixes the first join. An uncorrected seam brightens; a corrected one darkens. All four land between -1.13 and -1.80 at seam 1 where doing nothing gives +1.48. Seam 2 is correctable to near zero by three of them. A systematic bias that survives four different estimators is not noise -- it is something about the first join the estimate cannot see, and the obvious suspect is that hop 2 is the first hop that has a pin at all. Not chased further here.

The objection to AddGuide, tested

The reason Motion-Context is the default is join quality, so addguide winning on texture is only interesting if the join survives. Measured on the delivered masters, with no new renders: mean absolute frame-to-frame difference AT the join, against the median of the twelve frame pairs either side of it. A ratio of 1.0 means the cut looks like ordinary motion.

                        seam 1   seam 2
  A  motion_context      1.25x    0.95x
  E  addguide            1.16x    0.90x
  B  pin_to_qwen=off     1.26x    1.03x
  C  pin_renorm=band     1.21x    0.94x

No run shows a discontinuity, and AddGuide is the lowest of the four at both seams. Frames either side of both joins were also inspected directly and neither mode shows a visible break. The expected cost did not appear.

The limitation is the scene, and it is a real one. This is a talking head under camera: hold with very little motion. Motion-Context exists for motion continuity, so a chain with actual camera movement or fast action is precisely where AddGuide would be expected to fail -- and there is barely any motion here for a join to break. The honest reading is not "AddGuide costs nothing" but "on low-motion content the cost does not show, and the texture gain does." Anyone reaching for it on a moving shot should measure again.

Worth noting the asymmetry that appears here too: seam 1 bumps ~1.2x in every run while seam 2 sits at or below baseline. That is the same first-join asymmetry the brightness measurement found, from an unrelated instrument.

Read section 51 before acting on any of this

Everything above measures TEXTURE, and texture turned out not to be where the degradation lives. A later pass on the same rig found the one quantity that decays monotonically across a chain, and it is not a band energy: it is how much the LIGHTING responds to the subject. Section 51 has it. Three consequences for the numbers above.

The face and background band figures are partly pose, not texture. They are sampled from each hop's last frames, and the lighting in this model tracks head height -- correlation +0.70 in hop 1. The within-hop brightness swing (0.36) is LARGER than the across-chain drift (0.29), so which pose the final frames happen to catch moves the reading more than the chain does. The matched-pose method fixes the anatomy problem, not this one.

A background result reported here was withdrawn. An earlier draft had the background gaining 59% mid-band energy while the face lost it, and read that as detail migrating off the subject. Normalising each box by its own brightness removes the effect entirely: the background is not gaining texture, it is getting 57% BRIGHTER. That was caught only because the user said the lighting kept changing.

pin_to_qwen=off was already the shipped state for the reporting user. An independent audit of her runs found that with nine identity photographs scheduled on every hop she hits MAX_REF_IMAGES, so the pack skips the last-frame Qwen pin anyway -- 36 log lines saying so. The lever measured WORSE here is the one her chains had on the whole time, which makes the result more useful, not less.

One thing above got stronger rather than weaker. pin_mech=addguide winning was doubted because her isolated long-chain test of the same idea (force_pixel_pin) still degraded. The audit found that test had no matched control -- it was read against runs differing in hop count, audio file, reference schedule, encoder-side pin and code version. The A/B here changed one widget against a shared cached hop 1, so it is the better-controlled of the two.

What this is not

One chain, one subject, three hops, 640p, one checkpoint. Every number above is a single measurement. What it does establish is narrower and more useful than a ranking: the levers can now be measured at all, the method that makes them measurable is a matched-pose pair rather than a fixed box, and three pieces of standing guidance were wrong in ways that only showed when someone rendered.

54. The chain forgets how to light her (2026-09-05)

Four levers were measured against the texture ratchet and three did nothing. That is section 50. This is why: the thing that degrades is not texture, and none of those levers could have touched it.

The user watched the four renders and said the lighting kept changing -- darker when she raised her head, brighter when she looked down. That is a real behaviour and it is measurable: in hop 1, the correlation between background brightness and head height is +0.70. The model is doing a light-source thing, and it is doing it well.

By hop 6 that correlation is -0.49. It does not fade, it INVERTS.

The measurement, with the script removed

The obvious objection is that she simply moves less in later hops, and a weaker signal gives a weaker correlation. So the chain was re-run with the SAME BEAT on all six hops -- "She talks to the camera, glancing down at her notes and back up again", chosen because it contains the vertical head movement the lighting tracks. Any decay across hops 2-6 is then the chain's, not the writing's.

  hop   corr(bg luma, head height)   bg swing   how much she MOVED
   1              +0.581               0.278           23.97
   2              +0.631               0.229           22.75
   3              +0.334               0.172           14.73
   4              +0.338               0.133           13.47
   5              -0.417               0.132           11.10
   6              -0.494               0.099           14.52

Three things decay monotonically on identical beats. The lighting stops moving (swing -64%). The subject stops moving (-39%). And the coupling between them inverts.

The inversion is the part no confound explains. Less movement drives a correlation toward ZERO; it cannot carry it through zero to -0.49. That is a different behaviour, not a weaker one. The movement decay does mean the swing and correlation MAGNITUDES are partly downstream of the subject moving less -- which is itself a finding, since the beat asked for the same movement every time.

It is not exposure drift

The chain also brightens: background luma 0.63 -> 0.77. tone_compensate=anchor was run over byte-identical cached hops, so nothing but the correction differed. It pulled the level down (0.767 -> 0.705) and left the responsiveness untouched -- the per-hop swings match the uncorrected run to three decimal places, and the correlation still ends negative. Exposure drift is a symptom sitting on top of this, not the cause.

Why every presentation lever failed

Each hop is conditioned on the previous hop's LAST frames, and the end of a clip is its most settled moment. So each hop starts from a slightly calmer, flatter state than the one before, and it compounds. pin_to_qwen, pin_renorm and pin_mech all change how that state is PRESENTED. None of them changes the fact that it is inherited. That is why three of four did nothing, and why the pin's own statistics show no ratchet at all: sigma wanders 1.000 / 1.010 / 1.015 / 1.021 / 1.010 across six hops with no per-join step, and the high-band fraction ends ABOVE its anchor.

pin_noise is the exception, and the exception proves the reading: it works by mixing energy back INTO the pin, which is the only shipped lever that opposes the inheritance rather than re-presenting it. Measured against a matched control it held movement (18.10 vs 14.52 at hop 6), roughly doubled the surviving lighting swing (0.194 vs 0.099), and prevented the inversion -- +0.228 where the control reached -0.494. At the widget's 0.10 maximum it gets WORSE in the way that matters: more swing, less correlation, i.e. flicker that is not coupled to the subject. The tooltip's "gains reverse above 0.10" is now measured rather than asserted. 0.06 is the number.

anchor=restart, and what it did

If the inheritance is the mechanism, severing it should reset the decay. It does. A 6-hop chain with "anchor": "restart" on hop 4, against the same chain without it:

                   control            restart at 4
  hop 4     corr .338  swing .133   corr .431  swing .239  (+80% swing, +33% move)
  hop 5     corr -.417              corr -.137
  hop 6     corr -.494              corr -.258

The latent agreed independently: the pin's sigma against the hop-2 anchor went x1.0126 in the control and x0.9938 after the restart -- below the anchor, i.e. the accumulation reset rather than merely paused.

And one restart in six hops is not enough. Hop 5, the first hop relaying from the restart, is already at -0.137 where hop 2 relaying from hop 1 was +0.427. By hop 6 it is negative again. The restart buys one clean hop and about half the end-state damage. The useful interval looks like two or three hops, not five, and that is untested.

What this is worth

One subject, one location, 640x1152, six hops, single runs. The hop-to-hop wobble is real -- hop 3's correlation reads .334 in one chain and .559 in another on identical beats -- so no single row above should be defended. What is solid is the direction: three quantities decaying monotonically on identical beats, an inversion no confound explains, a mechanism that predicts which levers can and cannot work, and a lever built on that prediction that moved all three in the right direction at the hop it was applied.

The honest description of the failure is not "texture degrades". It is that the chain converges on a static, evenly-lit, motionless picture -- which is what "plastic" looks like, and which explains why chasing skin detail found nothing.

55. Two channels at a third of capacity (2026-09-05)

A user asked why the MEDIA tab offers one reference clip and one voice. The answer was that nobody had checked what the model takes. Core declares it outright, in the node's own input template: 9 reference images, 3 reference videos, 3 standalone reference audios, 3 per-video soundtracks. The pack matched the 9 and hardcoded one of each of the rest, two lines apart.

So ref_videos and ref_audios ran at a third of capacity, and ref_video_audios ran at zero -- a reference clip reached the model SILENT even when the file had sound. Twelve widgets and a pairing loop later, all three channels are full.

The ordinals are the trap

<Video N> and <Audio N> are positional: core numbers reference blocks by the order it iterates them, and the prompt cites those numbers. So the numbering has to be DENSE. Fill slots 1 and 3 and the model must see <Video 1> and <Video 2>, not 1 and 3 -- and the consequence, which is now in the tooltip and the README, is that clearing a slot RENUMBERS the ones after it. A beat naming "the second clip" then cites something else, and nothing would report it. That is the same class of defect refs.py fixed for pictures and paid for once already.

What the cache needed

chain_salt digested slot 1 of each. Left alone, a chain rendered with a second voice would be served to a run that dropped it -- the silently-wrong-frames class the key exists to prevent. It digests all three of each now, plus which clips carried sound. IS_CHANGED grew the new filenames too, so overwriting clip2.mp4 in place re-runs rather than serving the old render.

The guard that did not exist

tools/check_media_slots.py asserts the dense numbering including the gap case, and then something broader: that every *_file widget the node declares is claimed by a slot in media_strip.js. A Python file widget with no slot falls through to a native dial where the user types a filename by hand -- the 0.4.0 failure recorded at run_panel.js:53, which has recurred since and recurred again during this very session on the shot editor. Nothing checked for it. Now something does.

Not rendered. The plumbing is checked and the ordinals are tested; whether three voices actually behave -- and what three sets of reference blocks cost per step -- needs a GPU.

56. One take, every hop (2026-09-05)

master_audio_file: one continuous recording every hop lip-syncs to, so a chain can carry a scripted voiceover instead of generating a new voice per hop and relaying it. Empty string is off and is the default. The reference diff that first shipped this on a tester's tree is not in the pack; this was rebuilt from the prose, from PromptMasterLD/song_lock.py as the mask/encode reference, and from seven decisions taken in place of asking.

The window function is 0-based, pure, and checked against a hand-computed table for hops 0-8 at 8 s and hops 0-2 at 15 s (tools/check_audio_lock.py). A 1-based version fails every row of that table. The recording's digest is in chain_salt only when the file is set -- adding a None field while off would have moved every existing cache key. Delivered audio is a passthrough of the take trimmed to the rendered duration; the log line names the window.

Untested, because this machine has no GPU window:

• Whether SamplerCustomAdvanced honours a NestedTensor noise_mask on the audio stream. The polarity is asserted (1 on video, 0 on audio) but an ignored mask would still generate a voice that we then throw away at passthrough -- lips would follow the generate, sound would be the take. GPU test 1 in GROK_V2_GPU_TESTS.md is the proof.
• Whether this ComfyUI's audio VAE encode matches song_lock's [B, T, C] call. A mismatch raises with both signatures.
• Beat/<d> alignment with the take. We do not auto-cut a transcript into the beat; unmatched words can pull the mouth off. Visible, recoverable.

57. Last-frame guide, opt-in (2026-09-05)

last_frame_guide: combo off / still, default off. still AddGuide-pins start_image at the last PIXEL frame of every hop (frame_idx=-1, which Core counts from the end). Conservative half only: that pin does not become the next hop's frame 0. Keyframe chaining is a v3 conversation.

Default off is byte-identical. The setting reaches hop 1, so it lives in the per-hop key for every hop, and only when not off -- a new "off" field would have moved every existing cache key. Queue-fails if still is set with no start_image_file.

The index is the thing that was easy to get wrong. AddGuide's frame_idx is pixel frames. H3's FRAME_PER_TOKEN is (1, 4, 4, 4, 4). An 8 s hop is 192 pixel frames at latent T=57; latent_T-1 is pixel 56, about 2.3 s in, not the end. _last_pixel_guide_idx returns -1 so that trap has one place to live. tools/check_last_frame_guide.py asserts it.

Untested, because this machine has no GPU window:

• Whether the DiT actually treats a last-pixel AddGuide as a bound. The hop-4 wander this is medicine for was diagnosed on pin-less restarts; a last-frame pin can still lose if identity stills in the rail outvote it mid-hop. GPU test 5 in GROK_V2_GPU_TESTS.md.
• Whether -1 after Core's resolved_frame_index = frame_count + frame_idx is the last decoded frame, not one token-group early. Core's own tooltip says negative values count from the end; we did not decode a hop to confirm the last displayed frame matches.
• Chroma pulse at the still/render gap, named in the tooltip. Off by default, so a bad result costs nothing shipped.

58. Restart hops write their full length (2026-09-05)

A restart is a chain start. It overlaps with nothing. The master-write path still dropped the leading overlap_n frames of every hop after index 0, and the preallocation sum(lengths) - overlap * (n - 1) sized the buffer to match. Two restarts on a 9 x 8 s / 0.9 s chain threw away 44 frames (1.83 s) -- either silence at the end or an overrun raise, depending on which side you looked at.

The write now keys on hop_is_start, not i == 0. The preallocation counts only the hops that actually trim. The audio-lock window moves with the master head: a restart hop's take slice starts at the current write position, not at hop_index * stride. Leaving the uniform stride in place would have locked lips 0.9 s earlier than the picture, once per restart, compounding.

overlap leaves the per-hop key on a restart the same way pin_cond does -- the lever cannot reach a start hop's pixels. tools/check_restart_trim.py has the 1552 / 1596 table and the 510/24 vs 532/24 window split.

Untested: the 40 ms audio xfade at a restart cut (same helper as a continuation join). A hard concat might click; we did not hear it. GPU test 4 in GROK_V2_GPU_TESTS.md is the length check -- the log line names the frame count.

59. Shot-level refs, a choice not a drop (2026-09-05)

Identity stills on a pin-less hop can win the middle of it -- restart hop 4 of the tester chain opened on the couch and visited the portrait anyway. Silently dropping those stills on restart hops was the old accident, and it is not obviously right: a restart that needs the face still needs the face.

shot.refs is the choice. Omitted keeps the register default (unscheduled stills ride chain starts, stay off continuations under hop_script=next). [] is explicit none. A filled list is those tags only, in that order -- putting the room first is how you stop a portrait becoming Picture 1. Unknown tags fail on the queue. The editor round-trips both a filled list and the empty list; destroying the field on save is how it died the first time it existed.

Default is current behaviour on purpose. Last-frame guide (DEVLOG "Last-frame guide, opt-in") is the other medicine, and it is also opt-in. Neither ships as a silent drop.

Untested: whether refs: [] on hop 4 actually keeps the couch. The diagnosis is from pictures, not from this code path. GPU test 3.

60. 2.0.0 (2026-09-05)

Version bump. pyproject.toml 2.0.0, editor VERSION v2.0.0, README and CHANGELOG.md written against the code. Shot-field table, MEDIA strip, hop-cache notes and the "no shot-level refs" line were stale; join: cut in a README example is not a join value. docs/HANDOVER_*.md left as history; BETA_NOTES.md marked superseded. No behaviour change.

61. Locked hop-1 audio was 2-D, hop-2 trim was 3-D (2026-09-05)

GPU test 1: hop 1 locked [0.00s-8.00s] of the 26 s take, then died on hop 2 at _xfade_audio with Tensors must have same number of dimensions: got 2 and 3. The lock path squeezed the take to [C, T] for wav and unsqueezed a copy into the AUDIO dict; hop 1 wrote wav onto the master and hop 2 xfade'd that against audio["waveform"] which is [B, C, T].

_xfade_audio now batches both sides. The lock path keeps wav as [B, C, T] so it matches a decode. tools/check_audio_lock.py cats a 2-D take against a 3-D hop. Needs a ComfyUI restart (Python).

62. GPU tests 1 and 2 (2026-09-05)

2 hops × 8 s × 8 steps, 26 s ElevenLabs take, after the xfade fix and a ComfyUI restart.

Test 1 (lock on). Hop 1 audio locked [0.00s-8.00s], hop 2 [7.08s-15.08s], join wrote, final audio: passthrough of master_audio_file [0.00s-15.08s], drift +0 ms. Window and polarity are not Fail A/B.

Test 2 (lock off). Empty MEDIA slot: no master_audio_file: loaded, no audio locked, no passthrough line. Delivered audio is generated voice (heard). Drift -40 ms (the generated-voice xfade). Empty is off.

Still untested on GPU: last-frame guide, restart hop 4, restart length arithmetic on a real master, refs: [] on a pin-less hop. The latent sidecar still logs not representable without pickling on this NestedTensor shape -- hops render; a later cache hit will fall back to the pixel pin.

63. The fixture did not match the code (2026-09-05)

master_audio_file shipped with the hop cache silently disabled underneath it.

Every locked hop of the first GPU test logged latent not cached (ValueError('latent is not representable without pickling')). The hops rendered, so it read as noise. It is not noise. Without a stored sampler latent a later cache hit leaves prev_sampled empty, the hop after it predicts the AddGuide pixel fallback instead of Motion-Context, and that prediction is part of its key -- so the key stops matching what is on disk. store.py already carries a paragraph about this exact chain of consequences, written when the sidecar was built, ending "making cache_hops=on actively worse than off". A feature added after it walked straight back into it.

The cause is one line of type-checking. _latent_to_flat handles samples through latents.parts() because it can be a NestedTensor, and then handles every OTHER member of the latent dict as either a plain tensor or a scalar. But this is a joint AV latent, so anything shaped like it carries one tensor per stream -- and the audio lock's whole mechanism is out["noise_mask"] = NestedTensor((ones, zeros)). A NestedTensor is not a torch.Tensor; the module docstring in latents.py says so in its second paragraph. It fell to the else, which refuses, which is correct-by-design behaviour applied to a case nobody meant to refuse.

tools/check_latent_sidecar.py covered "other members of the latent dict" and passed, because its fixture builds the mask as torch.rand(1, 1, 8, 8) -- a plain tensor. The code under test never makes one of those. A fixture that does not match what the code produces is not a test, and this one was green through the whole of v2's development while the behaviour it guards was broken in every run that used the feature it was written beside.

Fixed both ends. Nested members are now decomposed the way samples is, stored as nested.<key>.<i>, and rebuilt through the same static import and the same class-name check; a member whose container parts() does not recognise is still refused rather than dropped, because restoring a latent minus its noise_mask would denoise the audio it was supposed to freeze. The checker now builds the mask the shape the code actually sets, and fails without the fix.

The lesson is not "write more checks". There were twenty-two, all green, and one of them was pointed directly at this. It is that a check is only as good as the resemblance between its fixture and production, and that resemblance decays silently every time a feature lands next to an older test. The tell was in the log the whole time, once per hop, in a line that said the word ValueError and was still easy to read as routine.

64. fp16 for the master, and what it actually costs (2026-09-05)

Section 52 deferred this: "fp16 is deliberately not in this change... it is a separate decision and should be made on its own." The decision was never made, and the master shipped fp32 through the whole of v2. Taking it now.

The master is DELIVERY-ONLY. prev_imgs is cloned from imgs, never read back out of the master, so nothing in the conditioning path depends on its precision. That halves both the footprint and the disk I/O of the largest allocation in the pack: an 8 x 15 s 1280x736 chain goes from ~29 GB to 14.4 GB.

fp16 and not bf16. The buffer is clamped to 0..1, so exponent range buys nothing and mantissa bits are the whole question. fp16's ten space the top octave at about 1/2048; bf16's seven space it at 1/256 -- exactly 8-bit output precision with nothing in reserve, and the highlights would band.

It is not free, and the checker now says so in the right units. The first assertion written here was "fp16 delivers the same 8-bit pixels as fp32", and it FAILED. The encode truncates rather than rounds -- core's Image.fromarray(np.clip(i, 0, 255).astype(np.uint8)) -- so a value fp16 nudges down across an integer boundary loses one 255th. Measured over two million samples: 2.06% of pixels move, every one of them by exactly 1, none by more, and rounding instead of truncating barely changes it (2.06%). That is well under the h264 encode's own error and is not visible, but "eight times finer than the output" was an argument about spacing that quietly implied bit-identity, and bit-identity is not what happens. The check asserts the measured bound instead of the comfortable claim.

Two paths were verified not to care: _frame_to_jpeg_b64 and sheet.small both call .detach().float() before touching pixels, so the preview and the contact sheet are unaffected. The one thing offline work cannot settle is a downstream node that assumes an IMAGE is fp32 -- core's own save path handles it, third-party nodes are not all core. That is a two-hop render away and belongs in the next GPU window.

Also recorded here because it was missing everywhere except this log: the master-spill work began with silveroxides putting the problem in exactly these terms and proposing unifiedefficientloader's streaming writer. The diagnosis was right. The writer was the wrong shape -- it exists to stream many tensors of unknown offset, and this is one tensor of known size written in order -- so np.memmap won and no code travelled. No licence obligation follows from that, which is precisely why the credit is worth writing down: this pack already names rkfg in tone.py and PromptMasterLD in audio_lock.py for techniques rather than code, and the same rule applies to a reading that turned out to be correct.

65. What the GPU window settled (2026-09-05)

Four things were verified on hardware, and one of them corrected a reading of my own.

anchor=restart stays in the shot. The tester's 9-hop package had hop 4 of both restart runs leaving the couch for the reference portrait for about two and a half seconds. On the v2 build, 4 hops at 0.70 MP with a fresh seed on the restart hop, it does not happen: hop 4 opens at the desk, holds the mic mid-hop, and ends at the desk. tools/shot_probe.py reads edges 3.2-4.4% and 1979-2483 colours across the whole hop with no collapse anywhere.

That is one run, and hop index and seed were confounded in her package, so this is "did not reproduce with the contract violations fixed and a different seed" rather than "fixed". The five contract violations in section 48 remain unproven as the cause. Recorded as such.

Restart hops write their full length. 4 hops x 192f overlap 22 -> 724 frames, and the log prints old formula would have been 702f beside it. The arithmetic in master_frame_count holds on hardware.

fp16 survives delivery. master buffer: 3.0 GB spilled at 0.70 MP and 4.2 GB at native, both exactly half what fp32 would have asked for, and SaveVideo accepted the fp16 IMAGE without complaint. That was the one claim in section 64 that offline work could not settle.

The last-frame guide fixes the restart cut, and I misread what it costs.

Guided, hop 3 arrives at the still's framing instead of snapping to it, so the restart reads as a match cut rather than the obvious jump the user watched on the unguided run. Two frames either side of the join make it plain: unguided, hop 3 ends tight and smiling and hop 4 opens wide and neutral -- a framing jump, a pose jump and a colour shift at once.

Then the cost, measured: the four hop ENDINGS converge to 3.8/255 of each other, against 39.1/255 unguided, while mid-hop frames stay as varied as ever (65.8 against 61.1). I put those four endings in a grid, saw one picture four times, and called for making the setting per-shot before release.

That was the wrong call and the user said so. A hop's last frame is passed through in a twenty-fourth of a second and the next hop continues straight out of it. Four stills in a grid is precisely the presentation that makes convergence obvious and motion invisible. Two people watched the clip and saw nothing; I had looked at 4 frames of 724 and chosen the arrangement that flattered my worry. The number is right, the inference from it was not.

What the number does support is narrower and is now a test rather than a claim. That run had CAMERA, FRAMING and PACE all unset, so nothing competed with the photograph. The guide plants it at frame_idx=-1 on every hop, so a shot authored framing: close ought to be overridden at its own ending -- and if it is, that is a real constraint on a feature we are shipping. Running now with close on two hops against a start image that is a wide.

The lesson is the one from section 48 wearing different clothes, six hours later. There the defect was real and the story I hung on it was not. Here the measurement is real and the conclusion I drew from it was not. Both times the error was reaching past what the evidence covered, and both times somebody looking at the actual output caught it.

66. The seam report was measuring the middle of hops (2026-09-05)

The user's complaint was ergonomic: the seam report's hops and overlap are typed in by hand and have to be kept in step with the chain node, which is a chore and goes stale. The bug underneath it is not ergonomic.

seam_positions(total, hops, overlap) does not know where the joins are. It solves for them, assuming every hop is the same length and every hop past the first is trimmed by the overlap. Section 58 broke the second assumption: a restart hop is a chain start, overlaps nothing, and writes its full length. So on the 4 x 192 chain rendered tonight with a restart on hop 4 -- 724 frames, overlap 22 -- it solves for a hop length of 197.5 and puts the seams at 198, 373, 548. The joins are at 192, 362, 532.

It does not merely misplace them. Planting a real step at each true join and measuring the same clip both ways:

unwired   seam 1 @ f198  +0.00/255  invisible
          seam 2 @ f373  +0.00/255  invisible
          seam 3 @ f548  +0.00/255  invisible

wired     seam 1 @ f192 +15.30/255  VISIBLE
          seam 2 @ f362 -12.75/255  VISIBLE
          seam 3 @ f532 +10.20/255  VISIBLE

Six, eleven and sixteen frames off is enough to land in the flat middle of a hop, where there is nothing to measure, so the report gives a clean bill of health to a chain with three visible seams. Anyone A/B-ing restart against relay -- which is the experiment this whole line of work exists to run -- would have read "0 of 3 visible" and believed it.

The fix is to stop deriving something that is known. run() records the write position of every hop past the first as it lays it into the master, and publishes them on info:

4 hops x 192f overlap 22 -> 724 frames (30.2s) 768x1344
seams: 192, 362, 532

HTCSeamReport takes info as an OPTIONAL socket -- forceInput: True, so it is not a widget and adds no entry to widgets_values, and every workflow saved before today keeps reading its three numbers out of the right slots. Wired, the widgets are ignored and the measured positions are exact. Unwired, nothing changes. An unparseable string falls back rather than raising, because a bad line on an input should not break a report that worked without one.

Two things worth keeping. The uniform solve also printed NOTE hop length works out to 197.50 frames, which is not a whole number -- the hops are probably not all the same duration, which was correct and was the tell, and which nobody read as anything but noise. And the ergonomic complaint was the symptom that surfaced it: a number a user has to keep in sync by hand is a number that will eventually disagree with the render, and the question "why do I have to type this twice" is a reasonable way to find out that the second copy was never reliable in the first place.

67. Guiding the hop that needs it, and only that one (2026-09-05)

last_frame_guide=still was shipped in section 57 as an opt-in with a GPU-untested note. It has now been run twice, and both results are real.

It works. With anchor: restart, the cut used to be an obvious jump -- hop 3 ending tight and smiling, hop 4 opening wide and neutral, a framing change and a pose change and a colour shift arriving together. Guided, hop 3 ARRIVES at the still's framing, so the restart opens on a composition the previous hop already reached. A match cut instead of a jump.

And it overreaches. The guide plants the photograph at frame_idx=-1 on every hop, unconditionally, so it also overrides an authored framing directive at every hop's ending. A shot set framing: close renders as a close-up for six seconds and then snaps to the still's wider framing in about 0.6 s; the next hop pushes back in and snaps again. The user watching that clip, with no idea what had changed, described it as "the camera kept cutting in and out". Frames into hop 3, framing: close:

1.58s close   3.67s close   4.92s close   5.96s close-ish   6.58s WIDE   7.04s WIDE

The directive wins the middle of the hop and the guide wins the end, which is the worst way to divide them.

before_restart guides only a hop whose NEXT shot is anchor="restart" -- the one place the behaviour has been shown to earn anything. Everywhere else the hop ends where the beat and the directives take it.

Two implementation notes worth keeping. The gate is a helper, _guides_last_frame(mode, hop_index, shots), used by BOTH the apply site and the cache-key field, because those two are the pair that has to agree: _pin_mech_for and _pin_continue disagreeing is what made cache_hops=on worse than off before the sidecar landed, and a key that says a hop was guided when it was not is the same defect wearing a different hat. And the key field is keyed on what the hop GETS rather than on the widget, so an unguided hop in a before_restart chain keeps the byte-identical key it had when the feature did not exist.

An option added to an existing combo, not a new widget: widgets_values is positional, and adding options is the safe half of that rule while adding widgets is not.

Also caught by the checker rather than by me: rewriting the tooltip silently dropped "default": "off" from the widget spec. Behaviour would have been unchanged -- ComfyUI falls back to the first combo entry, which is still off -- which is exactly the kind of thing that survives review and then means something later.

68. Three fixtures that did not match the code (2026-09-05)

Section 63 found a checker aimed squarely at a defect that passed anyway, because its fixture built a noise_mask as a plain tensor where the code makes a NestedTensor. That was one checker. An outside audit then asked the same question of the other twenty-one, and three of them had the same shape of hole. Closed here.

check_audio_lock.py never built the lock's real objects. It tabled the window arithmetic against a hand-computed table -- which is genuinely the strongest thing in the file -- fed assert_mask_polarity two toy tensors, and checked the xfade. It never called _splice_locked_audio, so the two unrecoverable failures of this feature were both untested: a mask on the wrong stream generates a voice over a frozen picture, and a video component that does not come back bit-identical is a silently different render. The splice is now driven with the shapes read off a real cached hop -- video [1, 24, 57, 72, 40], audio [1, 32, 2, 320] -- and asserts the video is bit-identical, the audio is the slice, the mask is NESTED with ones on video and zeros on audio and each spanning its own stream's dims, and that a video-only latent and a length mismatch are both refused by name. Breaking the mask to a plain tensor and separately scaling the video by 0.999 each fail it.

check_cache_keys.py never populated model.patches. _Patcher has taken a patches= argument since it was written and not one assertion ever passed one, so every check in the file ran against an empty dict -- which makes the loop that hashes LoRA key names and strengths a no-op. A regression that stopped hashing strengths entirely would have passed, and the consequence is the one this checker exists for: no crash, no failing test, a cache serving frames rendered under a different LoRA stack. Now covers key names, key ORDER (core hands back a dict, so two runs of one stack must agree), strength_patch, strength_model, and a malformed entry degrading rather than raising. Deleting the two strength lines fails exactly the two assertions about strength and nothing else.

check_master_spill.py never wrote a restart hop. drive() wrote hop 0 full and everything after it trimmed, which was production until section 58 made restart hops write their full length. A full-length write in the MIDDLE of a mapping was never exercised.

That third one came with a lesson about the limits of the test rather than the code. Breaking drive() to trim the restart did NOT fail anything, and it cannot: drive() feeds the RAM buffer and the mapping identically, so this file proves the mapping behaves like RAM and can never prove drive() matches run(). The restart pattern buys a full-length mid-chain write against np.memmap; it does not buy a guarantee that this is still what run() does. That guarantee lives in check_restart_trim.py, which reads run()'s own arithmetic. Both facts are now in the file, because the next person to read it will otherwise assume the first implies the second -- which is the assumption that let section 63 sit green for a week.

The audit's own framing is worth keeping: a fixture that does not resemble production is not a test, and the resemblance decays silently every time a feature lands next to an older checker. Twenty-two green checks were true and four of them were not measuring what their names claimed.

69. The caption was describing the person it replaced (2026-09-06)

SWAP shipped in 2.0.0 as a standalone implant: a fifth tab that writes one hop from a reference clip and an identity still, and never touches ref_plan. Stages 1 to 3 passed their GPU gate and merged. This is what stage 4 -- the swap modes -- cost to get right, and none of it was in the code.

A headswap checkbox cannot work here. The contributed fork had one, and unticking it only omitted a line from the instruct. That does nothing: sampling runs at cfg 1.0 with no negative branch, the identity photograph is in front of the encoder either way, and silence about identity lets it govern the whole subject. What is excluded has to be SAID.

The taxonomy came from PromptMasterLD, whose edit laws separate a subject replace from a head swap -- "THE BODY STAYS WITH THE PLATE", then build, hands, posture, every garment -- and from a features-only face swap. Four named modes, each stating what STAYS. Technique, not code.

Then three renders that all looked like "head swap does not work", and were three different things.

The first was a description of a pose. SWAP was sent ONE frame, so a vision model looking at a still of somebody with their hands on a bed wrote exactly that, while the instruct told it "the action, place and motion follow the clip" -- asking it to describe something it had never been shown. Three frames now, evenly spaced across the trimmed window and captioned in time order. That is also what "video vision" is in practice: the VLMs advertising it sample frames and present them ordered. Saying the order out loud is what turns three pictures into a movement. The next caption read "clenching their fists as white steam begins to rise... posture intensifies... vapor swirls more aggressively".

The second was the beat naming the identity once, in a subordinate clause -- "the person with the head of @ref_1" -- against a clip carrying 192 frames of conditioning. One photograph, added rather than weighed. The mode rules now specify the construction: the pack's own idiom first, attached to the subject, then a second sentence saying what stays.

The third was the one that mattered, and the user found it, not me. The failed run had a clip description and the successful one did not:

successful:  a reference clip is wired but has no description
failed:      <Video 1> is a reference clip: A man wearing an orange tank
             top stands in a dimly lit room...

That caption reaches the encoder as what <Video 1> IS. "A man wearing an orange tank top" asserts the subject's sex, build and clothing, additively, against a beat asking for somebody else. Not a weak signal losing a contest -- a flat contradiction. And SWAP's own Describe button wrote it, because _DESCRIBE_SYSTEM asked for "who is in it".

The clip is a MOTION AND PLACE plate. Identity comes from the stills. The caption now describes the action, the movement, the setting and the light, and is told not to describe the person at all. Because that is an instruction to an LLM rather than a guarantee, the caption is screened for words that describe a person and the tab says which ones it found -- a warning, never a rejection, since "a man" is a fine caption for a crowd.

And a fourth thing, which is not a bug and is worth more than the rest. With all of that fixed the swap still only took hold four seconds into an eight second hop. Core truncates a reference clip to frames[:frame_count], so reference frame N conditions output frame N -- the clip is temporally aligned with the output, and wherever it shows a clear face it competes with the identity stills for that same face. Decode area sets token count, token count is how loud the clip is, and at MAX it wins until the clip's own face is obscured. The swap arrived exactly when the steam covered him.

0.3 MP fixed it. reference_video_size was documented purely as a memory and detail budget, which is true and is not the half a user needs when an identity swap half works. It is an INFLUENCE dial and now says so.

What this section is really about: four consecutive reports of "head swap does not work" that were a missing frame sequence, a weak citation, a self-inflicted contradiction and a conditioning imbalance. Nothing in the code was broken. Every one of them was legible from the log -- the caption line, the beat, the frame count -- and three of the four were found by reading it rather than by changing anything.