render_from, and a cache that stops re-rendering hops nothing touched

Three things, all aimed at the same complaint: changing one shot in the middle
of a chain cost a whole chain.

`render_from` is the other end of the range `render_through` already had. It
truncates nothing -- the hops before it still run through the loop, they are
just required to come out of the hop cache instead of the sampler. Doing it
that way rather than seeding prev_imgs / prev_audio / prev_sampled / prev_key
from the store up front means there is still exactly ONE piece of code that
carries continuity forward, and it is the cache-hit branch that was already
carrying it. The sampler latent is the part that would have been got wrong: it
decides whether the next hop joins by Motion-Context or falls back to AddGuide.

Every misconfiguration is refused before the master tensor is allocated, which
on an 8x15s plan is ~31 GB. An inverted range is checked against the ORIGINAL
render_through, because `n` has already been truncated to it by then and
testing against `n` reported "past the end of the plan" and then rendered the
whole thing. A missing cache entry names the hop and says why it might be gone
rather than printing "cache miss" and leaving people to count files in temp.

The cache change is the one that matters most. `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 because the key is chained, that
re-rendered everything. References are now keyed per hop, from `base_images`,
which is the right set on both paths: this hop's scheduled stills with a ref
plan, every wired ref without one, and the pin frame it excludes is already
covered by prev_key.

Last: the 9-reference ceiling is per ENCODE, not per plan, but it was counted
over the whole rail. Twelve references at three per shot across four shots was
refused against a limit no shot came near. Counted per shot now, with
unscheduled refs counted everywhere as the conservative case -- under
hop_script=next they only ride hop 1, so that can refuse a plan that would
have been fine but never accept one that would overflow. A shot that fills all
nine slots now says so, because _attach_pin_to_qwen drops the incoming frame
rather than a still when there is no room, which turns a continuation into a
fresh generate.

The schema keeps maxItems at 9: a grammar cannot express "per hop", so the
writer is held to the safe subset and hand-authored plans get the real rule.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014VB4Dw6F79643vySkf19KV

h3_ref_chain.py

@@ -1552,6 +1552,22 @@ class HandTieClips:
                     "default": 0.0, "min": 0.0, "max": 3600.0, "step": 0.1,
                     "tooltip": "End of the soundtrack window. 0 = to the end.",
                 }),
+                # Appended 2026-09-03 -- LAST, per the note at the top of this
+                # block. `render_through` has been here since 0.4 and stops the
+                # chain; this is the other end of the same range.
+                "render_from": ("INT", {
+                    "default": 0, "min": 0, "max": 64,
+                    "tooltip": (
+                        "Start at this hop instead of hop 1. 0 starts at the "
+                        "beginning. Everything before it is replayed from the "
+                        "hop cache rather than rendered, so re-running one shot "
+                        "in the middle of a long chain costs that shot. "
+                        "Needs cache_hops=on, and every earlier hop must "
+                        "already be in the cache -- it names the first one that "
+                        "is not rather than guessing at the join. Pair it with "
+                        "render_through to render a range."
+                    ),
+                }),
             },
             "hidden": {
                 "unique_id": "UNIQUE_ID",
@@ -1615,7 +1631,7 @@ class HandTieClips:
             music_fit="loop", music_fade_s=1.0, soundtrack_file="",
             voice_start_s=0.0, voice_end_s=0.0,
             reference_video_start_s=0.0, reference_video_end_s=0.0,
-            music_start_s=0.0, music_end_s=0.0,
+            music_start_s=0.0, music_end_s=0.0, render_from=0,
             unique_id=None):
         # First thing, before a single model is touched: hand the writer's VRAM
         # back. The plan writer stays resident between plans now, which is the
@@ -1710,6 +1726,46 @@ class HandTieClips:
             print(f"[{TAG}] render_through={stop_at} is past the end of a "
                   f"{n}-hop plan; rendering all of it", flush=True)
 
+        # render_from is the other end of the same range, and unlike
+        # render_through it truncates nothing at all: the hops before it still
+        # run through the loop, they just have to come out of the cache instead
+        # of the sampler. Validated against the store further down, once there
+        # is a store to validate against.
+        start_at = int(render_from or 0)
+        # Inverted range first, and against the ORIGINAL render_through: `n` has
+        # already been truncated to it above, so testing start_at against `n`
+        # here would report an inverted range as "past the end of the plan" and
+        # then quietly render the whole thing.
+        if start_at > 1 and 0 < stop_at < start_at:
+            raise ValueError(
+                f"{TAG}: render_from={start_at} is past "
+                f"render_through={stop_at}, so the range is empty. "
+                "render_through is the LAST hop to render, not a count.")
+        if start_at > n:
+            print(f"[{TAG}] render_from={start_at} is past the end of a "
+                  f"{n}-hop plan; starting at hop 1", flush=True)
+            start_at = 0
+        replay_before = max(0, start_at - 1)
+        if replay_before:
+            # Checked here rather than beside the hop store, which is built much
+            # further down -- after the master tensor, which at 8 x 15 s and
+            # 1280x736 is ~31 GB. A misconfigured range must not cost that
+            # allocation before it is told it is misconfigured.
+            if dry:
+                raise ValueError(
+                    f"{TAG}: render_from={start_at} needs the hop cache, and a "
+                    "dry run never touches it. Use render_through to limit what "
+                    "a dry run compiles.")
+            if str(cache_hops) != "on":
+                raise ValueError(
+                    f"{TAG}: render_from={start_at} replays hops 1-"
+                    f"{replay_before} from the hop cache, so cache_hops must be "
+                    "on. With it off there is nothing to replay from, and the "
+                    f"join into hop {start_at} would be invented rather than "
+                    "continued.")
+            print(f"[{TAG}] render_from={start_at}: hops 1-{replay_before} come "
+                  f"from the cache, {start_at}-{n} render", flush=True)
+
         # Per-shot duration overrides, validated up front so a bad value fails
         # before any sampling happens rather than three hops in.
         lengths = []
@@ -1877,6 +1933,14 @@ class HandTieClips:
                 budget_gb=float(cache_budget_gb), fps=FPS)
             print(f"[{TAG}] hop cache: {hop_store.root} "
                   f"(budget {float(cache_budget_gb):.0f} GB)", flush=True)
+        # Note on how render_from works, since this is where the store appears:
+        # the leading hops are NOT seeded into prev_imgs / prev_audio /
+        # prev_sampled / prev_key from here. They run through the loop like any
+        # other hop and are simply required to hit the cache. The hit branch
+        # already carries all four forward exactly as a render does -- the
+        # sampler latent especially, which decides whether the next hop joins by
+        # Motion-Context or falls back to AddGuide -- and a second copy of that
+        # logic is a second thing to get subtly and silently wrong.
         # Everything constant across the chain, mixed into every hop key so a
         # resolution or sampler change invalidates the whole cache.
         chain_salt = {
@@ -1895,8 +1959,14 @@ class HandTieClips:
             # in _pin_continue (Motion-Context when a sampler latent exists,
             # AddGuide pixels otherwise), so it belongs in the per-hop key
             # below, not in the chain-wide salt.
-            "refs": {s: _store.tensor_digest(t)
-                     for s, t in sorted(slot_images.items())},
+            # No "refs" here any more -- they are keyed per hop below.
+            #
+            # Digesting every wired reference chain-wide meant swapping the file
+            # behind @outfit moved hop 1's key even when @outfit rides only hop
+            # 5, and because the key is chained that re-rendered the entire
+            # chain. Changing one late reference cost a full run. A reference
+            # can only change the pixels of a hop it is actually handed to, so
+            # that is where it belongs.
             "voice": _store.audio_digest(voice),
             "refvid": _store.tensor_digest(reference_video),
             "start": _store.tensor_digest(start_image),
@@ -2161,6 +2231,14 @@ class HandTieClips:
                     "seed": (int(shot["seed"]) if shot.get("seed") is not None
                              else ((int(seed) + i) if seed_per_shot else int(seed))),
                     "tags": [r["tag"] for r in hop_active],
+                    # The reference PIXELS this hop is handed, not the whole
+                    # rail (see chain_salt). `base_images` is the pre-pin dict,
+                    # which is the right thing on both paths: with a ref plan it
+                    # is this hop's scheduled stills, without one it is every
+                    # wired ref, and the pin frame it excludes is already
+                    # accounted for by `prev_key`.
+                    "refs": {k: _store.tensor_digest(t)
+                             for k, t in sorted((base_images or {}).items())},
                     # Per hop, not chain-wide: hop 2 after a hop-1 cache hit
                     # has no sampler latent and falls back to AddGuide, which
                     # is a different render of the same inputs.
@@ -2200,6 +2278,19 @@ class HandTieClips:
                               f"render yet; rendering it once", flush=True)
                 hop_keys.append(hop_key)
                 cached = hop_store.get(hop_key)
+                if i < replay_before and cached is None:
+                    # Name the hop. "Cache miss" on its own sends people to the
+                    # temp folder to count files; what they need to know is
+                    # which shot moved and that the sweep may simply have
+                    # reclaimed it -- the store is under ComfyUI's temp
+                    # directory, which is deleted on startup and shutdown.
+                    raise ValueError(
+                        f"{TAG}: render_from={start_at} needs hop {i + 1} in "
+                        "the cache and it is not there. Either its inputs "
+                        "changed since it rendered -- editing an earlier shot "
+                        "moves every key after it -- or the cache was swept. "
+                        f"Render hops 1-{replay_before} first, or set "
+                        "render_from back to 0.")
 
             this_sampled = None
             if cached is not None:

prompt_pack/SCHEMA.json

@@ -192,7 +192,7 @@
             }
           },
           "maxItems": 9,
-          "description": "At most 9 pictures on any one hop."
+          "description": "At most 9 pictures on any one hop. Keep the whole list to 9 and that always holds."
         },
         "subjects": {
           "type": "object",

refs.py

@@ -246,9 +246,7 @@ def parse_ref_plan(text):
         _fail("ref_plan 'refs' must be an array")
 
     refs = [_norm_ref(r, i) for i, r in enumerate(raw_refs)]
-    if len(refs) > MAX_REF_IMAGES:
-        _fail(f"ref_plan has {len(refs)} references; the encoder takes at most "
-              f"{MAX_REF_IMAGES} in one plan.")
+    _check_hop_load(refs)
     # The ordinal is derived from list position, which is what the author sees
     # in the rail. This keeps `active_refs`/`ordinals` unchanged while the
     # authored identity moves from a socket number to a filename.
@@ -274,6 +272,49 @@ def parse_ref_plan(text):
     return {"refs": refs, "subjects": subjects}
 
 
+def _check_hop_load(refs):
+    """Fail if any single shot would carry more stills than one encode takes.
+
+    The limit is per ENCODE, not per plan -- `active_refs` is what decides who
+    turns up at each one. This counted the whole rail until 1.1, so twelve
+    references scheduled three to a shot across four shots were refused against
+    a ceiling no shot came near.
+
+    `shots: null` is counted on every shot, which is the worst case rather than
+    always the truth: under `hop_script=next` an unscheduled still is dropped
+    from continuation hops, so it really only rides hop 1. Counting it
+    everywhere can only refuse a plan that would have been fine in `next` mode,
+    never accept one that would overflow -- and the ceiling is a hard encoder
+    limit, so erring toward refusing is the right direction.
+    """
+    always = [r for r in refs if r["shots"] is None]
+    by_shot = {}
+    for r in refs:
+        for h in (r["shots"] or []):
+            by_shot.setdefault(h, []).append(r)
+
+    worst_shot, worst = None, len(always)
+    for h in sorted(by_shot):
+        if len(always) + len(by_shot[h]) > worst:
+            worst_shot, worst = h, len(always) + len(by_shot[h])
+    if worst > MAX_REF_IMAGES:
+        where = f"shot {worst_shot}" if worst_shot is not None else "every shot"
+        rides = (f" {len(always)} of them have no shots set, so they are "
+                 "counted on every shot." if always else "")
+        _fail(f"{where} would carry {worst} references; one encode takes at "
+              f"most {MAX_REF_IMAGES}.{rides}")
+    # A hop that is already full has no room for the incoming frame, and
+    # _attach_pin_to_qwen drops it rather than a still -- which turns a
+    # continuation into a fresh generate with only the invisible latent pin
+    # holding it. Better said here, once, than discovered as a hard cut.
+    if worst == MAX_REF_IMAGES:
+        where = f"shot {worst_shot}" if worst_shot is not None else "every shot"
+        print(f"[{TAG}] note: {where} carries the full {MAX_REF_IMAGES} "
+              "references, leaving no slot for the incoming frame. On a "
+              "continuation hop pin_to_qwen will be skipped there; drop one "
+              "reference if you want the pin shown to the encoder.", flush=True)
+
+
 def active_refs(refs, hop_index, wired_slots):
     """Refs live on this hop, in rail order, restricted to those whose file loaded.
 

tools/check_features.py

@@ -267,12 +267,73 @@ def main():
         ck("render_through=%d compiles %d hop(s)" % (rt, want),
            o[2].count("===== hop") == want)
 
+    # render_from. The replay itself needs a populated cache and a real render,
+    # so what is asserted here is the half that decides whether a user loses an
+    # hour: every misconfiguration is refused BEFORE the master tensor is
+    # allocated (~31 GB on this plan) and before a single step is sampled.
+    def raises(**kw):
+        try:
+            run(**kw)
+        except ValueError as exc:
+            return str(exc)
+        return ""
+
+    ck("render_from past render_through is refused",
+       "range is empty" in raises(render_from=5, render_through=2))
+    ck("render_from on a dry run is refused",
+       "dry run never touches it" in raises(render_from=3))
+    ck("render_from without the hop cache is refused",
+       "cache_hops must be on" in raises(render_from=3, dry_run="off",
+                                         cache_hops="off"))
+    o, log = run(render_from=99)
+    ck("render_from past the end falls back to hop 1",
+       "past the end" in log and o[2].count("===== hop") == 8)
+    o, log = run(render_from=1)
+    ck("render_from=1 is not a replay at all",
+       "come from the cache" not in log and o[2].count("===== hop") == 8)
+    o, _ = run(render_from=0)
+    ck("render_from=0 leaves the chain alone", o[2].count("===== hop") == 8)
+
     _, log = run(quality="draft", render_through=2)
     ck("draft drops the canvas", "736x416" in log and "0.30 MP" in log)
     ck("draft drops the steps", "6 steps" in log)
     _, log = run(quality="final", render_through=2)
     ck("final leaves the canvas alone", "1280x736" in log)
 
+    # The reference ceiling is per ENCODE, not per plan. This counted the whole
+    # rail until 1.1, so a plan that spread its references across shots was
+    # refused against a limit no shot came near.
+    R = sys.modules["htcpack.refs"]
+
+    def rail(*specs):
+        """specs are (tag, shots) pairs; shots=None means 'rides every shot'."""
+        return json.dumps({"refs": [
+            {"tag": t, "file": f"{t}.jpg", "shots": s} for t, s in specs]})
+
+    def ref_err(*specs):
+        try:
+            R.parse_ref_plan(rail(*specs))
+        except Exception as exc:
+            return str(exc)
+        return ""
+
+    spread = [(f"r{i}", [1 + i // 3]) for i in range(12)]
+    ck("12 references at 3 per shot is allowed", not ref_err(*spread))
+    ck("10 references all riding every shot is refused",
+       "would carry 10" in ref_err(*[(f"r{i}", None) for i in range(10)]))
+    ck("10 references landing on ONE shot is refused",
+       "shot 2 would carry 10" in ref_err(*[(f"r{i}", [2]) for i in range(10)]))
+    # The mix is the case the old plan-wide count could not see either way:
+    # 6 unscheduled + 4 on shot 3 is 10 on that shot, and 6 everywhere else.
+    ck("unscheduled references count on every shot",
+       "shot 3 would carry 10" in ref_err(
+           *([(f"a{i}", None) for i in range(6)]
+             + [(f"b{i}", [3]) for i in range(4)])))
+    ck("the refusal explains where the unscheduled ones went",
+       "counted on every shot" in ref_err(
+           *([(f"a{i}", None) for i in range(6)]
+             + [(f"b{i}", [3]) for i in range(4)])))
+
     print()
     if FAIL:
         print("%d FAILURE(S): %s" % (len(FAIL), ", ".join(FAIL)))

tools/gen_schema.py

@@ -219,10 +219,20 @@ def build():
                 "required": ["refs"],
                 "additionalProperties": False,
                 "properties": {
+                    # The real rule is per HOP: a plan may hold more than
+                    # MAX_REF_IMAGES so long as no single hop carries that many,
+                    # which is what refs._check_hop_load enforces. A JSON-schema
+                    # grammar cannot express "per hop", and maxItems on the array
+                    # is the only lever structured output gives us -- so the
+                    # writer is held to the safe subset instead: a plan whose
+                    # whole rail fits on one hop can never breach the real rule.
+                    # Hand-authored plans are checked against the real rule.
                     "refs": {"type": "array", "items": ref,
                              "maxItems": r.MAX_REF_IMAGES,
                              "description": f"At most {r.MAX_REF_IMAGES} "
-                                            f"pictures on any one hop."},
+                                            f"pictures on any one hop. Keep the "
+                                            f"whole list to {r.MAX_REF_IMAGES} "
+                                            f"and that always holds."},
                     "subjects": {
                         "type": "object",
                         "patternProperties": {"^[0-9]+$": subject},

workflows/HandTieClips_Showcase.json

@@ -608,6 +608,7 @@
         0,
         0,
         0,
+        0,
         0
       ],
       "title": "H3 Ref2VA Chain - showcase 6x7s"

workflows/HandTieClips_Starter.json

@@ -611,6 +611,7 @@
         0,
         0,
         0,
+        0,
         0
       ],
       "title": "H3 Ref2VA Chain - starter"