Add pin_mech: choose the hop-2+ pin mechanism

Detection already existed -- _motion_context_cls() resolves the upstream class
and rejects incompatible forks, run() logs the path per hop, the preview shows
it. Only the choice was missing, which made one question unanswerable: does the
AddGuide pixel path ratchet less than Motion-Context? Its VAE round trip is
itself a projection and may scrub the latent structure that accumulates, at the
cost of the join quality Motion-Context was chosen for. Asking that used to mean
uninstalling a pack.

pin_mech is auto / motion_context / addguide, default auto = current behaviour.

The override is applied in BOTH _pin_mech_for and _pin_continue. The predictor
exists to put the mechanism in the per-hop cache key before the pin runs, and
its docstring already says every condition mirrors the executor. If the two
disagree the key stops describing what is on disk -- the failure that made
cache_hops=on worse than off before the latent sidecar landed. Both now carry a
comment saying not to change one without the other.

Forcing removes the predictor's four conditions rather than adding a fifth. A
forced setting that silently degrades answers a question nobody asked and
poisons the A/B it was turned on to run, so motion_context refuses instead:

- pack not installed, and overlap with no matching context_length, are
chain-wide, so both are validated before any sampling beside the duration
checks, naming the accepted frame counts;
- no previous sampler latent is per-hop and raises at the hop it affects,
naming both ways out;
- Motion-Context raising at call time -- the one case the predictor was always
unable to foresee -- re-raises rather than downgrading.

Not added to chain_salt. The mechanism is already in the per-hop key by design,
so switching re-renders hops 2+ and hop 1 hits cache: the ideal A/B, free from
the existing structure. Keying it chain-wide would throw away a byte-identical
hop 1 on every comparison, which is the mistake the comment two lines above it
records about overlap.

The widget is APPENDED, never inserted -- widgets_values is a bare ordered array
indexed against the schema. check_workflows.py caught the other half at once (48
vs 49): both shipped workflows carry their own array and neither knew about the
new dial. Both updated; because the widget is last, no existing index moves.

js/editor/run_panel.js GROUPS lands in this commit, not a later one. A Python
widget without its JS registration falls through to a native dial, which is what
happened to five widgets in 0.4.0.

Forcing addguide sets the Motion-Context class to None internally, which walked
into the existing "Motion-Context not available; install it" line -- false, and
exactly the line a user would read while wondering why forcing did nothing.
Forced now says it was forced.

12/12 checks pass. Browser pass still owed: this needs a ComfyUI restart to load
the new schema.

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

docs/DEVLOG.md

@@ -2298,3 +2298,66 @@ 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.
+
+## 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.

h3_ref_chain.py

@@ -902,7 +902,7 @@ def _condition_pin_latent(lat, anchor, mode="off", noise=0.0, seed=0):
     return new, anchor
 
 
-def _pin_mech_for(hop_index, overlap_n, prev_sampled):
+def _pin_mech_for(hop_index, overlap_n, prev_sampled, mode="auto"):
     """Which mechanism `_pin_continue` will pick, without doing the work.
 
     The hop cache key has to be built *before* the pin runs, and the two
@@ -911,9 +911,29 @@ def _pin_mech_for(hop_index, overlap_n, prev_sampled):
     predict is Motion-Context raising at call time, which the caller catches by
     comparing this against the mechanism actually used and declining to cache
     that hop.
+
+    `mode` is the `pin_mech` widget. "auto" is the shipped behaviour and the
+    four conditions below. Forcing does not add a fifth condition -- it removes
+    them, which is the point: a forced setting that quietly degrades to the
+    other mechanism tells you nothing, and the reason to force one is to
+    compare it against the other. The two chain-wide preconditions are
+    validated before any sampling starts, so the only one that can still be
+    false here is the per-hop latent.
     """
     if hop_index == 0:
         return "none"
