0.4.4: fix what two models proved the prompt never said

An A/B of qwen and gemma on the same 3-hop brief, each given
prompt_pack/SYSTEM_PROMPT.md and nothing else, produced the same two
faults -- which makes them the prompt's, not the models'.

Both wrote @kitchen in a beat, exactly as rule 10 instructs, and then
invented "tag": "kitchen_plate" for the register, so the run stopped on
an unknown reference. The string _plate appears nowhere in the prompt;
two different model families reached the same convention independently.
The cause was in the file: rule 10's only concrete place tag sits in a
beat, the register example held one ref (a person, no place), 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.

qwen also 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 text encoder on two of three hops. Nothing
caught it -- check_prompts.py would have, but only for the two shipped
workflows.

- prompt: the register example now carries a place tag on both sides of
the round trip, and rule 10 says the two spellings are one string
- refs.py: reject an @tag in name, locked or context rather than
encoding it
- run panel: help text was read from widget.options.tooltip, which this
frontend does not populate, so every field the panel drew had no
tooltip while the native dials kept theirs. tooltipFor() tries the
widget and then the node definition.

Devlog section 22 has the A/B and the one difference no parser can see:
handed a hallway, one model moved rule 4's example refrigerator into it
and the other wrote a hallway light.

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

README.md

@@ -37,6 +37,19 @@ of a second, separate generation. The pack exists so that you cannot tell which.
 > `avcodec_open2`. Both fixed. The Starter now also ships the seam report wired.
 > Measurements are in [`docs/DEVLOG.md`](docs/DEVLOG.md) section 21.
 
+> **0.4.4 — 2026-08-30.** Two local models were given `prompt_pack/SYSTEM_PROMPT.md`
+> and the same scene, and both made the same two mistakes — so both were the
+> prompt's fault, not theirs. The register example had no place tag in it, so
+> each model invented its own convention (`kitchen_plate`) while leaving
+> `@kitchen` in the beat, and the run stopped on an unknown reference. One model
+> also wrote `"name": "@cook_face"` into `subjects`, which parsed, rendered, and
+> quietly put a literal at-sign in front of the text encoder on every
+> continuation hop. The prompt now shows a place tag on both sides of the round
+> trip and says the two spellings are one string; `refs.py` now rejects an
+> `@tag` in `name`, `locked` or `context` instead of encoding it. The RUN panel
+> also has its tooltips back — it read them from `widget.options`, where this
+> frontend does not keep them. Section 22 of the devlog has the A/B.
+
 **Writing for it:** [PROMPTING.md](PROMPTING.md) is the authoring guide — the rules that come from what this model actually does, not from taste. [prompt_pack/](prompt_pack/) has a copy-paste prompt that gets a language model to write plans for you.
 
 Each hop is native **MiniMax H3 Reference-to-Video**. Hops after the first are guided by the **previous hop's sampler AV latent** via `ComfyUI-H3-Motion-Context` when that pack is installed (22 picture frames + 24-frame end-aligned audio). Stock `MiniMaxH3AddGuide` is the fallback when Motion-Context is missing or the previous hop was a pixel cache hit. Voice stays as a reference every hop. Identity stills ride hop 1; later hops use the pin for wardrobe and room unless a ref lists those hops in `shots`. A 5 s hop drops the airlock on a continuous join — validate seams at 8 s or 15 s.

docs/DEVLOG.md

@@ -921,3 +921,51 @@ fast-preview button it sounds like. `dry_run` is the fast-preview button.
   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.

js/editor/run_panel.js

@@ -13,12 +13,14 @@
  * is byte-identical to one produced by the stock UI, and anything this panel
  * cannot express is still reachable by dropping it from the group list.
  *
- * Help text is read from `widget.options.tooltip`, i.e. the `tooltip` written in
- * INPUT_TYPES. Retyping those sentences here would be a second copy that goes
- * stale, for exactly the reason routes.py exists.
+ * Help text comes from the `tooltip` written in INPUT_TYPES, via
+ * `tooltipFor()`. Retyping those sentences here would be a second copy that
+ * goes stale, for exactly the reason routes.py exists. Reading only
+ * `widget.options.tooltip` was not enough and left the whole panel with no
+ * tooltips at all while the native dials kept theirs -- see tooltipFor().
  */
 
-import { el, widgetByName, widgetType, widgetOptions } from "./widget_utils.js";
+import { el, widgetByName, widgetType, widgetOptions, tooltipFor } from "./widget_utils.js";
 
 const OPEN_PROP = "h3_run_open";
 
