writer: count speech in the unit the line is written in

First live write after the lead-in lint shipped was the proof it wanted: asked
for a 3-hop Korean vlog, the writer opened every hop with a named sound before
the line, and the lint stayed quiet on all three -- correctly.

The same run broke the length arithmetic. 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.2s against a
real 4-5s, warned on all three hops when two were fine, and told the author to
write "roughly 25 words" -- about 85 syllables in Hangul, three times the hop.

speech_seconds() 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 no longer counts
as a spoken word, which was buying every CJK line most of a second. The warning
and build_user_turn both name the target in the line's own unit.

Neither rate is measured on this model; DEVLOG 33 says so.

Also: docs/HANDOVER_*.md untracked and gitignored. They are working notes
between sessions, they name machine specifics, and one is always the live
queue -- kept on disk, out of the repo.

All 9 checks pass.

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

.gitignore

@@ -15,3 +15,8 @@ node.zip
 
 # Local LLM connection settings -- a machine property, not a release.
 htc_llm.json
+
+# Session handover docs. Working notes between sessions -- they name renders,
+# dead ends and machine specifics, and one of them is always the live queue.
+# The root HANDOVER.md was already ignored; these are the same thing, dated.
+docs/HANDOVER_*.md

docs/DEVLOG.md

@@ -1774,3 +1774,30 @@ smile and the wave are what filled the frames.
 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.

docs/HANDOVER_2026-09-01.md