+    if mode == "addguide":
+        return "addguide_pixels"
+    if mode == "motion_context":
+        if prev_sampled is None:
+            raise ValueError(
+                f"{TAG}: hop {hop_index + 1}: pin_mech=motion_context needs the "
+                "previous hop's sampler latent, and this one came from a cache "
+                "entry written before latents were stored. Re-render that hop "
+                "(edit it, or turn cache_hops off for one run) or use pin_mech="
+                "auto, which falls back to the AddGuide pixel pin here."
+            )
+        return "motion_context"
     if _motion_context_cls() is None:
         return "addguide_pixels"
     if str(overlap_n) not in MC_CONTEXT_LENGTHS:
@@ -924,7 +944,8 @@ def _pin_mech_for(hop_index, overlap_n, prev_sampled):
 
 
 def _pin_continue(cond, latent, vae, audio_vae, overlap_n,
-                  prev_sampled, prev_imgs, prev_audio, audio_ctx=24):
+                  prev_sampled, prev_imgs, prev_audio, audio_ctx=24,
+                  mode="auto"):
     """Hop 2+ motion pin. Latent Motion-Context when possible; AddGuide otherwise.
 
     AddGuide re-encodes decoded pixels and anchors audio forwards from frame 0
@@ -938,7 +959,11 @@ def _pin_continue(cond, latent, vae, audio_vae, overlap_n,
     pin was available.
     """
     ctx_label = str(overlap_n)
-    mc = _motion_context_cls()
+    # `mode` mirrors _pin_mech_for. Both have to honour it or the mechanism in
+    # the per-hop key stops matching the one on disk, which is the failure that
+    # made cache_hops=on measurably worse than off before the latent sidecar
+    # landed. Do not change one of these without the other.
+    mc = None if mode == "addguide" else _motion_context_cls()
     if mc is not None and ctx_label not in MC_CONTEXT_LENGTHS:
         print(
             f"[{TAG}] overlap {overlap_n}f has no Motion-Context context_length "
@@ -965,11 +990,27 @@ def _pin_continue(cond, latent, vae, audio_vae, overlap_n,
             # exception rather than swallowed -- repr(), because a bare
             # TypeError from a renamed upstream kwarg stringifies to nothing
             # useful.
+            if mode == "motion_context":
+                # Asked for explicitly, so falling back would answer a question
+                # nobody asked and quietly poison an A/B against the other
+                # mechanism.
+                raise RuntimeError(
+                    f"{TAG}: pin_mech=motion_context but Motion-Context raised "
+                    f"({e!r}). Use pin_mech=auto to fall back to the AddGuide "
+                    "pixel pin."
+                ) from e
             print(
                 f"[{TAG}] Motion-Context pin failed ({e!r}); AddGuide pixel pin",
                 flush=True,
             )
-    if mc is None:
+    if mode == "addguide":
+        # Asked for. Saying "not available" here would be false, and it is the
+        # line a user would read while wondering why forcing it did nothing.
+        print(
+            f"[{TAG}] pin_mech=addguide: AddGuide pixel pin ({overlap_n}f)",
+            flush=True,
+        )
+    elif mc is None:
         print(
             f"[{TAG}] Motion-Context not available; AddGuide pixel pin "
             f"({overlap_n}f). Install ComfyUI-H3-Motion-Context for a latent join.",
@@ -1639,6 +1680,28 @@ class HandTieClips:
                         "rather than by edge."
                     ),
                 }),
+                # APPENDED, never inserted. `widgets_values` is a bare ordered
+                # array matched to this schema by index, so a widget added
+                # anywhere but the end silently reassigns every later value in
+                # every saved workflow. Adding options to an existing combo is
+                # safe; adding a widget is not.
+                "pin_mech": (["auto", "motion_context", "addguide"], {
+                    "default": "auto",
+                    "tooltip": (
+                        "Which mechanism pins hops 2+ to the previous hop. "
+                        "auto = Motion-Context when the pack is installed, the "
+                        "overlap has a matching context_length and the previous "
+                        "hop left a sampler latent; AddGuide pixels otherwise. "
+                        "Forcing one does not fall back -- it fails with the "
+                        "reason, because a lever that silently becomes the "
+                        "other setting cannot be compared against it. "
+                        "motion_context: latent join, no decode/re-encode. "
+                        "addguide: re-encodes decoded pixels, which is itself a "
+                        "VAE round trip and may scrub differently. The "
+                        "mechanism is in the per-hop cache key, so switching "
+                        "re-renders hops 2+ and leaves hop 1 on disk."
+                    ),
+                }),
             },
             "hidden": {
                 "unique_id": "UNIQUE_ID",
@@ -1705,6 +1768,7 @@ class HandTieClips:
             music_start_s=0.0, music_end_s=0.0, render_from=0,
             reference_video_desc="",
             reference_video_size=None,
+            pin_mech="auto",
             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
@@ -1868,6 +1932,24 @@ class HandTieClips:
                         "join at 5 s.",
                         flush=True,
                     )