@@ -257,8 +259,16 @@ export function createRunPanel(node, { onChange, suppressed, hopCount } = {}) {
                 l.appendChild(el("span", null, labelFor(w)));
                 l.appendChild(f.input);
                 // The tooltip is the widget's own, straight from INPUT_TYPES.
-                const tip = widgetOptions(w).tooltip;
-                if (tip) l.title = String(tip);
+                // Set on the label, which wraps both the caption and the
+                // control, so the hover target is the whole field rather than
+                // the six pixels of text. `title` on the input as well because
+                // a DOM <select>/<input> does not always inherit the ancestor's
+                // tooltip while it has focus.
+                const tip = tooltipFor(node, w);
+                if (tip) {
+                    l.title = tip;
+                    f.input.title = tip;
+                }
                 grid.appendChild(l);
                 owned.push(name);
                 readers.push(f.read);

js/editor/widget_utils.js

@@ -165,6 +165,30 @@ export function widgetByName(node, name) {
     return node.widgets?.find((w) => w.name === name) || null;
 }
 
+/**
+ * The `tooltip` a widget was given in INPUT_TYPES, wherever this frontend
+ * keeps it.
+ *
+ * `widgetOptions(w).tooltip` on its own is not enough, and returned nothing
+ * for the entire RUN panel: ComfyUI's own tooltip layer does not read the
+ * widget object at all, it reads the node DEFINITION. So every native dial
+ * showed its help text while every field this editor drew showed none, which
+ * reads as "the panel has no tooltips" rather than as a lookup miss.
+ *
+ * Which of the three places holds the string depends on the frontend version,
+ * so all three are tried instead of pinning one. Never retype the sentences
+ * here: INPUT_TYPES is the single source, for the same reason routes.py exists.
+ */
+export function tooltipFor(node, w) {
+    if (!w) return "";
+    const direct = w.tooltip || widgetOptions(w).tooltip;
+    if (direct) return String(direct);
+    const spec = node?.constructor?.nodeData?.input;
+    const entry = spec?.required?.[w.name] || spec?.optional?.[w.name];
+    const tip = Array.isArray(entry) ? entry[1]?.tooltip : null;
+    return tip ? String(tip) : "";
+}
+
 /** Hide every widget in `names`, show the rest of `names`' complement set. */
 export function setWidgetVisibility(node, hiddenNames) {
     const hide = new Set(hiddenNames);

prompt_pack/AUTHORING_PROMPT.md

@@ -102,6 +102,11 @@ These are not style preferences. They are how this model fails.
    write reaches the encoder literally, so formatting becomes noise in the
    conditioning.
 
+   **The tag in the beat and the `tag` in the register are the same string,
+   character for character.** Writing `@kitchen` in a beat commits you to
+   `"tag": "kitchen"` in `ref_plan` -- not `kitchen_plate`, not `kitchen_ref`.
+   Decide the name once and use it in both documents.
+
 11. **Every object that persists gets an adjective.** A bare noun is
    unanchored: each hop encodes "the bowl" from scratch and is free to make it
    steel in one hop and porcelain in the next. Name a colour or a material the
@@ -249,7 +254,10 @@ then pinned into the next hop's audio.
   "refs": [
     {"tag": "hero_face", "file": "face.jpg", "subject": 1,
      "retention": "fully_preserved", "shots": [1, 4],
-     "desc": "head-and-shoulders, even light"}
+     "desc": "head-and-shoulders, even light"},
+    {"tag": "kitchen", "file": "kitchen_wide.jpg",
+     "retention": "reference", "shots": [1, 2, 3],
+     "desc": "wide shot of the counter and window"}
   ],
   "subjects": {
     "1": {"name": "the cook",
@@ -259,6 +267,17 @@ then pinned into the next hop's audio.
 }
 ```
 
+The place entry is `"tag": "kitchen"` because the beat says `@kitchen`. **The
+two spellings are one string.** Naming the register entry `kitchen_plate`,
+`kitchen_ref` or `kitchen_bg` while the beat still reads `@kitchen` stops the
+run: the node resolves tags by exact name and has no way to guess that two
+different words meant the same picture.
+
+`subjects` holds **plain prose, never tags.** `name` is the phrase that replaces
+a subject's `@tag` from hop 2 on, so `"name": "@hero_face"` would resolve to
+itself and put a literal at-sign in front of the encoder. Write `"the cook"`.
+The same goes for `locked` and `context`.
+
 Valid ref fields: `tag`, `file`, `subject`, `retention`, `desc`, `shots`. (There
 is also `slot`, which is derived from list position — never author it.)
 

prompt_pack/SYSTEM_PROMPT.md

@@ -89,6 +89,11 @@ These are not style preferences. They are how this model fails.
    write reaches the encoder literally, so formatting becomes noise in the
    conditioning.
 
+   **The tag in the beat and the `tag` in the register are the same string,
+   character for character.** Writing `@kitchen` in a beat commits you to
+   `"tag": "kitchen"` in `ref_plan` -- not `kitchen_plate`, not `kitchen_ref`.
+   Decide the name once and use it in both documents.
+
 11. **Every object that persists gets an adjective.** A bare noun is
    unanchored: each hop encodes "the bowl" from scratch and is free to make it
    steel in one hop and porcelain in the next. Name a colour or a material the
@@ -236,7 +241,10 @@ then pinned into the next hop's audio.
   "refs": [
     {"tag": "hero_face", "file": "face.jpg", "subject": 1,
      "retention": "fully_preserved", "shots": [1, 4],
-     "desc": "head-and-shoulders, even light"}
+     "desc": "head-and-shoulders, even light"},
+    {"tag": "kitchen", "file": "kitchen_wide.jpg",
+     "retention": "reference", "shots": [1, 2, 3],
+     "desc": "wide shot of the counter and window"}
   ],
   "subjects": {
     "1": {"name": "the cook",
@@ -246,6 +254,17 @@ then pinned into the next hop's audio.
 }
 ```
 
+The place entry is `"tag": "kitchen"` because the beat says `@kitchen`. **The
+two spellings are one string.** Naming the register entry `kitchen_plate`,
+`kitchen_ref` or `kitchen_bg` while the beat still reads `@kitchen` stops the
+run: the node resolves tags by exact name and has no way to guess that two
+different words meant the same picture.
+
+`subjects` holds **plain prose, never tags.** `name` is the phrase that replaces
+a subject's `@tag` from hop 2 on, so `"name": "@hero_face"` would resolve to
+itself and put a literal at-sign in front of the encoder. Write `"the cook"`.
+The same goes for `locked` and `context`.
+
 Valid ref fields: `tag`, `file`, `subject`, `retention`, `desc`, `shots`. (There
 is also `slot`, which is derived from list position — never author it.)
 

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "comfyui-hand-tie-clips"
-version = "0.4.3"
+version = "0.4.4"
 description = "Native MiniMax H3 Ref2VA chain: persistent references, previous-segment clip+audio pin, one queue."
 readme = "README.md"
 # SPDX string, not `{ file = "LICENSE" }`. The registry does not resolve the file

refs.py

@@ -75,11 +75,30 @@ def _norm_subject(key, raw):
     if unknown:
         _fail(f"subject {num}: unknown field(s) {unknown}. "
               f"Valid: {list(SUBJECT_FIELDS)}")
-    return num, {
+    out = {
         "name": str(raw.get("name") or "").strip(),
         "locked": str(raw.get("locked") or "").strip(),
         "context": str(raw.get("context") or "").strip(),
     }
+    # All three fields are PROSE that reaches the encoder verbatim -- `name`
+    # is what `resolve_tags` substitutes for a subject's tag on hop 2+, and
+    # `locked`/`context` are copied into the continuity line. A reference tag
+    # written here therefore resolves to itself: a model that wrote
+    # `"name": "@cook_face"` put a literal at-sign into the conditioning of
+    # every continuation hop, and nothing anywhere caught it -- the plan
+    # parsed, the tags resolved, the render completed, and two of three hops
+    # were conditioned on a token no one intended. Loud here, or silent
+    # forever.
+    import re                       # local, as everywhere else in this module
+    for field, text in out.items():
+        hit = re.search(r"@[A-Za-z0-9_]+", text)
+        if hit:
+            _fail(f"subject {num}: `{field}` contains the reference tag "
+                  f"'{hit.group(0)}'. These fields are prose that reaches the "
+                  f"text encoder literally -- @tags only resolve inside a "
+                  f"shot's beat. Write the plain words instead, e.g. "
+                  f"\"the cook\".")
+    return num, out
 
 
 def _norm_ref(raw, i):