@@ -1,314 +0,0 @@
-# Handover — 2026-09-01 (trim bars → LM branch → merge) — CLOSED
-
-**Superseded by `docs/HANDOVER_2026-09-02.md`.** Soundtrack + LM + texture are
-on local `main`; Grok's live queue is the writer-rail/vision leftover. Keep
-this file as the closed task list. Do not resume the merge.
-
-Written for a second agent (Grok) to pick up mid-flight. Root `HANDOVER.md`
-is still the general orientation doc.
-
-Read order if you need the closed queue: this file, then `CLAUDE.md`, then
-`docs/DEVLOG.md` §30.
-
-**Closed 2026-09-02.** TASK 1 `19cd072`. TASK 2.6 bit-identical vs `efd6a3e`;
-2.8 widgets are a prefix. TASK 3 4b `b81504e`; 4a eviction confirmed live.
-TASK 4 merge on `main` (`185f1f4`+). Not pushed.
-
----
-
-## 0. Rules that are not negotiable
-
-These are not style preferences. Each one has already cost a session.
-
-1. **`widgets_values` is positional.** New widgets go at the **bottom** of
-   `optional`, never in the middle, or every saved workflow silently misaligns.
-   `tools/check_workflows.py` catches it — it has caught it three times.
-2. **Never `rm` untracked things.** The `.bak` pile, `input/h3_refs/` media,
-   `user/default/workflows/`. Move to `D:\ComfyUI\_disabled_custom_nodes\`.
-3. **No `subprocess` anywhere in this pack.** It is registry-scanned and was
-   flagged `python_command_injection_risk` for 0.4.1–0.4.3. `llm.py`'s docstring
-   spells this out.
-4. **aiohttp handlers share ComfyUI's event loop.** Anything that decodes,
-   reads a file or talks to a model goes through `run_in_executor`. Blocking it
-   freezes the canvas, the queue and the progress bar together.
-5. **Never disable Smart App Control** on this machine — it is a one-way door
-   that requires a clean Windows reinstall. If an unsigned `.pyd` is blocked,
-   change the package version instead. (This is why the audio decoder is PyAV,
-   which is already installed and proven, and not `torchcodec`.)
-6. **Do not pass `--token` to `comfy node publish`** — it lands in
-   `PSReadLine\ConsoleHost_history.txt`. Let it prompt.
-7. Python is `D:/ComfyUI/venv/Scripts/python.exe`. PowerShell 5.1 — no `&&`.
-8. `user/default/workflows/*.json` are on legacy node ids **on purpose**. Do
-   not migrate them.
-
----
-
-## 1. State
-
-| | |
-|---|---|
-| path | `D:\ComfyUI\custom_nodes\ComfyUI-Hand-Tie-Clips` |
-| current branch | **`soundtrack`**, 5 commits ahead of `main`, **not pushed** |
-| `main` | `d07b19b` — 0.4.5, pushed to both remotes |
-| also open | `texture-ratchet` (3 ahead, pushed), `llm-plan-writer` (9 ahead, **not pushed**) |
-| working tree | clean at `082eb91` |
-
-```
-082eb91  the trim bar, and the rail's pixel budget
-a2cfa42  trim windows on every media input, and a per-reference pixel budget
-efd6a3e  media: decode audio with PyAV, because torchaudio.load no longer decodes
-6c5d3ea  soundtrack: put it in the panel, where the other media already lives
-7d5c81d  soundtrack: a music bed under the chain, ducked under the dialogue
-```
-
-All six checkers on this branch pass:
-
-```
-D:/ComfyUI/venv/Scripts/python.exe tools/check_waveform.py
-D:/ComfyUI/venv/Scripts/python.exe tools/check_music.py
-D:/ComfyUI/venv/Scripts/python.exe tools/check_workflows.py
-D:/ComfyUI/venv/Scripts/python.exe tools/check_features.py
-D:/ComfyUI/venv/Scripts/python.exe tools/check_prompts.py
-D:/ComfyUI/venv/Scripts/python.exe tools/check_templates.py
-```
-
-Run all six before every commit. There is no JS runtime on this machine (no
-node, no deno), so **JavaScript is verified only by opening the browser** —
-say so plainly rather than claiming a JS change is tested.
-
-**What shipped in these 5 commits:** a music bed mixed under the finished
-chain; the soundtrack as a filename in the MEDIA strip (its AUDIO socket
-remains, and wins when both are set); PyAV audio decoding; trim windows
-(`in`/`out` seconds) on the reference clip, the voice and the soundtrack, with
-a waveform scrub bar per slot; and a per-reference megapixel cap in the
-REFERENCES rail. Rationale for all of it: `docs/DEVLOG.md` §30.
-
----
-
-## 2. TASK 1 — the bar does not appear until the browser is refreshed
-
-**Confirmed by the user, 2026-09-01:** "after inserting a ref clip/audio/
-soundtrack, i have to refresh the browser before it appears. visually all the
-bars are moving well though." So the control itself works; only its first
-appearance is wrong.
-
-**Cause, and it is certain — no guessing needed.** In
-`js/h3_ref_chain_ui.js:126`, the media strip is constructed with
-`onChange: () => node.graph?.setDirtyCanvas?.(true, true)`. That repaints the
-litegraph node; it does **not** re-render this DOM. `createMediaStrip`'s own
-`render()` is called once at construction (`media_strip.js:136`) and then only
-from the UI's own render path. A trim bar is `display: none` until its file has
-a name (`trim_bar.js:261`), so picking a file leaves the bar hidden until a
-reload rebuilds the strip. The header `count` ("none set" / "2 set") is stale
-for exactly the same reason.
-
-**The fix, in `js/editor/media_strip.js` only.** Four edits:
-
-1. Line 16 — also import the cache-drop helper, which already exists and is
-   currently imported by nobody:
-
-```js
-import { createTrimBar, forgetPeaks } from "./trim_bar.js";
-```
-
-2. Add these two functions **above** the `for (const [name, kind, ...] of SLOTS)`
-   loop (i.e. after `let missing = 0;`):
-
-```js
-    function syncCount() {
-        let set = 0;
-        for (const [name] of SLOTS) {
-            if (String(widgetByName(node, name)?.value || "")) set += 1;
-        }
-        count.textContent = set ? `${set} set` : "none set";
-    }
-
-    // The bars and the header, deliberately NOT the pickers: this runs from
-    // inside a picker's own `set`, and re-entering that picker's render in the
-    // middle of its own callback is how you get a control that fights itself.
-    function afterPick() {
-        syncCount();
-        for (const b of bars) b.render();
-    }
-```
-
-3. In the picker construction (currently `set: (v) => commit(node, w, v),`),
-   redraw after the commit:
-
-```js
-            // A pick has to redraw the bar under it. The strip's `onChange` is
-            // only `setDirtyCanvas`, which repaints the litegraph node and not
-            // this DOM, so before this a newly picked file left its bar hidden
-            // until a browser reload rebuilt the strip from scratch.
-            //
-            // `forgetPeaks` because the client cache is keyed by NAME while the
-            // route's is keyed by (name, mtime): re-uploading different audio
-            // under a basename already on the canvas would otherwise draw the
-            // old file's waveform over the new one's duration.
-            set: (v) => { commit(node, w, v); forgetPeaks(v); afterPick(); },
-```
-
-4. `render()` loses its inlined counting and calls `syncCount()` instead —
-   one definition of the count, not two:
-
-```js
-    function render() {
-        syncCount();
-        for (const p of pickers) p.render();
-        for (const b of bars) b.render();
-    }
-```
-
-**Verify (browser, no restart needed — it is JS only; hard-reload the tab):**
-open the panel, MEDIA tab, pick a voice file. The waveform row must appear
-immediately, the header must go to "1 set", and the grips must drag on the
-first try. Then pick a *different* file into the same slot: the waveform must
-change. No F5 at any point.
-
-**Do not** fix this by calling the strip's full `render()` from the picker, and
-**do not** re-render anything while a grip is being dragged — rebuilding the
-DOM destroys the pointer-captured element and the drag dies halfway. That rule
-is why the bar paints its grips directly during a drag and only calls `set()`
-on release.
-
-Commit alone, on `soundtrack`:
-`media: a picked file redraws its own bar, without a reload`
-
----
-
-## 3. TASK 2 — verification the user must run (agents cannot do these)
-
-Nothing has been rendered since `efd6a3e`. These are from the approved plan and
-each needs a human at the ComfyUI GUI. **Restart ComfyUI first** — there are new
-Python widgets and new JS modules. Before any A/B, set
-`control_after_generate=fixed`.
-
-3. **Header-lie check.** Peaks route against `Track 2 master test.mp3`;
-   `seconds` must be ≈ **173.5**, not a doubled Xing figure. (173.49 s is the
-   decoded truth, already measured.)
-4. **Trim a voice.** Same seed, same everything, voice trimmed to a different
-   6 s window. The render **must** differ — that is the proof it reaches the
-   conditioning — and the console must report a hop-cache miss.
-5. **Trim the soundtrack** to a window recognisable by ear; the bed must start
-   there, not at 0.
-6. **Null check.** Every window at 0/0 → bit-identical to a render from
-   `efd6a3e`. Untouched inputs must cost nothing.
-7. **Per-ref mp.** Drop one reference to 0.3 MP; `info` must name the resize and
-   the hop cache must miss.
-8. **Old workflow.** Load one saved before this change; confirm no widget
-   shifted.
-
-If 4 or 6 fails, stop and report — that is the half where being wrong is
-*silent*, and it is worth more than any new feature.
-
----
-
-## 4. TASK 3 — the LM branch (`llm-plan-writer`)
-
-Nine commits ahead of `main`, never pushed, an **alpha**. It adds an LM Studio
-plan writer: `llm.py` (647), `planner.py` (371), `js/editor/writer_bar.js`
-(311), `routes.py` +162, `tools/check_planner.py` (322),
-`tools/grade_plan.py` (368), `tools/check_all.py` (93), DEVLOG §29.
-
-```
-0faf168  llm: keep the writer warm, and evict it when a render is queued
-68b13a4  tools: check_all.py, the pre-commit sweep that kept being retyped
-edc1f8f  writer bar: the model dropdown now actually selects the model
-6d1996d  planner: warn when the final shot leaves `tail` unset
-440ffcb  tools: rescue grade_plan.py from a scratch directory
-fcbaf66  ALPHA: a Free VRAM killswitch, not just an automatic unload
-2450d96  ALPHA: the panel writes and repairs its own plans
-```
-
-Two items are open on it. **Read `llm.py`, `planner.py` and the branch's
-`CLAUDE.md` before touching either** — they were queued in an earlier session
-and `2450d96` may already have moved the ground under the second one.
-
-**4a. Warm/evict timing check (measurement, not code).** `0faf168` keeps the
-writer resident between plans and evicts it when a render is queued;
-`h3_ref_chain.py`'s `run()` calls `llm.free_for_render()` as its first act,
-blocking on purpose (it is the execution worker thread, not the event loop).
-What has never been measured is whether the wait is long enough on this card:
-write a plan, queue a render immediately, and confirm from the console that the
-eviction is reported *and* the diffusion load does not OOM. The dial if it is
-short is the post-evict wait in `llm.py`'s config block (near `keep_warm`), and
-the honest fix is a longer wait, not a smaller model.
-
-**4b. "Suggest, don't set."** The writer currently writes plan fields directly.
-The intent recorded earlier is that it should *propose* and the user accept —
-the model is a drafting aid, and a plan silently rewritten under you is worse
-than no plan. Confirm the current behaviour first; if `2450d96` already
-proposes rather than writes, close this item in the DEVLOG rather than
-building it twice.
-
----
-
-## 5. TASK 4 — the merge, and what will conflict
-
-Order: verify `soundtrack` (§3) → merge to `main` → then merge
-`llm-plan-writer` → then `texture-ratchet`. Do not merge anything before the
-null check in §3 passes.
-
-**Known conflicts when `llm-plan-writer` meets `soundtrack`/`main`:**
-
-- **`h3_ref_chain.py`, the top of `run()`** — the real one. `llm-plan-writer`
-  inserts its `free_for_render()` block immediately after the `run()`
-  signature, and `soundtrack` has lengthened that signature by seven
-  parameters (`soundtrack_file`, then the six window floats). **Resolution:
-  keep `soundtrack`'s longer signature verbatim, and put the LM block at the
-  top of the body.** Do not let a merge tool drop a parameter — that is a
-  silent `widgets_values` misalignment in every saved workflow.
-- **`routes.py`** — both branches append routes. Keep both.
-- **`js/h3_ref_chain_ui.js`, `js/h3_ref_chain.css`** — both append. Keep both.
-- **`docs/DEVLOG.md`** — §29 is on `llm-plan-writer`, §30 on `soundtrack`.
-  Keep both, in number order.
-- **`CLAUDE.md`** — both add sections. Keep both.
-
-**Then register the new checkers.** `tools/check_all.py` exists only on
-`llm-plan-writer` and does not know about `check_music.py`,
-`check_texture.py` (on `texture-ratchet`) or `check_waveform.py`. Add all
-three once the branches are together, and confirm `check_all.py` runs green.
-
----
-
-## 6. Also open, not scheduled
-
-- **`pin_renorm=band` A/B** on `texture-ratchet`: 3 hops,
-  `control_after_generate=fixed`, `cache_hops=on`, read the face box with
-  `tools/texture_probe.py --box`. Baseline is ×1.042 per join.
-- **`match_band` partial pull** — mirror `tone.anchor_pull`'s
-  `ANCHOR_STRENGTH = 0.35`, **only** if faces go waxy after that A/B.
-- **A crop box for the first frame.** `MiniMaxH3AddGuide` does
-  `_resize(image, width, height, "center")`, so a 9:16 source on a 16:9 canvas
-  silently loses both sides. A megapixel control there would be inert — this is
-  the control it actually lacks. Noted, not planned.
-- **Nothing on `soundtrack` or `llm-plan-writer` is pushed.** The remote has
-  only `main` and `texture-ratchet`.
-- Six `.npy` scratch files remain in `D:\downloads\`.
-
----
-
-## 7. Facts worth not re-deriving
-
-- The pack's media story is **filenames, not sockets**. Sixteen sockets were
-  collapsed to five; `start_image_file` / `reference_video_file` / `voice_file` /
-  `soundtrack_file` are STRING widgets naming files under
-  `<ComfyUI input>/h3_refs`.
-- **torchaudio ≥ 2.9 cannot decode.** `torchaudio.load` is a thin wrapper over
-  `torchcodec`, which is not installed, so it raised on every file — this had
-  been silently breaking `voice_file` too, not just the soundtrack.
-  `torchaudio.functional.resample` still works. Audio decoding is PyAV now.
-- **`_encode_ref_audio` has no cap** (`comfy_extras/nodes_minimax_h3.py:71`).
-  The whole voice file becomes latent frames the DiT attends over on every step
-  of every hop. This is why trimming the voice is a cost fix, not a convenience.
-- **`chain_salt` digests tensors, not filenames or settings.** So trim windows
-  and per-reference megapixels are hop-cache-correct with zero cache changes: a
-  trimmed voice is simply a different tensor.
-- **`end == 0` means "to the end of the file."** `media.clip_window()` is the
-  single definition, shared by four readers, and it can never return an empty
-  span — reversed, negative, past-the-end and shorter-than-50 ms all fall back
-  to the whole file.
-- **Peaks are bucket-`max`, not mean.** A mean flattens transients, and
-  transients are the only landmarks you can trim against.
-- Bash heredocs in this environment mangle backslashes. Write scripts
-  containing regex escapes to a file instead.

docs/HANDOVER_2026-09-02.md

@@ -1,186 +0,0 @@
-# Handover — 2026-09-02 (merged main, writer looks at the rail)
-
-Written by Grok for Claude to take over. Root `HANDOVER.md` is orientation.
-`docs/HANDOVER_2026-09-01.md` is the **closed** soundtrack/LM/merge queue.
-This file is **the live queue** and supersedes both wherever they disagree.
-
-Read order: this file, then `CLAUDE.md`, then `docs/DEVLOG.md` §29 (writer)
-and §30 (trim / null check). Plan files under `~/.claude/plans/` are historical.
-
----
-
-## 0. Where you are
-
-| | |
-|---|---|
-| path | `D:\ComfyUI\custom_nodes\ComfyUI-Hand-Tie-Clips` |
-| branch | **`main`** at `495335d` *writer: desc and context are the point of looking* |
-| remotes | **not pushed.** `main` is **35 commits ahead of `origin/main`** (`d07b19b`, 0.4.5) |
-| working tree | clean |
-| version | `pyproject.toml` still **0.4.5** — no bump, no publish |
-| JS | `js/h3_ref_chain_ui.js` `VERSION = "v1.5.3"` |
-| Python | `D:/ComfyUI/venv/Scripts/python.exe` |
-| shell | PowerShell 5.1 — no `&&` |
-
-```
-495335d  writer: desc and context are the point of looking     ← HEAD, untested in GUI
-1fb2293  writer: empty subjects is a patch, not a rewrite
-2077f42  writer: the rail's pictures are the scene
-406e242  schema: the planner knows about per-ref mp
-185f1f4  Merge branch 'texture-ratchet'
-c810f83  Merge branch 'llm-plan-writer'
-3def9a0  docs: TASK 2 null check and old-workflow widgets passed
-```
-
-`soundtrack` (`3def9a0`) and `llm-plan-writer` (`b81504e`) are **merged and stale**. Do not commit on them. `texture-ratchet` is on origin; its commits are in `main` via `185f1f4`.
-
-**Restart ComfyUI and hard-reload the tab before any GUI check.** Python + JS both changed. The last live Write-plan the user saw was **before** `495335d`.
-
----
-
-## 1. Rules that are not negotiable
-
-Same as 09-01. Each has already cost a session.
-
-1. **`widgets_values` is positional.** New widgets at the **bottom** of `optional` only. `tools/check_workflows.py` is the catcher.
-2. **Never `rm` untracked things.** Move to `D:\ComfyUI\_disabled_custom_nodes\`.
-3. **No `subprocess` in this pack** (registry `python_command_injection_risk`). `tools/check_all.py` may use it; `llm.py` / `store.py` must not.
-4. **aiohttp handlers share the event loop.** Decode / disk / model I/O goes through `run_in_executor`.
-5. **Never disable Smart App Control.**
-6. **Do not pass `--token` to `comfy node publish`.**
-7. Python / PowerShell as above.
-8. `user/default/workflows/*.json` stay on **legacy node ids** (`H3RefChain`). Do not migrate them.
-
-Checkers before every commit:
-
-```
-D:/ComfyUI/venv/Scripts/python.exe tools/check_all.py
-```
-
-Nine children: templates, prompts, waveform, music, texture, workflows, features, planner, `gen_schema.py --check`. All green at `495335d`.
-
-No node/deno on this machine. **JS is verified only in the browser.** Say so; do not claim a JS change is tested.
-
----
-
-## 2. Closed — do not redo
-
-### Merge (TASK 4 from 09-01)
-
-Order was: verify soundtrack → `main` ← soundtrack ← llm-plan-writer ← texture-ratchet.
-
-Done on local `main`. Conflicts resolved as specified:
-
-- `h3_ref_chain.py` `run()`: **soundtrack's longer signature kept** (`soundtrack` … `music_end_s`), `llm.free_for_render()` at the **top of the body**.
-- `routes.py` / JS / CSS: both sides kept.
-- DEVLOG: §§24–30 in number order.
-- `check_all.py` taught music / waveform / texture.
-- Planner schema knows per-ref `mp` (`406e242`).
-
-### TASK 1 — trim bar first appearance
-
-`19cd072`. User signed off.
-
-### TASK 2 — GUI verification (soundtrack vs `efd6a3e`)
-
-| # | item | result |
-|---|---|---|
-| 2.3 | Header-lie (peaks `seconds` ≈ 173.5 on *Track 2 master test.mp3*) | pass (user) |
-| 2.4 | Voice trim reaches encoder | pass; male timbre will not override a woman in frame at 8-step turbo |
-| 2.5 | Soundtrack mix | pass (user; −6 dB under speech) |
-| 2.6 | Null check 0/0 vs `efd6a3e` | **pass, bit-identical hops** |
-| 2.7 | Per-ref mp | pass (user) |
-| 2.8 | Old workflow widgets | **pass** — names from 0.4.5 (34) and `efd6a3e` (39) are a prefix of 45 |
-
-**2.6 detail (do not re-render).** A's graph vs `efd6a3e` with every window 0/0, empty `voice_file` / `soundtrack_file`. Hop 1 and hop 2 FFV1 frames and `.npy` audio identical (contact_sheet_00039 vs 00043; pin σ 0.9578/0.4434). Hop **keys** differ because this tree added `voice_on`; that is a key-field change, not a generate change.
-
-Two agent B renders **did not count**: Starter graph without Parasyte LoRA, and a beat truncated at the 400-char hop-meta. Real B used A's API prompt from `contact_sheet_00039_.png` metadata.
-
-A's copies: `D:\downloads\_nullcheck_A\`.
-
-### TASK 3 4b — suggest, don't set
-
-`b81504e`. Write plan holds a draft; Accept writes widgets; Discard leaves cards. Still the rule.
-
-### TASK 3 4a — warm/evict vs OOM
-
-**Measured this session, pass.** Keep-warm was on. Queue called `free_for_render`. LM Studio log: `POST /api/v1/models/unload`. User: "the model did get evicted." No OOM reported.
-
-The bug that made eviction a no-op: `asyncio.run(unload_all(...))` inside ComfyUI's **already-running** execute loop → `RuntimeError` + `coroutine never awaited`. Fixed in `2077f42` as `llm._run_coro` (side thread, own loop). Proven offline in `tools/check_planner.py` (`free_for_render from a running loop does not raise`).
-
----
-
-## 3. LIVE — writer looks at the rail (take over here)
-
-User intent: pictures already in the REFERENCES boxes are the scene. Write plan must look at them (vision), keep those tags/files, fill retention / subject / desc / subjects from the stills + the brief. Not pick other files from `h3_refs`.
-
-### What landed
-
-| commit | what |
-|---|---|
-| `2077f42` | POST current rail rows; pin tags+files; attach JPEG stills on attempt 1; vision 400 → filenames-only fallback |
-| `1fb2293` | empty `subjects: {}` is a subjects-only repair + merge; stub name/locked from desc after 3 misses; panel shows a partial draft on give-up |
-| `495335d` | **untested in GUI.** Empty values do not wipe a filled register. Pinned writes **require** `desc` on every ref and `name`/`locked`/`context` on every subject |
-
-Key files: `js/editor/writer_bar.js` (`railRefs()`), `routes.py` (`_pinned_refs`, executor encode), `planner.py` (`build_user_turn` pinned path, `attach_images`, `_merge_register`, validate), `llm.py` (multimodal `content`, `_nudge_no_think`, `_run_coro`), `media.py` (`vision_data_url`, `VISION_SIDE = 1024`).
-
-No new `INPUT_TYPES`. Draft still waits for Accept.
-
-### Last live run (before `495335d`)
-
-User: two random stills in the rail (`pic2_1.jpg` girl, `h3_stress_kitchen_2.jpg` kitchen), both rows still on setting/prop + reference, brief about a beautiful Asian girl talking, 2 hops. Qwen3.8-27b-uncensored (VLM, JIT-loaded).
-
-**Worked:** tags/files kept; `@ref_1` became Subject 1 / fully preserved; `@ref_2` stayed setting/reference; shots listed 1 and 2; script was a talking scene; vision parts were in the POST (`image_url` data-URLs); model evicted on queue.
-
-**Failed:** `desc` on both refs and `context` on Subject 1 stayed empty. Subject name/locked were the **stub** (`the person` / `the same face and hair`) because qwen emitted `"subjects": {}` on every attempt, including a repair that re-sent refs **without** `desc` and wiped attempt 1's `"head and shoulders, even light"`.
-
-LM Studio also logged: `Qwen-VL models require at minimum 1024 image tokens` (`--image-min-tokens 1024`). `VISION_SIDE` is now 1024 px; that is pixels, not llama.cpp image tokens. If desc/context stay generic after `495335d`, the next lever is LM Studio's load flag `--image-min-tokens 1024`, not more prompt text.
-
-### Your first GUI job
-
-1. Restart ComfyUI, hard-reload. Confirm console `[HandTieClips] editor ui v1.5.3 loaded`.
-2. Same two pictures, same brief, hops=2, duration **7 s** is the RUN panel not the hops box.
-3. Write plan. Expect:
-   - same two filenames, same tags
-   - `@ref_1` fully_preserved + subject 1
-   - `@ref_2` reference, no subject
-   - **non-empty `desc` on both rows** (one sentence of what the photo shows)
-   - Subject 1: `name` + `locked` + **`context`** (wardrobe/pose), not the stub
-4. If the status line says *filled from the photo descriptions*, the model still omitted prose and we stubbed — read the three boxes before Accept.
-5. Accept, queue, confirm unload line `[HandTieClips] freed the writer` (or silent if already unloaded).
-
-If desc/context are still stub/empty after that, the structured-output schema still lets `"subjects": {}` and omitted `desc` through. Do **not** put vision rules in `SYSTEM_PROMPT.md` (that file is also the manual LM Studio paste). Keep pinning + "look at the stills" in `build_user_turn`. A tighter repair that asks **only** for `desc`/`context` (and merges) is the next code move; a second tiny vision turn is the one after that.
-
-Do not scan the whole `h3_refs` folder with vision. Do not auto-Accept.
-
----
-
-## 4. Open, not the writer
-
-- **`pin_renorm=band` A/B** (was texture-ratchet, now on `main`): 3 hops, `control_after_generate=fixed`, `cache_hops=on`, `tools/texture_probe.py --box`. Baseline +4.2% mid-band per join. `sigma` is a no-op / wrong way; `band` is the lever. Only pull `match_band` toward `tone.anchor_pull`'s 0.35 **if faces go waxy**.
-- **First-frame crop box.** `MiniMaxH3AddGuide` center-crops; a 9:16 still on 16:9 loses the sides. Noted, not planned. A megapixel cap there is inert.
-- **Push.** Nothing on `main` is on GitHub/HF except the old 0.4.5. If the push touches `docs/img/`: `git lfs push https://github.com/dntpi/ComfyUI-Hand-Tie-Clips.git main` **then** `git push origin main`. `origin` has two push URLs; LFS only follows the first.
-- **Version / publish.** Still 0.4.5. Do not `comfy node publish` with `--token`.
-- **`user/default/workflows`** remain legacy `H3RefChain`. Shipped examples are `workflows/HandTieClips_Starter.json` / `_Showcase.json` (45 widgets).
-
----
-
-## 5. Facts worth not re-deriving
-
-- Pack media is **filenames under `<input>/h3_refs`**, not sockets. `end==0` means to EOF; `media.clip_window()` is the only window definition.
-- `chain_salt` digests **tensors**, not filenames. Trim / mp already invalidate the hop cache. `voice_on` is an extra key field on this tree (why 2.6 keys differ, pixels did not).
-- Hop meta `block` is stored as `block[:400]`. Do not reconstruct a beat from that.
-- H264 SaveVideo is not bit-identical; 2.6 compared hop FFV1 `.mkv` + `.npy`.
-- Writer: `htc_llm.json` is gitignored, machine-local. No API keys. `keep_warm` default on; eviction is `run()` → `free_for_render`. `tools/check_planner.py` redirects `_conn_path` to a temp file so it cannot overwrite the user's settings.
-- ComfyUI execute is **async**. Never `asyncio.run` from `run()`.
-- 8-step turbo is the validation regime. Do not report 14-step as the result.
-
----
-
-## 6. Also on disk (scratch, do not `rm`)
-
-- `D:\downloads\_nullcheck_A\` — A's lossless hops for 2.6
-- `D:\downloads\_nullcheck_A_prompt.json` — A's API graph
-- `D:\downloads\_queue_nullcheck_b.py` / `_queue_nullcheck_b3.py` / `_compare_*.py` — agent B scripts
-- `D:\ComfyUI\output\HandTieClips\contact_sheet_00039_.png` — A's sheet (has embedded prompt+workflow)
-- Six `.npy` scratch files in `D:\downloads\` from an older note; leave them

docs/HANDOVER_2026-09-02_2.md

@@ -1,273 +0,0 @@
-# Handover — 2026-09-02, second session (writer: the rail is read, the GUI is not)
-
-Written by Claude at the end of the 02:30 session. **This file is the live
-queue.** It supersedes `docs/HANDOVER_2026-09-02.md` (Grok's, 01:36) and
-`docs/HANDOVER_2026-09-01.md` (closed) wherever they disagree.
-
-Read order: this file, then `CLAUDE.md`, then `docs/DEVLOG.md` §29–§30.
-**DEVLOG §31 is not written yet** — see §4. Plan files under `~/.claude/plans/`
-are historical.
-
----
-
-## 0. Where you are
-
-| | |
-|---|---|
-| path | `D:\ComfyUI\custom_nodes\ComfyUI-Hand-Tie-Clips` |
-| branch | **`main`** at `4f756a7` *a likeness plate and a wardrobe plate are not the same picture* |
-| remotes | **not pushed.** `main` is **40 commits ahead of `origin/main`** |
-| working tree | clean |
-| version | `pyproject.toml` still **0.4.5** — no bump, no publish |
-| JS | `js/h3_ref_chain_ui.js` `VERSION = "v1.5.3"` — **untouched this session** |
-| Python | `D:/ComfyUI/venv/Scripts/python.exe` |
-| checkers | `tools/check_all.py` — **all 9 green at `4f756a7`** |
-
-```
-4f756a7  writer: a likeness plate and a wardrobe plate are not the same picture
-369d3b1  writer: a cut-off reply is the context, not the formatting
-bbade17  writer: take the empty answer out of the grammar
-9cf1a64  writer: the filename is the identity, not the tag
-2517543  docs: handover for Claude, writer-rail is the live queue   <- Grok's
-495335d  writer: desc and context are the point of looking
-```
-
-### The LM Studio settings are load-bearing and they do not survive a reload
-
-**Context `32768`, reasoning OFF.** Both were correct for the one fully
-successful run and both had reverted to defaults (8192, thinking on) by the
-next one. Check them before reading anything into a failure. The arithmetic
-that proves it is in the error message itself: `prompt 8159 + completion 31 =
-8190 ≈ 8192`.
-
-Reasoning off is now a standing rule from the user, not a workaround.
-
----
-
-## 1. Rules that are not negotiable
-
-Unchanged from 09-01 and 09-02. Each has already cost a session.
-
-1. **`widgets_values` is positional.** New widgets at the **bottom** of
-   `optional` only. `tools/check_workflows.py` is the catcher.
-2. **Never `rm` untracked things.** Move to `D:\ComfyUI\_disabled_custom_nodes\`.
-3. **No `subprocess` in this pack.** `tools/check_all.py` may; `llm.py` /
-   `store.py` must not.
-4. **aiohttp handlers share the event loop.** Decode / disk / model I/O goes
-   through `run_in_executor`.
-5. **Never disable Smart App Control.**
-6. **Do not pass `--token` to `comfy node publish`.**
-7. PowerShell 5.1 — no `&&`.
-8. `user/default/workflows/*.json` stay on legacy `H3RefChain` ids.
-
-New, and it shaped two changes this session:
-
-9. **A change to `prompt_pack/` goes in BOTH `SYSTEM_PROMPT.md` and
-   `AUTHORING_PROMPT.md`.** `tools/check_prompts.py` compares the numbered
-   rules, the length table and the closing checklist; it does **not** compare
-   the prose between them, so a rule added to one file only can still pass.
-   `AUTHORING_PROMPT.md` is the copy users paste into LM Studio by hand, and
-   the user has said explicitly that the manual paste is the *primary* route —
-   the Write-plan button is the alternative. A rule that helps both belongs in
-   the prompt; a rule about the rail belongs in `planner.build_user_turn`,
-   where it cannot leak into the paste text.
-
----
-
-## 2. Closed — do not redo
-
-### The 09-02 live item: "writer looks at the rail"
-
-**Vision was working the whole time.** It never needed proving again after
-`495335d`. The rail's filenames actively lie (`cafe_floral_9x16.jpg` *is the
-face plate*, `podcast_host.jpg` is the full body), and the model described all
-three correctly. Nothing that reads filenames calls `cafe_floral_9x16.jpg` a
-close-up portrait.
-
-`VISION_SIDE = 1024` is fine. **Do not chase `--image-min-tokens`** — that was
-Grok's next lever and it was aimed at the wrong thing.
-
-### Four faults, in the order they were hiding behind each other
-
-| commit | fault | how it was proved |
-|---|---|---|
-| `9cf1a64` | model renames rail tags (`@ref_1` -> `@girl_face`); `validate` matched on tag so it **never reached the file check**, and `_merge_register` unioned by tag so attempt 1's invented names poisoned every later attempt — the loop could not converge on a plan that was already correct | remap by filename; `check_planner.py` asserts first-attempt converge |
-| `bbade17` | `"subjects": {}` and omitted `desc` | **three byte-identical 1797-char replies** across three repair turns. Prose cannot outvote a grammar that permits the empty answer |
-| `369d3b1` | a truncated reply was returned as-is, `split_reply` found no JSON, and the loop spent every attempt blaming the model's formatting for an exhausted context | `finish_reason == "length"` now checked before the text is returned |
-| `4f756a7` | both plates of one person marked `fully_preserved` on every hop — including a full-body plate with a microphone and another room in it | prompt rule + two lints |
-
-### The one fully successful run (worth not re-deriving)
-
-Context 32768, reasoning off, three stills, the user's deliberately bad brief.
-**ok, 2 attempts, no stub.**
-
-- `@ref_1` *"a close-up portrait of a young woman with long dark hair and red
-  lipstick smiling at the camera"*
-- `@ref_2` *"a wide shot of a kitchen counter with a blue mug and a sink under
-  a window"*
-- `@ref_3` *"a medium shot of a young woman in a white top and denim shorts
-  sitting next to a microphone"*
-- subject 1 `context`: *"a white ribbed crop top and blue denim shorts, sitting
-  on the counter"* — read off `@ref_3`, which is the user's "full body image is
-  the wardrobe" instruction obeyed without it having been written well.
-
-The one thing it got wrong is what `4f756a7` addresses: `@ref_3` was
-`fully_preserved` on `[1, 2]`. It should be `partially_copy` on `[1]` with the
-colours in `context`, which is what an earlier run produced unprompted.
-
----
-
-## 3. LIVE — take over here
-
-### 3a. The GUI and the HTTP route were never exercised. Say so; do not imply otherwise.
-
-Everything above was driven by a standalone script that calls
-`planner.write_plan` **directly**:
-
-    D:\downloads\drive_writer.py     (NIMG=0 forces the text-only path)
-    D:\downloads\measure_ctx.py      (prompt-token measurements)
-
-Both were copied out of the session scratchpad, which is session-scoped and is
-gone by the time you read this. They need no running ComfyUI: `media.input_dir`
-falls back to `<ComfyUI>/input` when `folder_paths` is absent, and the pack is
-loaded the way `tools/check_planner.py` loads it, with `D:\ComfyUI` on
-`sys.path`. That also means they always run the code **on disk** rather than
-whatever a long-lived ComfyUI imported at boot — which is why they are the
-faster loop for anything that is not the panel itself.
-
-**Therefore still unverified:**
-
-- `routes.py::_plan` — `_pinned_refs`, the executor `vision_data_url` encode,
-  the 400-on-images fallback. The script builds pinned rows and data-URLs by
-  hand and bypasses the handler entirely.
-- The panel: Write plan -> the three boxes -> **Accept** -> widgets -> queue.
-- `js/` is unchanged this session, so `v1.5.3` is as it was, but the *round
-  trip* of an accepted register onto the rail rows has not been seen since the
-  tag remap landed. That is the one place the remap could still be wrong: the
-  rail keys rows by tag, and the remap now guarantees the accepted plan uses
-  the rail's tags, which is what Accept needs — but nobody has watched it.
-- **ComfyUI was never restarted this session.** The running instance has the
-  *old* `planner.py` in `sys.modules`. Restart before any GUI check or you will
-  be testing `495335d`.
-
-### 3b. Your first job
-
-1. LM Studio: context **32768**, reasoning **off**. Confirm both survived the
-   load.
-2. Restart ComfyUI. Hard-reload the tab. Console: `[HandTieClips] editor ui
-   v1.5.3 loaded`.
-3. Same rail as the session: `@ref_1 cafe_floral_9x16.jpg`,
-   `@ref_2 h3_stress_kitchen_6.jpg`, `@ref_3 podcast_host.jpg`, all three left
-   on the default `setting/prop` + `reference`, desc boxes empty. Brief: the
-   user's own badly-written one (§5). Hops **2**, duration **7 s in the RUN
-   panel**.
-4. Expect: three correct `desc`, subject 1 with real `name`/`locked`/`context`,
-   no *"filled from the photo descriptions"* warning.
-5. **The open question is whether `4f756a7`'s prompt rule moves `@ref_3` to
-   `partially_copy` on `shots: [1]`.** It is a model-behaviour question, not a
-   code one. If it does not move, the lint fires and says so before Accept —
-   that is the design, not a failure. Do not promote the lint to an error;
-   `planner.validate` explains why (`errors` means the node would refuse the
-   plan, and a retry rewrites the parts that were already right).
-6. Then Accept, queue, and confirm `[HandTieClips] freed the writer`.
-
-### 3c. The decision the user has not made
-
-`_stub_missing_subjects` fills `desc` with `"the reference photograph"` and a
-subject with `"the person"` / `"the same face and hair"`, then hands over a
-plan that *looks* filled. It is the only path in the writer that can put words
-the user never chose in front of the encoder.
-
-The user's stated principle: *"if it's bad, it's just a bad intent from the
-user — that's fine — but the guardrails must be as failsafe and protective of
-the intent as possible."* Silent filler is the opposite of that.
-
-`bbade17` should keep the stub from firing at all. The proposal on the table,
-**not yet approved**: mark stubbed fields visibly in the draft so an unread
-Accept cannot launder machine filler into a plan. Ask before building it.
-
----
-
-## 4. Open, not the writer
-
-- **DEVLOG §31 is unwritten.** The three findings that belong in it: grammar
-  beats prose (the byte-identical replies), the prompt-token breakdown, and
-  the tag-remap cascade. Everything needed is in §2 and §5 of this file.
-- **`pin_renorm=band` A/B.** 3 hops, `control_after_generate=fixed`,
-  `cache_hops=on`, `tools/texture_probe.py --box`. Baseline +4.2% mid-band per
-  join. `sigma` is a no-op; `band` is the lever. Only pull `match_band` toward
-  `tone.anchor_pull`'s 0.35 **if faces go waxy**.
-- **The system prompt is the biggest cost in the writer.** 5886 tokens, 74% of
-  a 7929-token first turn, paid again on every repair turn. Nothing to do
-  about it today — it is the shipped paste text and cutting it changes both
-  routes at once — but it is the reason an 8192 context cannot work.
-- **First-frame crop box.** `MiniMaxH3AddGuide` centre-crops; a 9:16 still on a
-  16:9 canvas loses the sides. Noted, not planned.
-- **Push.** Nothing on `main` is on GitHub/HF except the old 0.4.5. If the push
-  touches `docs/img/`: `git lfs push
-  https://github.com/dntpi/ComfyUI-Hand-Tie-Clips.git main` **then**
-  `git push origin main`. `origin` has two push URLs; LFS follows only the first.
-- **Version / publish.** Still 0.4.5. No `--token`.
-
----
-
-## 5. Facts worth not re-deriving
-
-**Prompt token costs, measured on this machine against qwen3.8-27b:**
-
-| | tokens |
-|---|---|
-| `SYSTEM_PROMPT.md` | 5886 (74% of the first turn) |
-| 3 stills @ 1024 px | 1747 |
-| 3 stills @ 768 px | 1003 |
-| 3 stills @ 512 px | 451 |
-| 1 still @ 1024 px | 591 |
-| brief + rail rows | ~300 |
-| **first turn, 3 stills** | **7929** -> **8159** after `4f756a7` |
-
-Shrinking `VISION_SIDE` is **not** the lever it looks like. The stills are 22%
-of the turn; the system prompt is three and a half times their cost. At 512 px
-you save 1300 tokens and go back to guessing which picture is the face.
-
-- **A grammar outvotes prose.** Three byte-identical replies with the images
-  and the errors in context. If a field is optional in the JSON schema, a
-  repair turn asking for it will not produce it. `_tighten_schema` makes the
-  missing fields structurally mandatory **for the repair turn only** — the
-  shipped schema stays permissive on purpose, because a plan with no people in
-  it is legitimate and `minProperties` on `subjects` would forbid it.
-  `check_planner.py` pins the shipped schema's permissiveness so a later
-  tightening of the wrong file fails there rather than in front of a user.
-- **The filename is the identity, not the tag.** A model that has looked at a
-  picture names the row for what it saw. Accept writes back onto rail rows
-  keyed by tag, so the remap is what makes the two survivable together.
-- **Text-only is a real diagnostic, not just a fallback.** Blind, the model
-  confabulated `cafe_floral_9x16.jpg` into *"a wide view of a bright kitchen"*
-  and promoted `podcast_host.jpg` to the likeness — a confident, well-formed,
-  completely wrong register. Same schema, no eyes. `NIMG=0` reproduces it.
-- The user's test brief, verbatim: *"beautiful asian girl sitting on top of a
-  kitchen counter talking about her day in earnest. 2 hops of 7 seconds. face
-  image is the likeness of the subject. Full body image is the wardrobe and
-  clothing of the subject"* — deliberately badly written, to test the
-  guardrails rather than the prose.
-- **7 s is under the join canvas.** `CLAUDE.md` puts join validation at 2 x 8 s
-  (`00028`); 5 s drops the airlock. Keep 7 s for writer testing, switch to 8 s
-  before concluding anything about the join.
-- Pack media is **filenames under `<input>/h3_refs`**, not sockets.
-- `chain_salt` digests **tensors**. `voice_on` is an extra key field on this
-  tree (why the 09-01 null check's keys differed and its pixels did not).
-- Hop meta `block` is stored as `block[:400]`. Do not reconstruct a beat from it.
-- ComfyUI execute is **async**. Never `asyncio.run` from `run()`; `llm._run_coro`
-  is the side-thread escape.
-- 8-step turbo is the validation regime. Never report a 14-step result as one.
-
----
-
-## 6. Also on disk (scratch, do not `rm`)
-
-- `D:\downloads\_nullcheck_A\` — A's lossless hops for the 09-01 null check
-- `D:\downloads\_nullcheck_A_prompt.json` — A's API graph
-- `D:\downloads\_queue_nullcheck_b*.py`, `_compare_*.py` — agent B scripts
-- `D:\downloads\drive_writer.py`, `measure_ctx.py` — this session's writer
-  driver and the token measurements (§3a)
-- `D:\ComfyUI\output\HandTieClips\contact_sheet_00039_.png` — A's sheet
-- Six `.npy` scratch files in `D:\downloads\` from an older note; leave them

planner.py

@@ -85,6 +85,48 @@ def beat_table():
 # words and measured 1.8 s of voiced audio.
 SPEECH_WPS = 2.5
 
+# Speech rate for scripts written in syllable blocks rather than space-delimited
+# words -- Hangul, Han, Kana. Counting their whitespace tokens with SPEECH_WPS
+# undercounts badly: a 27-syllable Korean line is 8 tokens, which the word rate
+# calls 3.2 s against a real 4-5 s, and the "write roughly N words" target it
+# derives would ask for about 85 syllables in a 10 s hop. ~5.5 syllables a
+# second is the conversational figure across all three scripts; it is a
+# reference figure, not something measured on this model.
+SPEECH_SPS = 5.5
+
+# Built from codepoints rather than written as an escape class so the source
+# stays pure ASCII. Hangul jamo and syllables, kana, CJK ideographs, halfwidth
+# kana.
+_CJK_RANGES = ((0x1100, 0x11ff), (0x3040, 0x30ff), (0x3130, 0x318f),
+               (0x3400, 0x4dbf), (0x4e00, 0x9fff), (0xa960, 0xa97f),
+               (0xac00, 0xd7ff), (0xff66, 0xff9f))
+_CJK = re.compile("[" + "".join(chr(a) + "-" + chr(b) for a, b in _CJK_RANGES) + "]")
+
+
+def speech_seconds(text):
+    """Seconds of speech in `text`, counting each script in its own unit.
+
+    A plan may be written in any language -- the beats stay English prose, the
+    lines inside the quotes need not. Mixed text is counted both ways and
+    added, so an English beat with one Korean line is estimated correctly
+    rather than in whichever unit happens to dominate.
+    """
+    t = str(text or "")
+    cjk = len(_CJK.findall(t))
+    # Only tokens carrying a letter or digit. Stripping the CJK out of a
+    # Korean line leaves its punctuation stranded as free-standing tokens,
+    # and counting "!" and "." as two spoken words bought a 10 s hop most of
+    # a second it does not have.
+    rest = sum(1 for w in _CJK.sub(" ", t).split() if any(c.isalnum() for c in w))
+    return cjk / SPEECH_SPS + rest / SPEECH_WPS
+
+
+def spoken_text(beat):
+    """Just the words inside the spoken spans, joined."""
+    t = str(beat or "")
+    return " ".join(t[a + 1:b] for a, b in spoken_spans(t))
+
+
 # How much of a hop a speaking character should actually be speaking for. Below
 # this there are seconds of someone visibly mid-sentence with nothing assigned,
 # and the model fills them itself -- as fragments (chain_00059: 17.8% voiced,
@@ -322,17 +364,24 @@ def validate(shot_text, ref_text, *, hops=None, known_files=None, pinned=None,
         # twenty. This is the arithmetic, and it is worth stating outright
         # because the number the author needs is not the number of lines.
         secs = DURATION_FRAMES.get(label, 0) / float(FPS or 24)
+        said = spoken_text((sh or {}).get("beat"))
         if spoken_words and secs:
-            speech = spoken_words / SPEECH_WPS
+            speech = speech_seconds(said)
+            # Name the target in the unit the line is actually written in,
+            # because "roughly 25 words" of Korean is about 85 syllables and
+            # three times the hop.
+            if len(_CJK.findall(said)) > len(_CJK.sub(" ", said).split()):
+                target = f"{int(secs * SPEECH_SPS)} syllables"
+            else:
+                target = f"{int(secs * SPEECH_WPS)} words"
             if speech < secs * SPEECH_MIN_SHARE:
                 warnings.append(
-                    f"shot {i + 1}: {spoken_words} spoken words is about "
-                    f"{speech:.1f}s of speech in a {secs:.0f}s hop. A character "
-                    f"written as talking throughout needs roughly "
-                    f"{int(secs * SPEECH_WPS)}. The seconds left over are a "
-                    f"person visibly mid-sentence with nothing assigned, and "
-                    f"the model fills them itself. Give those seconds more "
-                    f"words, or name the sound they carry.")
+                    f"shot {i + 1}: the spoken lines run about {speech:.1f}s "
+                    f"in a {secs:.0f}s hop. A character written as talking "
+                    f"throughout needs roughly {target}. The seconds left over "
+                    f"are a person visibly mid-sentence with nothing assigned, "
+                    f"and the model fills them itself. Give those seconds more "
+                    f"to say, or name the sound they carry.")
         # Rule 3 inside a hop. A beat that opens on action and speaks later has
         # frames with a picture and no sound, and the model fills them with
         # dialogue nobody wrote -- the same failure as a silent hop, one
@@ -697,7 +746,11 @@ def build_user_turn(brief, hops, files, pinned=None, duration=None):
                 f"roughly {int(secs * SPEECH_WPS)} words INSIDE the quotes -- "
                 f"several sentences, not one. Count the spoken words too. "
                 f"A hop where nobody speaks is fine, but say so: name the "
-                f"sound the room makes instead.")
+                f"sound the room makes instead. If the lines are in a script "
+                f"written in syllable blocks rather than spaced words -- "
+                f"Korean, Japanese, Chinese -- count syllables instead and "
+                f"aim for about "
+                f"{int(secs * SPEECH_SPS)}.")
             lines.append(
                 "If anything happens before the first spoken line -- walking "
                 "in, sitting down, turning to the camera -- name the sound "

tools/check_planner.py

@@ -418,8 +418,49 @@ def main():
                                 ("twenty-five words is not", full, False)):
         _, ws = PL.validate(_talk(spoken), json.dumps(GOOD_REFS), hops=1,
                             known_files=kf, duration="10 s")
-        ck(label, any("spoken words is about" in w for w in ws) == want,
-           "; ".join(w for w in ws if "spoken words" in w)[:110])
+        ck(label, any("spoken lines run about" in w for w in ws) == want,
+           "; ".join(w for w in ws if "spoken lines run" in w)[:110])
+
+    # A plan may be written in any language; only the beats around the quotes
+    # have to be English. Counting a Korean line's whitespace tokens with the
+    # word rate called a real 4-5 s line 3.2 s, and the "roughly N words"
+    # target it derived asked for about 85 syllables in a 10 s hop. Live, on
+    # 2026-09-02: a 3-hop Korean vlog warned on every shot for being too thin
+    # when two of the three were fine.
+    KO = chr(0xd55c) + chr(0xad6d) + chr(0xc5d0) + chr(0xc11c) + chr(0xc758)
+    KO_LINE = KO + " " + chr(0xc2dc) + chr(0xac04) + chr(0xc740)   # 8 syllables
+    ck("a CJK line is counted in syllables, not tokens",
+       abs(PL.speech_seconds(KO_LINE) - 8 / PL.SPEECH_SPS) < 0.01,
+       "%.2f" % PL.speech_seconds(KO_LINE))
+    ck("English still uses the word rate",
+       abs(PL.speech_seconds("one two three four five") - 5 / PL.SPEECH_WPS) < 0.01,
+       "%.2f" % PL.speech_seconds("one two three four five"))
+    ck("mixed text counts both scripts",
+       abs(PL.speech_seconds(KO_LINE + " and five more words here")
+           - (8 / PL.SPEECH_SPS + 5 / PL.SPEECH_WPS)) < 0.01,
+       "%.2f" % PL.speech_seconds(KO_LINE + " and five more words here"))
+    ck("stranded punctuation is not a spoken word",
+       PL.speech_seconds(KO_LINE + " ! . ?") == PL.speech_seconds(KO_LINE),
+       "%.2f vs %.2f" % (PL.speech_seconds(KO_LINE + " ! . ?"),
+                         PL.speech_seconds(KO_LINE)))
+    ck("the word rate would have undercounted it",
+       len(KO_LINE.split()) / PL.SPEECH_WPS < PL.speech_seconds(KO_LINE),
+       "%.2f vs %.2f" % (len(KO_LINE.split()) / PL.SPEECH_WPS,
+                         PL.speech_seconds(KO_LINE)))
+
+    # ...and the shortfall warning has to name the target in the unit the line
+    # is written in. "roughly 25 words" of Korean is three times the hop.
+    thin_ko = json.dumps({"shots": [
+        {"id": "s1", "beat": "@ref_1 walks and says, '" + KO
+                             + "' She keeps going as the clip ends.",
+         "directives": {"tail": "hold"}}]})
+    _, ws = PL.validate(thin_ko, json.dumps(GOOD_REFS), hops=1,
+                        known_files=kf, duration="10 s")
+    short = [w for w in ws if "spoken lines run about" in w]
+    ck("a thin CJK hop is still flagged", bool(short), "; ".join(ws)[:110])
+    ck("and its target is in syllables",
+       bool(short) and "syllables" in short[0],
+       short[0][:120] if short else "")
 
     # Rule 3 applies INSIDE a hop. A beat that opens on action and speaks later
     # has frames with a picture and no sound, and the model fills them with