+        # pin_mech=motion_context: both chain-wide preconditions checked before
+        # any sampling, so a forced setting fails on the queue rather than three
+        # hops in. The per-hop one (no sampler latent) cannot be known here and
+        # is raised by _pin_mech_for at the hop it affects.
+        if str(pin_mech) == "motion_context":
+            if _motion_context_cls() is None:
+                raise ValueError(
+                    f"{TAG}: pin_mech=motion_context but ComfyUI-H3-Motion-Context "
+                    "is not installed. Install it, or use pin_mech=auto for the "
+                    "AddGuide pixel pin."
+                )
+            if str(overlap_n) not in MC_CONTEXT_LENGTHS:
+                raise ValueError(
+                    f"{TAG}: pin_mech=motion_context but overlap {overlap} "
+                    f"({overlap_n} frames) has no Motion-Context context_length. "
+                    f"It accepts {', '.join(sorted(MC_CONTEXT_LENGTHS, key=int))} "
+                    "frames; pick an overlap with one of those, or use pin_mech=auto."
+                )
         for i, ln in enumerate(lengths):
             if overlap_n >= ln:
                 raise ValueError(
@@ -2327,7 +2409,8 @@ class HandTieClips:
             # must show staleness before queuing or it reads as a bug.
             hop_key = None
             cached = None
-            pin_mech_pred = _pin_mech_for(i, overlap_n, prev_sampled)
+            pin_mech_pred = _pin_mech_for(i, overlap_n, prev_sampled,
+                                          mode=str(pin_mech))
             pin_mech_used = pin_mech_pred
             if hop_store is not None:
                 hop_key = _store.hop_key(prev_key, {
@@ -2438,7 +2521,7 @@ class HandTieClips:
                     cond, pin_mech_used = _pin_continue(
                         cond, latent, vae, audio_vae, overlap_n,
                         pin_latent, prev_imgs, prev_audio,
-                        audio_ctx=audio_ctx,
+                        audio_ctx=audio_ctx, mode=str(pin_mech),
                     )
 
                 _offload_text_encoder(clip, model)

js/editor/run_panel.js

@@ -41,6 +41,11 @@ const GROUPS = [
                   "control_after_generate", "seed_per_shot",
                   "shift_video", "shift_audio"]],
     ["join & pin", ["hop_script", "pin_to_qwen", "ref_image_size",
+                    // pin_mech sits with the other pin dials even though it is
+                    // the newest widget on the node: the panel's order is
+                    // display only, and INPUT_TYPES appends it last so saved
+                    // workflows keep their widget indices.
+                    "pin_mech",
                     "audio_pin_frames", "pin_renorm", "pin_noise",
                     // tone_anchor sits next to the mode it modifies: it is
                     // read only when tone_compensate is `anchor`, and split

workflows/HandTieClips_Showcase.json

@@ -611,7 +611,8 @@
         0,
         0,
         "",
-        "MAX"
+        "MAX",
+        "auto"
       ],
       "title": "H3 Ref2VA Chain - showcase 6x7s"
     },

workflows/HandTieClips_Starter.json

@@ -614,7 +614,8 @@
         0,
         0,
         "",
-        "MAX"
+        "MAX",
+        "auto"
       ],
       "title": "H3 Ref2VA Chain - starter"
     },