Merge remote-tracking branch 'origin/main' into wt/20261018-204501

Deployed shape verified live: KV 16,384.00 MiB (ledger-exact 32,768 B/token x
524,288), RS 100.50 MiB (2 cells), settled nvidia-smi 21,176 used / 2,949 free,
n_slots 2, n_ctx_slot 262144, DropInPaths empty.

Rates recorded as FLOORS: another consumer drove the endpoint through the whole
window (56 prompts on the other slot in three minutes, 96% GPU-util). Single
stream 134.1-141.5 (145.8/163.2 in a lighter minute) vs the 168.7 q8_0 record;
two-stream aggregate 256.6-265.1 vs ~300 across three; prefill 3,159.5 at
106,282 beats the 2,877 record while contended; decode at 106k depth 71.5 (new
baseline, no prior). Per-stream concurrency improved: ~130 each vs 102.8.

Instrument correction: the PrismML fork build 10777 answers 500 'The model
produced output that does not match the expected Content-only format' for a
greedy ignore_eos run on the raw /completion path, so the per-request timings
must be read off /v1/chat/completions. AGENTS.md Benchmarking Policy corrected.

AGENTS.md

@@ -27,7 +27,7 @@ merge absorbed the former `vllmScripts` repo, history preserved).
 |--------|---------|---------|-------|------|
 | Dankserver | `frank-archon` | **radiance** (StillDeadcode, **pin 1.0.13** digest-pinned `stilldeadcode/radiance@sha256:4c3f484564…`, plain `podman run`, root systemd unit) | **Publisher payload** (swap 2026-10-15, MODEL_FILE-only): `StillDeadcode/qwen3.8-next-flash-fp8-iq4r-moe` → **`qwen3.8-next-flash-fp8-iq4r-moe.rad`** (121,969,901,568 B = **116,322 MiB**, Hub-LFS sha256 `0af5e962…` verified at fetch by `scripts/download-frank-archon-iq4r.sh`) — the OFFICIAL Qwen3.8-Flash-Next bf16 checkpoint rad-converted by the engine's author: routed experts as **4-bit codes into a 16-level non-uniform codebook** (128-pt Walsh–Hadamard rotation, GPTQ on a 10M-token calibration + 3 coordinate-descent sweeps, E4M3 scales per 64 weights), **10 whole bf16-protected experts/layer**, int8 W8A8 trunk/lm_head, fp8 HC mixtures, fp8 fixed-scale PLE n-gram (47.7 GiB), **MTP head + bf16 vision tower in the container**; card KL 0.0789 mean all-tokens / top-1 92.85 % vs BF16. **Base-alignment (censored) model** — the abliterated family lives on frank-dragoon. Shape carried VERBATIM from the 2026-10-13 record: **3 × 200,000 fp8-KV** (`--max-num-seqs 3`), **25,600 MiB slab + 5,120 MiB pool = 30,720 of the 30,969 MiB claimable**, 44 GiB/rank pinned host pool, PLE pinned to RAM, MTP depth 2, MNBT 2048, Froggeric v22.5 template. Decode/prefill ladders in the runbook are the **w4dn8 record** (the bar to beat; new-payload probes pending). Rollback: re-download the w4dn8 `.rad` from the HF mirror `frank8465/Swift-1.5-Qwen3.8-Flash-Next-GPTQ-W4A8-Radiance-AMD-R9700` (LFS sha256 `09dd9306…`) + revert the swap commit — the local copy was **purged 2026-10-17** (it was the last non-iq4r model on the host; the GLM-4.7 GGUF, the radiance kvcache tiers, and every stale compile cache went in the same purge, 763 GiB free). The fp8-native `.rad` + the raw Swift1.5 BF16 source were DELETED from disk 2026-10-15 (Frank's one-time rm, volume for this payload; rebuildable via the fetch/build scripts). | 7770 |
 | Dankclaw | `frank-dragoon` | **halogen-flash-server 0.16.2** (`ghcr.io/peonist-ai/halogen-flash-server@sha256:0c61bf84…`, digest-pinned, plain `podman run` via `scripts/serve-frank-dragoon.sh`, root systemd unit) | Quat3rnion/halogen-qwen3.8-flash-next-v2-abliterated **`qwen38-flash-next-v2-abliterated.hgn`** (66,687,678,432 B ≈ 62.1 GiB resident, Hub LFS sha256 `b5bd925f…` verified at fetch — the **NATIVE 2026-10-11 v2 conversion** of orcarouter's pinned BF16, abliterated, NOT the writer transplant that carried this filename; the v2 `.hgn` format loads in NO other engine), **+ REQUIRED `qwen38-flash-next-ngram.hgn`** (51,200,246,144 B, peonist @5cc17cea) **+ vision tower** (897,916,416 B, @e053f488) — both **hardlinked** from the swift15 payload dir (the release publishes only the main file; the engine's own `niah` 18/18 + `ppl` 3.968 with mean KL 0.155 vs the swift15 logits certified the stock companions), **vision ON** (`image_url` parts only, ≥256 px probes), **MTP spec decode ALWAYS-ON (`HALOGEN_SPEC_ADAPT=0` — the adaptive default disables the drafter per request and HALVES decode)**, MTP head INSIDE the checkpoint (`HALOGEN_MTP_HEAD` unset), **TWO slots over ONE `HALOGEN_KV_POOL_POSITIONS=401408` pool (= 2 × ctx) at `HALOGEN_CTX=200704`** (pool RAISED from 200,704 and DEPLOYED 2026-10-18 so BOTH slots can hold a maximum-length request at once; the parity play was frank-zealot's then-401,408 total in-flight context — zealot moved to 786,432 the same evening and dragoon's pool was NOT raised again, because every position is page cache the n-gram table loses; **11.0 GiB reserved, measured on that deploy** (the preflight formula bills 11.3) where 200,704 cost 5.5, 262,144 cost 7.2 and the 2026-10-06 pool measured 14.6; the ceiling does NOT move with it — 262,144 is the native wall and the engine refuses more without `HALOGEN_ROPE_YARN`), harness window 155,648 = ceiling − 45k estimate headroom, **server-side sampler 1.0/0.95/20** (peonist engine recipe — Quat3rnion publishes none; models.yml extraBody matches), coupled cap/timeout 65536/7200, prompt cache ON by default (warm 100k turn ≈ 2 s vs ≈ 88 s cold), **n-gram table disk-backed** (mmap page cache, `Pin::None`); measured vs the swift15 boot: cold prefill +12.6 %, decode 50.0 vs 46.8 t/s, NIAH 18/18 vs 17/18, PPL +2.3 %, thinking tokens ×1.9|7770|
-| Dankclaw | `frank-zealot` | **llama.cpp PrismML fork build** (vendor release `0.2.0-dev` build **10777**, commit `e3de71522`; root systemd unit, relinked — the ONLY loader for this payload, and since 2026-10-18 also the minimum build that pairs MTP with a quantized V cache) | `prism-ml/Ternary-Bonsai-2-9B-gguf` **PQ2_0 carrying the MTP head in the file** (2,675,410,720 B, Hub-LFS sha256 `c79fcdfa…` verified at fetch by `scripts/download-frank-zealot-bonsai9.sh`; `qwen35` hybrid: `block_count 33` = **32 trunk layers** (8 full-attention + 24 Gated DeltaNet at `full_attention_interval 4`) + the `blk.32` MTP block, 4 KV heads × 256 dim, native 262,144; `general.file_type 141` with **202 custom-type PQ2_0 tensors of 442** + `prism.hadamard.*` dequant metadata, which is what locks the runtime) + the publisher's own **Q8_0 mmproj** (624,229,664 B, sha256 `e0cb6f69…`; **Q8_0 is the publisher's requirement** for concurrent image requests — the BF16 tower can crash the server, and this endpoint runs three slots) for **vision**, on the RTX 3090, **THREE 262,144-token slots** (`--ctx-size 786432 --parallel 3` = every conversation at the trained window), **q8_0 K + q8_0 V** under flash attention (17 KiB/token over the 8 full layers = 13,056 MiB pool, ledger-exact; **f16 KV needs 26,112 MiB and cannot boot this card**; +151 MiB of recurrent state for the three DeltaNet cells — the SPEC-ARMED arms print 452 MiB, because MTP depth 2 bills three seqs per slot), batch 4096 / **ubatch 2048** (measured CUDA optimum), `--log-verbosity 4`, **MTP OFF — measured, not because the head is absent**: the draft context bills its own f16 KV over the WHOLE pool (3,072 MiB) and at ubatch 2048 that squeeze halves decode (167.2 → 109.2 t/s); the documented MTP arm is `SPEC_TYPE=draft-mtp` + `UBATCH_SIZE=1024` → 213.5 t/s. Production boot 17,922 used / 6,203 free; **168.7 t/s** single-stream greedy decode (three runs, 168.4–168.7) and **~300 t/s** aggregate across three concurrent streams (102.8 each); 2,877 t/s prefill at 106,418 was the trial arm. Cutover 2026-10-18 from Ternary-Bonsai-2-**27B** PQ2_0 at 2 × 200,704 (payload + build 10754 tree on disk as rollback). | 7771 |
+| Dankclaw | `frank-zealot` | **llama.cpp PrismML fork build** (vendor release `0.2.0-dev` build **10777**, commit `e3de71522`; root systemd unit, relinked — the ONLY loader for this payload; the b10776 floor that gates MTP beside a quantized V cache is moot under exact KV, but the custom tensor type alone keeps the build pinned) | `prism-ml/Ternary-Bonsai-2-9B-gguf` **PQ2_0 carrying the MTP head in the file** (2,675,410,720 B, Hub-LFS sha256 `c79fcdfa…` verified at fetch by `scripts/download-frank-zealot-bonsai9.sh`; `qwen35` hybrid: `block_count 33` = **32 trunk layers** (8 full-attention + 24 Gated DeltaNet at `full_attention_interval 4`) + the `blk.32` MTP block, 4 KV heads × 256 dim, native 262,144; `general.file_type 141` with **202 custom-type PQ2_0 tensors of 442** + `prism.hadamard.*` dequant metadata, which is what locks the runtime) + the publisher's own **Q8_0 mmproj** (624,229,664 B, sha256 `e0cb6f69…`; **Q8_0 is the publisher's requirement** for concurrent image requests — the BF16 tower can crash the server, and this endpoint runs several slots) for **vision**, on the RTX 3090, **TWO 262,144-token slots** (`--ctx-size 524288 --parallel 2` = every conversation STILL at the trained window — the per-slot contract never moved) over **unquantized f16 K + f16 V** (32 KiB/token over the 8 full layers = **16,384 MiB** pool; the POOL halved because exact KV at the old 786,432 pool is 24,576 MiB against the 24,123 MiB the driver leaves addressable — the repo's older "26,112 MiB" figure had doubled the q8_0 number including its 1/32 scale overhead; +100.5 MiB of recurrent state for the two DeltaNet cells, ~50.25 MiB a cell), batch 4096 / **ubatch 2048** (measured CUDA optimum), `--log-verbosity 4`, **MTP OFF — measured, and now doubly so**: the draft context bills its own f16 KV over the WHOLE pool (3,072 MiB at the old pool, 2,048 MiB at this one) and at ubatch 2048 that squeeze halves decode (167.2 → 109.2 t/s); the documented q8_0-era MTP arm is `SPEC_TYPE=draft-mtp` + `UBATCH_SIZE=1024` → 213.5 t/s. Last MEASURED boot (the 3 × 262,144 q8_0 arm this replaces): 17,922 used / 6,203 free, **168.7 t/s** single-stream greedy decode (three runs, 168.4–168.7), **~300 t/s** aggregate across three concurrent streams (102.8 each), 2,877 t/s prefill at 106,418 — the f16 boot's ledger and rates land in the runbook once measured. Cutover 2026-10-18 from Ternary-Bonsai-2-**27B** PQ2_0 at 2 × 200,704 (payload + build 10754 tree on disk as rollback). | 7771 |
 
 Retired endpoints (`frank-npu`, and every prior runtime) are in
 the [runbook index](#runbook-index). The full swap history lives in
@@ -252,8 +252,12 @@ archive.
 real users, and a bench beside a live service starves the GPU and corrupts
 results. Use the runtime's own harness: `llama-bench` for the llama.cpp
 endpoints; a live llama.cpp server (frank-zealot) also reports honest
-per-request numbers in its `/completion` `timings` object (prefill/decode
-rates, `draft_n`, `draft_n_accepted`), which is how frank-zealot was measured.
+per-request numbers in a `timings` object (prefill/decode rates, `draft_n`,
+`draft_n_accepted`) — but on the PrismML fork build 10777 that object is only
+reaching you on **`/v1/chat/completions`**: a greedy `ignore_eos` run on the raw
+`/completion` path there answers **500 "The model produced output that does not
+match the expected Content-only format"**, so measure through the chat path
+(measured 2026-10-18 on the exact-KV reslice).
 halogen has NO `/completion` path at all — frank-dragoon's rates come from
 wall-clock around `/v1/chat/completions` plus the boot ledger. Rolling your own
 bench requires asking first.
@@ -350,9 +354,9 @@ and `frank-zealot` through
 the publisher's own **Q8_0** mmproj passed as `--mmproj` — Q8_0 is the
 publisher's requirement for concurrent image requests (the card states the
 BF16 tower can crash `llama-server` when several image requests run at once,
-and this endpoint runs three slots). `frank-zealot`'s `contextWindow` is
-**262144** — the PER-SLOT window (`--ctx-size 786432 --parallel 3` since the
-2026-10-18 Bonsai-2-**9B** swap), which since that swap EQUALS the model's
+and this endpoint runs several slots). `frank-zealot`'s `contextWindow` is
+**262144** — the PER-SLOT window (`--ctx-size 524288 --parallel 2` since the
+2026-10-18 reslice to exact f16 KV), which EQUALS the model's
 native window; llama.cpp answers a longer prompt with a 400 naming the limit,
 never a truncation, so the harness must compact before it.
 Note also
@@ -510,7 +514,8 @@ llama.cpp refuses the custom type at load, and a loader that
 ignored the Hadamard metadata would dequant WRONG — same lock class as the
 ROCmFPX era. On top of that lock, **the fork gates MTP beside a quantized V
 cache on build `prism-b10776-d00e252` or newer**, which is why the prebuilt
-moved 10754 → 10777; the 10754 tree stays on disk as the 27B rollback runtime.
+moved 10754 → 10777 (exact f16 KV makes that gate moot — the custom type alone
+pins the runtime); the 10754 tree stays on disk as the 27B rollback runtime.
 Retargeting the payload without the fork ships an endpoint that cannot load,
 so the seam pins both paths.
 
@@ -520,36 +525,47 @@ attention + FFN in q8_0, which is why the draft context bills real KV), and
 `qwen35.full_attention_interval = 4` ⇒ **8 full-attention + 24 Gated
 DeltaNet**, 4 KV heads × 256 dim, native 262,144. **KV accounting:** the pool
 scales with the 8 full layers — 8 × 4 × 256 = 8,192 elements/token per cache,
-so **q8_0 K + q8_0 V bills 17,408 B/token ≈ 17 KiB** = **13,056.00 MiB** at the
-786,432 pool (ledger-exact) — exactly HALF the 27B's 34,816 B/token, which is
-the whole reason three native windows fit where the 27B afforded only two
-shortened ones. **f16 K would bill 26,112 MiB and cannot boot on a 24,123 MiB
-card.** The 24 DeltaNet layers bill a fixed recurrent state per SLOT — the
-production ledger prints `RS buffer size = 150.75 MiB (3 cells, 32 layers,
-3 seqs)`, while the SPEC-ARMED arms print 452.25 MiB (MTP depth 2 bills three
-seqs per slot, so 9 cells) — so pool arithmetic alone under-prices the shape.
+so **the deployed exact pair f16 K + f16 V bills 32,768 B/token = 32 KiB** =
+**16,384 MiB** at the 524,288 pool. The q8_0 pair this endpoint shipped first
+billed **17,408 B/token** (1.0625 B/element: 32 codes plus one 2-byte scale per
+32-block) = **13,056.00 MiB** at the old 786,432 pool, ledger-exact — exactly
+HALF the 27B's 34,816 B/token. **Exact KV at that 786,432 pool is 24,576 MiB,
+more than the 24,123 MiB the driver leaves addressable, so the POOL is what
+pays for f16 — the window never moved.** (The "26,112 MiB" figure this repo
+carried doubled the q8_0 number *including* its scale overhead; the true ratio
+is 1.882×, not 2×.) The 24 DeltaNet layers bill a fixed recurrent state per
+SLOT — ~50.25 MiB a cell, so the 3-slot ledger printed `RS buffer size =
+150.75 MiB (3 cells, 32 layers, 3 seqs)` and two slots bill 100.50, while the
+SPEC-ARMED arms print 452.25 MiB (MTP depth 2 bills three seqs per slot, so 9
+cells) — so pool arithmetic alone under-prices the shape.
 
-**The shape (2026-10-18):** `--ctx-size 786432 --parallel 3` = THREE
-conversations of 262,144, every one at the model's TRAINED window (Frank: "if
-you can possibly fit a third context, do it"), `--flash-attn on`, **q8_0 K +
-q8_0 V**, batch 4096 / **ubatch 2048** (the measured CUDA optimum carried from
-the MiMo/Swift A/Bs on this card; it also sets the compute-buffer size, which
-is what decides whether MTP fits), `--log-verbosity 4`, `--metrics`,
-`--jinja`, `--mmproj` for vision, **speculative decoding OFF**
-(`SPEC_TYPE=none`). Boot: **17,876 MiB used / 6,249 free**; compute 1,409 MiB
-CUDA + 1,201 MiB CUDA_Host, projector 595 + 248 MiB. Measured on the same
-boot: **167.2 t/s** greedy decode, 158.9 t/s single-stream chat, **280.2 t/s
-aggregate across three concurrent streams**, **2,877 t/s prefill at 106,418**
-tokens — the 27B record (76.6 decode / 109.4 aggregate / 691.7 prefill at 166k)
-beaten on every axis. The **first request after boot is a warmup artifact**
-(37.7 t/s class) — never report it.
+**The shape (2026-10-18, resliced the same evening):** `--ctx-size 524288
+--parallel 2` = TWO conversations of 262,144, every one still at the model's
+TRAINED window (the first arm was THREE — Frank: "if you can possibly fit a
+third context, do it" — and the exact-KV reslice handed one back),
+`--flash-attn on`, **unquantized f16 K + f16 V**, batch 4096 / **ubatch 2048**
+(the measured CUDA optimum carried from the MiMo/Swift A/Bs on this card; it
+also sets the compute-buffer size, which is what decides whether MTP fits),
+`--log-verbosity 4`, `--metrics`, `--jinja`, `--mmproj` for vision,
+**speculative decoding OFF** (`SPEC_TYPE=none`). The MEASURED record still
+belongs to the arm this replaced (3 × 262,144, q8_0 K + q8_0 V): boot **17,876
+MiB used / 6,249 free**; compute 1,409 MiB CUDA + 1,201 MiB CUDA_Host, projector
+595 + 248 MiB; **167.2 t/s** greedy decode, 158.9 t/s single-stream chat,
+**280.2 t/s aggregate across three concurrent streams**, **2,877 t/s prefill at
+106,418** tokens — the 27B record (76.6 decode / 109.4 aggregate / 691.7 prefill
+at 166k) beaten on every axis. The exact-KV arm's ledger and rates go in the
+runbook once booted; its projection is ~21,200 MiB used / ~2,900 free, since
+only the KV pool (+3,328) and one recurrent-state cell (−50) move. The **first
+request after boot is a warmup artifact** (37.7 t/s class) — never report it.
 
 **Why MTP is off even though the head is in the file.** The drafter is GOOD —
 acceptance 0.798 / 0.617 per position, mean accepted length 2.41 — and the card
-recommends depth 2. It still loses AT THIS SHAPE because the draft context
-bills its OWN **f16** KV over the WHOLE pool (4,096 B/position × 786,432 =
-**3,072.00 MiB**, 4,830 MiB with its compute buffers) and ubatch 2048 refuses to
-give it up. Booted arms, same card, same traffic (2026-10-18):
+recommends depth 2. It still loses because the draft context bills its OWN
+**f16** KV over the WHOLE
+pool (4,096 B/position — **3,072.00 MiB** at the 786,432 pool, 4,830 MiB with
+its compute buffers; **2,048.00 MiB** at the shipped 524,288 pool) and ubatch
+2048 refuses to give it up. Booted arms, same card, same traffic (2026-10-18,
+every row q8_0 K + q8_0 V at the 786,432 pool):
 
 | slots | spec | ubatch | used / free | decode |
 |---|---|---|---|---|
@@ -563,13 +579,17 @@ give it up. Booted arms, same card, same traffic (2026-10-18):
 drafter, is what halves it at three windows. The arm that WOULD run it at three
 windows is `SPEC_TYPE=draft-mtp` + `UBATCH_SIZE=1024` (213.5 t/s single-stream,
 250.8 three-stream aggregate) and pays prefill −17 % and 2.7 GiB of headroom on
-a card whose projector worst-case lands AFTER the engine's own fit check. This
-endpoint is the fleet's compaction hub — prefill-bound, 2–3 concurrent
-subagents — so the shipped arm takes the +17 % prefill (2,877 vs 2,395 t/s) and
-the +12 % three-stream aggregate (280.2 vs 250.8) over single-stream speed, and
-keeps 6.2 GiB free. `SPEC_TYPE=none` strips the WHOLE spec set (`--spec-type`
-and every `--spec-draft-*`) — flags move as a set or the arm measures a crash
-instead of an absence.
+a card whose projector worst-case lands AFTER the engine's own fit check. Under
+**exact KV the drafter is arithmetically out**: the trunk projects ~21,200 MiB
+of the 24,123 MiB addressable before the draft context's 2,048 MiB and its
+buffers are even asked for, so the doors back to speculation are ONE window per
+conversation, or KV back to q8_0.
+The compaction-hub load is what makes exact KV affordable: prefill is
+weight-bandwidth bound and does not re-read the cache per generated token, so
+the dtype is paid in decode and concurrency (two conversations now, not three),
+not in the work this endpoint exists to do. `SPEC_TYPE=none` strips the WHOLE
+spec set (`--spec-type` and every `--spec-draft-*`) — flags move as a set or the
+arm measures a crash instead of an absence.
 
 **Sampler**: the recipe lives in the checkpoint (`general.sampling.*` =
 temperature 1.0 / top_p 0.95 / top_k 20 / min_p 0 / repeat_penalty 1.0,
@@ -581,7 +601,7 @@ would silently re-add the flag on an explicit empty value).
 
 **Vision**: the publisher's own **Q8_0** mmproj via `--mmproj` — Q8_0 is
 MANDATORY, not a preference: the card says the BF16 tower "can crash
-llama-server when several image requests run at once", and `--parallel 3` is
+llama-server when several image requests run at once", and `--parallel 2` is
 exactly that shape. Probe traps carry over: ≥256 px probe images or the model
 answers "video", only the OpenAI `image_url` content part reaches the model,
 and thinking tokens count against `max_tokens` — budget ≥512 or the probe
@@ -596,10 +616,12 @@ have to be fetched first.
 
 **Compaction hub**: `models.yml` routes `compactionModel` for
 `frank-archon`, `frank-dragoon` and `frank-zealot` (the 3090 endpoint) here —
-262,144 (since the 2026-10-18 reslice) is the widest window in the fleet and
-the only one that comfortably fits a worst-case compaction input (~170k
-tokens). With `--parallel 3` a compaction request no longer serializes behind a
-live generation (the Gemma4 era's `--parallel 1` law). Retrieval through a
+262,144 (still the PER-SLOT window after the exact-KV reslice) is the widest
+window in the fleet and the only one that comfortably fits a worst-case
+compaction input (~170k tokens). With `--parallel 2` a compaction request still
+runs beside ONE live generation, and with two already busy it waits — the Gemma4
+era's `--parallel 1` law at half strength, which is the concurrency price of
+exact KV. Retrieval through a
 25,960-token prompt was verified exact after the swap.
 
 **Contract law learned at verbosity 4:** a raw `/completion` request prints
@@ -1040,18 +1062,34 @@ linked runbooks.
 - **A draft context bills its own f16 KV over the WHOLE POOL, and on a
   single-card endpoint that squeeze can cost more than the drafter wins.** The
   draft context is built at the target's `n_ctx`, so with `--parallel N` the
-  drafter pays the POOL, not the slot: on frank-zealot's 786,432-position
-  qwen35 pool, `--spec-type draft-mtp` added **3,072.00 MiB of f16 draft KV**
-  (4,096 B/position — the draft cache is never quantized) plus its own compute
-  buffers, 4,830 MiB all told. Booted arms, same card, same traffic
-  (2026-10-18): 3 slots + ubatch 2048 → **167.2 t/s decode with spec OFF,
-  109.2 with spec ON**; dropping `UBATCH_SIZE` to 1024 hands the buffers back
-  and spec ON gives **213.5** (+28 % over the spec-OFF arm), and at 1–2 slots
-  the SAME card runs MTP at ubatch 2048 and still gains ~28 %. So the MTP
-  question is never "does the file carry the head" — it is "what do draft KV
-  + buffers cost against whatever the batch knobs keep for compute buffers",
-  and that answer is per-shape. Measure the arm, never the flag. See
+  drafter pays the POOL, not the slot: on frank-zealot's qwen35 pool
+  `--spec-type draft-mtp` adds **4,096 B/position of draft KV at the default
+  f16 dtype** (`--spec-draft-type-k/-v` can quantize the draft — untested here),
+  **3,072.00 MiB** at the 786,432 pool it shipped with and **2,048.00 MiB** at
+  the 524,288 pool it runs now, plus its own compute buffers (4,830 MiB all told
+  at the old pool). Booted arms, same card, same traffic (2026-10-18, every row
+  q8_0 KV): 3 slots + ubatch 2048 → **167.2 t/s decode with spec OFF, 109.2 with
+  spec ON**; dropping `UBATCH_SIZE` to 1024 hands the buffers back and spec ON
+  gives **213.5** (+28 % over the spec-OFF arm), and at 1–2 slots the SAME card
+  runs MTP at ubatch 2048 and still gains ~28 %. So the MTP question is never
+  "does the file carry the head" — it is "what do draft KV + buffers cost
+  against whatever the batch knobs keep for compute buffers", and that answer is
+  per-shape. Measure the arm, never the flag. Production corollary: beside
+  exact KV an **f16-draft** arm has no room — the trunk projects ~21,200 MiB of
+  the 24,123 addressable before the drafter is asked for anything; the untested
+  door is `--spec-draft-type-k/-v q8_0` (1,088 MiB). See
   [[frank-zealot-llama-prism-bonsai9-mtp]].
+- **A quant's scale overhead belongs in its byte rate, and doubling a measured
+  pool figure to "get the f16 number" invents 6.25 %.** This repo carried "f16
+  KV would bill 26,112 MiB" for weeks by doubling the q8_0 ledger figure
+  (13,056.00 MiB). q8_0 is 1.0625 B/element (32 codes plus one 2-byte scale per
+  32-block), f16 is exactly 2.0 ⇒ the true ratio is **1.882×**, so exact KV over
+  that pool is **24,576 MiB**. The conclusion (three f16 windows cannot boot a
+  card that leaves 24,123 MiB addressable) survived; the number did not — and
+  the honest rate is what made the resize calculable, because it shows 524,288
+  positions is the largest exact-KV pool that fits with room for the projector.
+  Derive byte rates from element count × block layout, then check them against
+  the ledger.
 - **`--ubatch-size` has an OPTIMUM on the 2x R9700 layer split, not a plateau —
   and the curve is BACKEND-SPECIFIC, so never carry it across (next bullet). Its
   compute buffers land about TWICE as heavy on the card that holds the output

dankclaw/voiceservice/Containerfile.engine

@@ -0,0 +1,140 @@
+# frank-tts-engine — the arm A TTS engine: qwentts.cpp's resident `tts-server`
+# (the CPU binary that frank-tts on :7772 forwards to). The runbook is
+# [[Frank TTS Engine]]; the fleet-facing endpoint is [[Frank TTS]].
+#
+# WHAT THIS IS. The upstream source is NOT vendored here: the image clones
+# ServeurpersoCom/qwentts.cpp at one pinned commit and builds it. Rebuilding is
+# therefore a network operation (github.com plus objects.githubusercontent.com
+# for the `ggml` submodule), and build_compose_image in scripts/deploy-remote.sh
+# skips it whenever this Containerfile's sha256 label already matches the built
+# image — the same offline-safe idiom as loki/alloy/comfyui, so a re-deploy of
+# an unchanged engine needs no network.
+#
+# THE PINNED COMMIT IS THE CONTRACT. 5916bf7c79dbb4e66fc059cdc507a79a23a28bb4
+# is the commit the 2026-10-18 CPU trial on Dankclaw measured (server-side TTFA
+# 94-112 ms, warm RTF 0.55-0.67, run spread +-0.01 — the numbers that won the
+# engine decision). Moving it means re-measuring, not just editing this line.
+# `ggml` is a submodule of the repo (the only one; vendor/cpp-httplib and
+# vendor/yyjson are ordinary directories in the tree), and the submodule commit
+# is recorded in the parent tree, so cloning the parent commit recursively is
+# reproducible without a second pin.
+#
+# THE BUILD LINE IS THE ONE PROVEN ON DANKCLAW, verbatim:
+#
+#   cmake -B build -DCMAKE_BUILD_TYPE=Release -DGGML_CCACHE=OFF \
+#       -DGGML_BACKEND_DL=OFF -DGGML_CPU_ALL_VARIANTS=OFF -DGGML_OPENMP=ON \
+#       -DGGML_BLAS=OFF -DGGML_CUDA=OFF -DGGML_HIP=OFF -DGGML_VULKAN=OFF \
+#       -DGGML_METAL=OFF -DGGML_SYCL=OFF -DGGML_RPC=OFF \
+#   && cmake --build build -j 8
+#
+# Every flag is load-bearing, so do not "tidy" it:
+#   GGML_BLAS=OFF is FORCED, not a preference — Dankclaw has libopenblas.so.0
+#     but no BLAS dev headers, so the upstream default (BLAS on) fails to
+#     configure. Upstream's own Dockerfile and buildcpu.sh both pass BLAS on,
+#     which is why this file does not copy them.
+#   GGML_CCACHE=OFF because a container build layer has no persistent ccache
+#     directory to hit; on, it only writes a useless one.
+#   GGML_OPENMP=ON is what makes the runtime need libgomp1 (installed below).
+#   GGML_BACKEND_DL=OFF / GGML_CPU_ALL_VARIANTS=OFF: upstream's images build
+#     every x86 ISA as a loadable backend so one image runs anywhere. This one
+#     is built on the machine that runs it, so the single native CPU backend is
+#     what was measured. That is also why no -DGGML_NATIVE is passed: ggml
+#     defaults it ON outside wasm/cross-compiles, i.e. -march=native for THIS
+#     host — correct while build host == run host, wrong if anyone ever builds
+#     this image elsewhere, which is why the fleet builds it on Dankclaw.
+#   CUDA/HIP/VULKAN/METAL/SYCL/RPC all OFF: this is a CPU endpoint (the trial
+#     ran on CPU; the box's GPUs belong to the text endpoints).
+#
+# BUILD SHARED LIBS, RUNTIME SMALL. BUILD_SHARED_LIBS defaults ON on Linux, so
+# tts-server links libggml*.so rather than swallowing them; the runtime stage
+# copies the binary and its shared objects out of the build tree and points
+# LD_LIBRARY_PATH at them, exactly as upstream's own Dockerfile does (the RPATH
+# baked at link time names the build directory, which does not exist here).
+#
+# BASE PINNED BY DIGEST, like every other image this fleet builds: the digest
+# is the multi-arch INDEX of ubuntu:24.04 as resolved from Docker Hub on
+# 2026-10-18; Dankclaw takes the amd64 entry. One base for both stages so there
+# is exactly one thing to re-resolve.
+#
+# NO HEALTHCHECK IN THIS FILE. The probe lives in the Quadlet unit
+# (HealthCmd=), which is the fleet pattern for anything with a shell — see the
+# alertmanager/prometheus units, and the opposite case in dankclaw/loki, whose
+# distroless image has no /bin/sh for the generator's CMD-SHELL wrapping.
+# `curl` is therefore installed in the runtime stage, for that probe only.
+
+ARG BASE_IMAGE=docker.io/library/ubuntu:24.04@sha256:68ee22004a9109b44973313b02ff7b1de250f1de0f5ecb628d73f579aaff33ac
+
+# ------------------------------------------------------------------ build
+FROM ${BASE_IMAGE} AS build
+
+RUN apt-get update -qq \
+    && apt-get install -y -qq --no-install-recommends \
+        ca-certificates cmake g++ git make \
+    && rm -rf /var/lib/apt/lists/*
+
+# Checked out detached at a full SHA, then the recorded submodule. No branch
+# name anywhere: a branch moves, this commit does not.
+ARG QWENTTS_COMMIT=5916bf7c79dbb4e66fc059cdc507a79a23a28bb4
+RUN git clone --no-checkout https://github.com/ServeurpersoCom/qwentts.cpp /src \
+    && git -C /src checkout --detach "${QWENTTS_COMMIT}" \
+    && git -C /src submodule update --init --depth 1 \
+    && git -C /src rev-parse HEAD \
+    && git -C /src submodule status
+
+WORKDIR /src
+RUN cmake -B build -DCMAKE_BUILD_TYPE=Release \
+        -DGGML_CCACHE=OFF \
+        -DGGML_BACKEND_DL=OFF \
+        -DGGML_CPU_ALL_VARIANTS=OFF \
+        -DGGML_OPENMP=ON \
+        -DGGML_BLAS=OFF \
+        -DGGML_CUDA=OFF \
+        -DGGML_HIP=OFF \
+        -DGGML_VULKAN=OFF \
+        -DGGML_METAL=OFF \
+        -DGGML_SYCL=OFF \
+        -DGGML_RPC=OFF \
+    && cmake --build build -j 8
+
+# ---------------------------------------------------------------- runtime
+FROM ${BASE_IMAGE}
+
+# libgomp1: the OpenMP runtime the build above links against. curl: the unit's
+# HealthCmd. ca-certificates: so that curl can speak https if anyone ever
+# points a probe at a URL with a scheme this host terminates elsewhere.
+RUN apt-get update -qq \
+    && apt-get install -y -qq --no-install-recommends \
+        ca-certificates curl libgomp1 \
+    && rm -rf /var/lib/apt/lists/*
+
+# Same unprivileged uid as the frank-tts façade (10000): the voice packs and the
+# model directory are host state mounted read-only, and one uid across the pair
+# means one thing to remember about what is world-readable.
+#
+# `useradd`, NOT `adduser`: this trimmed ubuntu:24.04 base ships no `adduser` at
+# all (verified 2026-10-18 against this digest — `adduser` is absent from the
+# base and is not pulled in by ca-certificates/curl/libgomp1 either), so an
+# `adduser` line dies at image-build time with crun's "executable file `adduser`
+# not found in $PATH". `useradd --system --uid 10000` succeeds and prints one
+# cosmetic warning (`uid 10000 is greater than SYS_UID_MAX 999`); the uid is the
+# point, and it is what matches the façade. The alpine façade Containerfile keeps
+# its own busybox `adduser -D -u 10000` — different base, different tool, same uid.
+RUN useradd --system --uid 10000 --home-dir /app --shell /usr/sbin/nologin tts
+
+WORKDIR /app
+COPY --from=build /src/build/tts-server /src/build/*.so* /app/
+COPY dankclaw/voiceservice/tts-engine-start.sh /app/start.sh
+# The boot warmer lives INSIDE the image because the engine publishes no port:
+# the unit reaches it with `podman exec`, and the script needs the same curl,
+# base64 and /voices the engine's own namespace has. It is a sibling of
+# start.sh, not a second entrypoint — CMD stays the server.
+COPY dankclaw/voiceservice/tts-engine-warm.sh /app/warm-voices.sh
+RUN chmod 755 /app/start.sh /app/warm-voices.sh
+
+# The binary's RPATH points inside the build tree; this is what makes it find
+# the libggml*.so copied beside it.
+ENV LD_LIBRARY_PATH=/app
+
+USER tts
+EXPOSE 8880
+CMD ["/app/start.sh"]

dankclaw/voiceservice/app.py

@@ -7,7 +7,10 @@ Consumers (the omp harness, OpenWebUI, open-notebook) speak the OpenAI
 directory under ``$VOICES_DIR`` and ``reference.wav`` inside it is what makes
 the name real. A name that has no reference is not a voice — the shim answers
 400 with the list that is, instead of silently narrating in a fallback voice
-(silent fallback is how a wrong-voice endpoint stays wrong for weeks).
+(silent fallback is how a wrong-voice endpoint stays wrong for weeks). A request
+that names NO voice at all takes ``$DEFAULT_VOICE``: that is a spoken choice in
+the env file rather than a surprise in the code, and the journal marks it
+``(default)`` so a name nobody asked for is never mistaken for one that was.
 
 Two backends sit behind the one surface, chosen by ``TTS_BACKEND``:
 
@@ -70,7 +73,7 @@ class Config:
 
     def __init__(self, voices_dir, backend, upstream, upstream_model, llama_bin,
                  llama_model, llama_mmproj, llama_lang, llama_threads, port,
-                 max_chars, timeout):
+                 max_chars, timeout, default_voice=""):
         self.voices_dir = Path(voices_dir)
         self.backend = backend
         self.upstream = upstream
@@ -83,6 +86,7 @@ class Config:
         self.port = port
         self.max_chars = max_chars
         self.timeout = timeout
+        self.default_voice = default_voice
 
     @classmethod
     def from_env(cls, environ=None):
@@ -100,6 +104,7 @@ class Config:
             port=_int(env, "SHIM_PORT", 7772),
             max_chars=_int(env, "SHIM_MAX_CHARS", 15000),
             timeout=float(_int(env, "SHIM_TIMEOUT", 600)),
+            default_voice=(env.get("DEFAULT_VOICE") or "").strip(),
         )
 
 
@@ -271,8 +276,13 @@ class SpeechHandler(BaseHTTPRequestHandler):
                                    "endpoint serves wav and mp3" % fmt))
             return
 
-        # `voice_id` is the alias the omp harness forwards for `voice`.
-        voice = body.get("voice") or body.get("voice_id")
+        # `voice_id` is the alias the omp harness forwards for `voice`. A request
+        # that names nothing takes the declared default — the harness has no
+        # setting that feeds a voice, so voice-less calls are the normal shape
+        # there, not a client bug.
+        requested = body.get("voice") or body.get("voice_id")
+        defaulted = not requested and bool(cfg.default_voice)
+        voice = requested or cfg.default_voice
         reference = resolve_voice(cfg.voices_dir, voice)
         if reference is None:
             available = list_voices(cfg.voices_dir)
@@ -297,8 +307,9 @@ class SpeechHandler(BaseHTTPRequestHandler):
 
         content_type = MP3_CONTENT_TYPE if fmt == "mp3" else WAV_CONTENT_TYPE
         self._bytes(200, audio, content_type)
-        self.log_message("speech voice=%s format=%s chars=%d -> %d bytes %s",
-                         voice, fmt, len(text), len(audio), content_type)
+        self.log_message("speech voice=%s%s format=%s chars=%d -> %d bytes %s",
+                         voice, " (default)" if defaulted else "", fmt,
+                         len(text), len(audio), content_type)
 
     # -- backends ----------------------------------------------------------
     def _speech_http(self, cfg, model, text, voice, reference):

dankclaw/voiceservice/quadlet/frank-tts-engine.container

@@ -0,0 +1,115 @@
+# Quadlet unit: frank-tts-engine (rootless, boot-persistent).
+#
+# Install path on dankclaw: ~/.config/containers/systemd/frank-tts-engine.container
+# Unit name: frank-tts-engine.service (container name: frank-tts-engine)
+#
+# WHAT IT IS. The arm A TTS engine: qwentts.cpp (pinned commit
+# 5916bf7c79dbb4e66fc059cdc507a79a23a28bb4) built into an image by
+# dankclaw/voiceservice/Containerfile.engine, running its resident `tts-server`
+# with the 1.7 B base talker Q4_K_M and the Q8_0 12 Hz tokenizer loaded ONCE at
+# startup. It is deliberately NOT a fleet endpoint: the endpoint consumers
+# address is **frank-tts on 7772** ([[Frank TTS]]), which resolves voice names,
+# re-encodes to mp3 and owns the timeout budget. Runbook: [[Frank TTS Engine]].
+#
+# WHY THIS ENGINE (Frank's call, 2026-10-18, criterion "whatever is better for
+# live output"): server-side time-to-first-audio 94-112 ms (86-451 ms end to
+# end through the façade), streaming that stays ahead of real time at warm RTF
+# 0.55-0.67, and a run-to-run spread of +-0.01 — against the mainline CLI path's
+# 0.93-0.99 at +-0.25, which crosses 1.0 often enough to stall a live stream.
+# The A/B that decided it is "Decision: arm A for live output" in
+# [[Local TTS and Voice Cloning]].
+#
+# IMAGE. Built locally by deploy-remote.sh (build_compose_image), like
+# loki/alloy/frank-tts. `Pull=never` plus the `localhost/` prefix are required:
+# this host's quadlet path cannot resolve a locally built tag from local storage
+# otherwise. The build is a network operation (it clones the pinned commit) and
+# is skipped when the Containerfile hash label already matches.
+#
+# NETWORK, AND WHY IT PUBLISHES NOTHING. The container sits on exactly one
+# network: the private `frank-tts-engine.network` (10.89.5.0/24). The façade
+# joins the same network and dials `http://frank-tts-engine:8880` — the
+# container DNS name, on the network that owns it. There is no `PublishPort` of
+# any kind, not even `127.0.0.1:8880`, and the reason is the lesson that 502'd
+# hermes: netavark DNATs published ports only, so a host-loopback publish is not
+# a path to a peer container — the façade could never have used it, and a bridge
+# container cannot reach the host's own loopback bind either (see
+# [[Container Network Namespaces]]). A publish would therefore buy exactly one
+# thing: an extra reachable surface on an engine that has no authentication, on
+# a box whose CPU is also carrying the text endpoints. Diagnostics do not need
+# it either — `podman exec frank-tts-engine curl http://127.0.0.1:8880/health`
+# speaks to the server from inside its own namespace, which is where the address
+# is valid.
+#
+# MEMORY / NO GPU. Peak RSS measured 5.7 GiB with both GGUFs resident
+# (2026-10-18 trial); no memory limit is set because the box has the room and a
+# limit would convert a busy moment into an OOM kill mid-utterance. No
+# /dev/kfd, no /dev/dri, no keep-groups: every GPU backend is compiled out of
+# the image, the endpoint is CPU-only by decision, and the GPUs on this host
+# belong to the text endpoints.
+#
+# THE VOICE MOUNT IS READ-ONLY AND IS FOR THE WARMER, NOT THE ENGINE. A voice
+# becomes known to the engine only through POST /v1/audio/voices, and the
+# registration is MEMORY ONLY — it does not survive a restart, which is exactly
+# why the warm hook below runs on every start. That hook runs INSIDE this
+# container (see ExecStartPost), so it reads the packs at /voices; `tts-server`
+# itself never opens the directory, it receives the reference audio as base64 in
+# the registration body. The façade mounts the same host directory read-only for
+# its own name list, so one directory stays the single source of a voice name.
+#
+# REGISTRY LAW, THE REASON EXECSTARTPOST EXISTS. The voice registry is memory
+# only: a restart forgets every voice, and re-registering does not warm one —
+# only synthesizing does — so a boot without this hook leaves the façade
+# answering 400 for every name. The per-voice cold penalty is real but small, and
+# not the trial's 6.2-8.0 s: measured on the built container 2026-10-18 against an
+# empty registry, the first synthesis of a freshly registered voice cost 1,883 ms
+# against 1,226-1,283 ms for the requests after it. The warm pass runs serially
+# (two short syntheses per voice, ~5 s each) and `TimeoutStartSec=900` keeps a growing library from
+# tripping systemd's default 90 s start deadline. The leading `-` on
+# ExecStartPost is load-bearing: with `Restart=always`, a warmer that exits
+# non-zero (a pack missing its reference.wav, the engine still loading past the
+# warmer's own patience) would restart the whole container and crash-loop the
+# endpoint forever. A failed warm must be a journal line, not a restart.
+#
+# The hook is `podman exec`, not a host script, because there is no address the
+# host could dial: this container publishes nothing (above). Exec-ing into it
+# also means the warmer inherits this unit's EnvironmentFile, so every knob it
+# has lives in scripts/frank-tts-engine.env beside the engine's own, and it sees
+# the same /voices and 127.0.0.1:8880 the engine does.
+#
+# HEALTH. `GET /health` answers `{"status":"ok"}` from the HTTP thread, not the
+# synthesis queue, so a busy engine still reads healthy and a dead one does not.
+# HealthStartPeriod covers the first model load. The command is argument-only
+# and needs /bin/sh — the generator wraps HealthCmd as CMD-SHELL — so the image
+# installs curl (see the opposite case in dankclaw/loki, whose distroless base
+# has no shell).
+
+[Unit]
+Description=frank-tts-engine (arm A qwentts.cpp TTS engine, internal :8880)
+After=network-online.target
+Wants=network-online.target
+
+[Container]
+ContainerName=frank-tts-engine
+Image=localhost/franksdank/frank-tts-engine:latest
+Pull=never
+Network=frank-tts-engine.network
+# No PublishPort, at all: the only reachable address this server has is the
+# bridge address the façade resolves by name. Diagnostics use `podman exec`.
+EnvironmentFile=/home/dank/serverAppConfigs/scripts/frank-tts-engine.env
+Volume=/home/dank/models/Qwen3-TTS-GGUF:/models:ro
+Volume=/home/dank/voices:/voices:ro
+HealthCmd=curl -fsS http://127.0.0.1:8880/health
+HealthInterval=30s
+HealthTimeout=10s
+HealthRetries=3
+HealthStartPeriod=120s
+
+[Service]
+Restart=always
+RestartSec=10
+# Model load (tens of seconds) plus two short syntheses per registered voice.
+TimeoutStartSec=900
+ExecStartPost=-/usr/bin/podman exec frank-tts-engine /app/warm-voices.sh
+
+[Install]
+WantedBy=default.target

dankclaw/voiceservice/quadlet/frank-tts-engine.network

@@ -0,0 +1,52 @@
+# Quadlet network: the private bridge of the voice pair (rootless).
+#
+# Install path on dankclaw: ~/.config/containers/systemd/frank-tts-engine.network
+# Unit name: frank-tts-engine-network.service (podman network name:
+# systemd-frank-tts-engine — quadlet prefixes "systemd-", so probe the runtime
+# name, never the filename; see [[Container Network Namespaces]]).
+#
+# WHY A PRIVATE BRIDGE FOR A PAUSE THAT LOOKS PUBLIC-FACING. frank-tts (:7772,
+# published, the one endpoint consumers address) and frank-tts-engine (:8880,
+# never published, the arm A qwentts.cpp server behind it) could both have
+# stayed on the fleet-wide dankclaw_default and resolved each other by name.
+# They are split off anyway, for two reasons:
+#
+# 1. THE HOST-LOOPBACK TRAP. The phase-1 shape in `scripts/frank-tts.env` still
+#    names `host.containers.internal:8880` as the upstream, on the assumption the
+#    engine runs on the host and publishes `127.0.0.1:8880`. That cannot work:
+#    netavark DNATs published ports only, a published port is not on any podman
+#    bridge, and a container cannot reach the host's own loopback bind — the same
+#    shape that 502'd hermes, and the reason the signal-relay hop needs a host LAN
+#    bind instead ([[Container Network Namespaces]], [[Homepage Status Probes]]).
+#    Putting both containers on one committed network removes the guess: the
+#    façade dials the engine's container DNS name on the network that owns it, and
+#    the engine publishes nothing at all.
+#
+# 2. THE ENGINE HAS NO AUTH AND NO QUEUE LIMIT WORTH THE NAME. `tts-server`
+#    answers anyone who can open a socket, and at `--max-batch 1` a second
+#    caller simply waits behind the first. Left on dankclaw_default every
+#    container on that net — open-webui, hermes, the *arr proxies — could drive
+#    a CPU synthesiser that occupies every other core on a box that also serves
+#    two text endpoints. On this bridge the only dialer is frank-tts: the engine
+#    publishes no port, so not even the host has an address to reach it at, and
+#    diagnostics go through `podman exec` instead.
+#
+# Kernel bridge, not slirp4netns: the 2026-08-22 open-webui incident (a dead
+# per-container userspace helper left a container that accepted TCP and reset
+# every request for two days, logging nothing). A bridge has no such helper.
+#
+# Subnet registry on dankclaw (rootless):
+#   10.88.0.0/16  default "podman" bridge
+#   10.89.0.0/24  gitea (systemd-gitea)
+#   10.89.1.0/24  compose stack (dankclaw_default)
+#   10.89.2.0/24  searxng (systemd-searxng)
+#   10.89.3.0/24  open-webui (systemd-open-webui)
+#   10.89.4.0/24  open-notebook (systemd-open-notebook)
+#   10.89.5.0/24  voice pair (systemd-frank-tts-engine)  <- this file
+# Pinned so the two container IPs stay deterministic across reboots, like the
+# other pinned nets; 10.89.5.0/24 was the next unclaimed /24 in this registry.
+
+[Network]
+Driver=bridge
+Subnet=10.89.5.0/24
+Gateway=10.89.5.1

dankclaw/voiceservice/quadlet/frank-tts.container

@@ -9,9 +9,9 @@
 # /home/dank/voices holding reference.wav; the shim refuses any name without
 # one (400 + the list that does exist) rather than narrating in a fallback
 # voice nobody chose. The engine behind it is a separate decision —
-# TTS_BACKEND in scripts/frank-tts.env picks between forwarding to an
-# OpenAI-shaped upstream on host :8880 and running a local CLI binary per
-# request.
+# TTS_BACKEND in scripts/frank-tts.env picks between forwarding to the
+# OpenAI-shaped engine (`frank-tts-engine`, [[Frank TTS Engine]]) and running a
+# local CLI binary per request.
 #
 # IMAGE. Built locally from dankclaw/voiceservice/Containerfile by
 # deploy-remote.sh (build_compose_image), like loki/alloy: python 3.12-alpine
@@ -19,16 +19,27 @@
 # Pull=never and the localhost/ prefix are required — this host's quadlet
 # path cannot resolve a locally built tag from local storage otherwise.
 #
-# NETWORK. Bridge (dankclaw_default), NOT host: nothing here needs a shared
-# loopback namespace, and the comfyui/loki/authentik units are bridge too.
-# Consequences both ways: consumers reach it on the published 7772, and the
-# shim reaches the host-side TTS engine through host.containers.internal
-# (never the LAN IP — a bridge netns cannot route to the host's own address
-# for every bind shape, and the fleet's law is the gateway name). NOTE for
-# whoever starts the :8880 engine: host.containers.internal reaches the host
-# network namespace, so the engine must bind an address that namespace
-# accepts; a 127.0.0.1-only bind is not it (the 2026-09-17 signal-relay hop
-# needed the host LAN bind for the same reason).
+# NETWORK. TWO attached networks, and the order is the one the open-notebook
+# pair uses: `dankclaw_default` first (the default route, and where consumers
+# live — they reach the published 7772, and open-notebook dials
+# `http://frank-tts:7772/v1` by container name), then the voice pair's private
+# bridge, `frank-tts-engine.network`, where the arm A engine lives. The shim's
+# upstream is therefore the engine's container DNS name
+# (`http://frank-tts-engine:8880`, scripts/frank-tts.env) and NOT
+# host.containers.internal: netavark DNATs published ports only, so a bridge
+# container cannot reach a host-loopback bind — the shape that 502'd hermes —
+# and the engine publishes nothing at all. That file MUST be installed beside
+# this unit (the engine's handler does it; the façade handler re-installs it for
+# `--only frank-tts`), because with a referenced Network= file missing the v1
+# generator refuses to produce this container unit at all.
+#
+# ORDERING. Wants+After on frank-tts-engine.service, not Requires: the façade
+# has a second backend (`TTS_BACKEND=llama-tts-cli`) that needs no upstream, and
+# an engine that will not start must not take this endpoint's unit down with it.
+# When both boot, this comes up after the engine, whose ExecStartPost warm pass
+# is part of its start — so the first request of the day meets a REGISTERED voice
+# (the registry is memory-only) rather than a 400, and skips the ~0.6 s penalty
+# the first synthesis of an unwarmed voice costs.
 #
 # VOICES. /home/dank/voices is host state, never repo state, and is mounted
 # READ-ONLY: this endpoint has no business writing voice packs. Because the
@@ -41,14 +52,16 @@
 # carries them deliberately.
 [Unit]
 Description=frank-tts (cloned-voice OpenAI-compatible TTS facade)
-After=network-online.target
+After=network-online.target frank-tts-engine.service
 Wants=network-online.target
+Wants=frank-tts-engine.service
 
 [Container]
 ContainerName=frank-tts
 Image=localhost/franksdank/frank-tts:latest
 Pull=never
 Network=dankclaw_default
+Network=frank-tts-engine.network
 PublishPort=7772:7772
 EnvironmentFile=/home/dank/serverAppConfigs/scripts/frank-tts.env
 Volume=/home/dank/voices:/voices:ro

dankclaw/voiceservice/tts-engine-start.sh

@@ -0,0 +1,89 @@
+#!/usr/bin/env bash
+# tts-engine-start.sh — the entrypoint of the frank-tts-engine image
+# (dankclaw/voiceservice/Containerfile.engine). It exists for one reason: the
+# knobs of the arm A engine are command-line flags, while the fleet's knobs
+# live in scripts/frank-tts-engine.env and reach the container through
+# EnvironmentFile=. This is the translation layer, and nothing else — no
+# supervision, no retries, no logging of its own. PID 1 stays the server, so
+# `podman stop` and the unit's Restart=always drive it directly.
+#
+# THE FLAGS THAT ARE NOT HERE, and must stay absent:
+#
+#   --threads / -t   does not exist in this build. src/backend.h computes the
+#                    CPU thread count as std::thread::hardware_concurrency()/2
+#                    (the comment there: GEMM shares SIMD units across
+#                    hyperthreads), and there is no flag to override it. So a
+#                    CPU affinity pin (CPUQuota=, taskset, a cpuset) silently
+#                    changes the engine's thread count instead of just its
+#                    placement — pinning is deliberately not done anywhere in
+#                    this stack. See the env file header for the same warning
+#                    aimed at the operator.
+#   --device         left at its default. Every GPU backend is compiled out of
+#                    the image, so the default device pick can only land on
+#                    CPU; naming a device would add a way to be wrong.
+#
+# Everything defaults to the shape the 2026-10-18 trial measured, so an empty
+# environment still boots the decided configuration: 1.7 B talker Q4_K_M with
+# the Q8_0 tokenizer, one request at a time, on the private bridge.
+set -euo pipefail
+
+# The binary path. Overridable for one reason: the bats seam runs a stub
+# instead of a 1.2 GiB model. Operators never set it — the image ships exactly
+# one binary at /app/tts-server.
+: "${QWENTTS_BIN:=/app/tts-server}"
+
+# Paths are CONTAINER paths (the host directories they come from are named in
+# scripts/frank-tts-engine.env and mounted by the Quadlet unit).
+: "${QWENTTS_MODEL:=/models/qwen-talker-1.7b-base-Q4_K_M.gguf}"
+: "${QWENTTS_CODEC:=/models/qwen-tokenizer-12hz-Q8_0.gguf}"
+
+# Reported by GET /v1/models, and what scripts/frank-tts.env's
+# TTS_UPSTREAM_MODEL names. A model id, not a filename: the file name would
+# leak a quantization choice into every consumer's config.
+: "${QWENTTS_ALIAS:=frank-tts-engine}"
+
+# 0.0.0.0 inside the container is not "public". tts-server defaults to
+# 127.0.0.1 (its own usage prints `--host <ip> Listen address (default:
+# 127.0.0.1)`), and inside a container netns a loopback bind is reachable by
+# nothing outside that namespace — the façade dials this container by its bridge
+# address on the private voice network, which is why the address has to be
+# broad. The unit PUBLISHES NOTHING (see
+# dankclaw/voiceservice/quadlet/frank-tts-engine.container: no PublishPort at
+# all, not even 127.0.0.1:8880), so the only namespaces that can reach
+# 0.0.0.0:8880 are that bridge and this container's own loopback — and its own
+# loopback is exactly where the boot warmer and the health probe speak.
+: "${QWENTTS_HOST:=0.0.0.0}"
+: "${QWENTTS_PORT:=8880}"
+
+# The language label used when a request omits one. `auto` is the upstream
+# default and what the trial ran.
+: "${QWENTTS_LANG:=auto}"
+
+# One request at a time. The server-side queue is a serialised FIFO at this
+# setting, which is what keeps the measured per-voice timings true; batching
+# on a CPU build splits the same cores between two syntheses and the warm RTF
+# margin (0.55-0.67 against real time 1.0) disappears. The engine's own
+# default is also 1; it is written here because it is a decision, not an
+# accident.
+: "${QWENTTS_MAX_BATCH:=1}"
+
+# Fail loudly BEFORE binding, so the journal says which artifact is missing
+# instead of the unit reporting a container that starts and dies. This is the
+# self-healing path: Restart=always re-runs it every RestartSec, and the same
+# sentence repeats until the operator fetches the weights
+# (scripts/download-frank-tts-engine-qwentts.sh).
+for artifact in "$QWENTTS_MODEL" "$QWENTTS_CODEC"; do
+    if [[ ! -r "$artifact" ]]; then
+        echo "frank-tts-engine: cannot read ${artifact}; run scripts/download-frank-tts-engine-qwentts.sh on the host (the /models mount is read-only and holds the two GGUF files)" >&2
+        exit 1
+    fi
+done
+
+exec "$QWENTTS_BIN" \
+    --model "$QWENTTS_MODEL" \
+    --codec "$QWENTTS_CODEC" \
+    --alias "$QWENTTS_ALIAS" \
+    --host "$QWENTTS_HOST" \
+    --port "$QWENTTS_PORT" \
+    --lang "$QWENTTS_LANG" \
+    --max-batch "$QWENTTS_MAX_BATCH"

dankclaw/voiceservice/tts-engine-warm.sh

@@ -0,0 +1,222 @@
+#!/usr/bin/env bash
+# tts-engine-warm.sh — the boot warmer of the arm A TTS engine, shipped inside
+# the frank-tts-engine image at /app/warm-voices.sh
+# (dankclaw/voiceservice/Containerfile.engine).
+#
+# WHO RUNS IT. Two callers, same binary:
+#
+#   1. The Quadlet unit, as
+#      `ExecStartPost=-/usr/bin/podman exec frank-tts-engine /app/warm-voices.sh`
+#      — after every start of the container, including every boot.
+#      `podman exec` rather than a host script because the engine publishes no
+#      port at all, so there is no address the host could dial; and because an
+#      exec inherits the unit's EnvironmentFile, which is what puts every knob of
+#      this script in scripts/frank-tts-engine.env next to the engine's own.
+#   2. scripts/deploy-remote.sh's deploy_frank_tts_engine, once per deploy, so a
+#      voice that did not warm becomes a deploy result instead of only a journal
+#      line (the unit's `-` prefix deliberately cannot fail the unit).
+#
+# WHY IT EXISTS AT ALL (the registry law). The voice registry is MEMORY ONLY: a
+# restart forgets every voice, and re-registering a voice does not warm it — only
+# synthesizing does. A boot that registers nothing therefore leaves frank-tts
+# answering 400 for every name, so this script registers every pack it finds. The
+# per-voice cold penalty is real but small, and smaller than the trial reported:
+# measured on the deployed build 2026-10-18 against an empty registry, the FIRST
+# synthesis of a freshly registered voice cost 1,883 ms against 1,226-1,283 ms for
+# the requests after it — about 0.6 s, not the trial's 6.2-8.0 s. Each voice gets
+# two identical requests so the journal carries both numbers, `voice <name>
+# cold=…ms warm=…ms`; cold ≈ warm is the expected shape, and a large gap is what
+# would mean the snapshot path is broken.
+#
+# THE VOICES. /voices — the host directory /home/dank/voices mounted read-only by
+# the unit, the same packs frank-tts mounts for its own name list. A pack is a
+# directory that contains reference.wav; everything else in it (manifest.json, the
+# engine's reference.spk / reference.rvq extraction, a 16 kHz variant) is not read
+# here. The registration payload is `{"name": <dir>, "wav_b64": <base64 of
+# reference.wav>}` with NO ref_text, which selects the embedding-only (x-vector)
+# voice — the shipped default, warm RTF ~0.57-0.63 against ICL's 0.67, and the one
+# this fleet can produce honestly because it has no trustworthy transcript for the
+# audition crops. Adding ref_text (with the codes) would flip that voice to
+# in-context-learning mode: better fidelity on a good transcript, slower, and only
+# worth it for batch work like a podcast render. That is a per-voice opt-in this
+# script deliberately does NOT exercise, and the door stays open: a pack that
+# wants ICL needs its text in the pack plus one key in the payload below.
+#
+# A lone `spk_b64` is a 400 (src/tts-server.h:480 — it is `wav_b64` or BOTH
+# `spk_b64` and `rvq_b64`), which is why the WAV travels and the .spk stays home.
+#
+# NOTHING HERE IS A SECRET, and nothing is logged that could be: the audio bytes
+# are discarded, the synthesized text comes from the env file, and the reference
+# clip is base64'd into a request body that is written to a temporary file and
+# handed to curl as `@file` — never echoed, and never placed on a command line,
+# because of the size law explained at the mktemp below.
+set -euo pipefail
+
+# The engine's own address, from inside its namespace. Loopback is valid HERE:
+# this script runs in the container, next to the server. There is deliberately no
+# host-visible address to use instead — the unit publishes nothing, because a
+# host-loopback publish would be unreachable from the façade anyway (netavark
+# DNATs published ports only) while adding a surface on an unauthenticated
+# server.
+: "${ENGINE_URL:=http://127.0.0.1:8880}"
+
+# Container path; the host directory behind it is named in the Quadlet unit.
+: "${VOICES_DIR:=/voices}"
+
+# How long to wait for the engine to answer /health. Model load dominates: the
+# two GGUFs (1.2 GiB + 291 MB) are read and the context built before the HTTP
+# thread binds, and a boot races every other unit on this box.
+: "${HEALTH_WAIT:=300}"
+
+# One short sentence, long enough to exercise the codec snapshot and short enough
+# that warming a library of voices is seconds, not minutes. Never varied per run:
+# the cold/warm numbers in the journal should mean the same thing every boot. The
+# synthesis asks for `wav`, the buffered path — the streamed path (`pcm`) is
+# different audio at the same seed, and `wav` is also what frank-tts asks for.
+: "${WARM_TEXT:=Warm up, one two three.}"
+
+# Per-request ceiling. A cold voice is 6-8 s by measurement; anything approaching
+# this is a stalled engine and should be reported rather than waited on forever —
+# systemd counts the whole warm pass against the unit's start deadline.
+: "${REQUEST_TIMEOUT:=120}"
+
+# The warm text goes into a JSON string literal by interpolation. Two steps make
+# whatever the two readers of scripts/frank-tts-engine.env deliver arrive as the
+# sentence itself:
+#
+# 1. Unwrap ONE shell-style quoting layer. bash (`set -a; source`) strips the
+#    quotes around a value with spaces; podman's `--env-file` does NOT — measured
+#    2026-10-18 against the image's pinned base, `WARM_TEXT="…"` reaches the
+#    container WITH its quotes. Unwrapped only when the whole value is exactly one
+#    quoted string (starts AND ends with `"` and holds no quote inside), so a
+#    sentence that legitimately contains quotes is never mangled.
+# 2. Escape the two characters that would corrupt or end a JSON string: a
+#    backslash, and a double quote.
+#
+# Without step 1 the body is `{"input":""Warm up…"",…}`, the engine's JSON parser
+# rejects it, every voice stays cold, and the boot still reads healthy. Voice NAMES
+# need neither step: the character class checked below admits no quote, no
+# backslash and no control byte.
+warm_text="$WARM_TEXT"
+if (( ${#warm_text} >= 2 )) && [[ "$warm_text" == \"*\" ]]; then
+    inner="${warm_text:1:${#warm_text}-2}"
+    [[ "$inner" != *'"'* ]] && warm_text="$inner"
+fi
+warm_json="${warm_text//\\/\\\\}"
+warm_json="${warm_json//\"/\\\"}"
+
+# The registration body is a FILE, never an argument. The kernel caps a single
+# command-line string at 32 pages — MAX_ARG_STRLEN = 131,072 bytes — and a shipped
+# reference clip base64's to about 1.27 MB, so passing the body as one argument
+# fails with E2BIG before curl is even executed. The first real boot of the unit
+# (2026-10-18, the three shipped packs) proved it end to end: `/usr/bin/curl:
+# Argument list too long` for every voice, reported as the misleading
+# "registration failed (HTTP no response)". `mktemp` lands in the container's
+# /tmp as the unprivileged `tts` user; one file for the whole pass, overwritten
+# per voice, removed on any exit — it is container scratch, not host state.
+body_file="$(mktemp -t frank-tts-warm.XXXXXX)"
+trap 'rm -f "$body_file"' EXIT
+
+fail=0
+log() { printf 'frank-tts-engine-warm: %s\n' "$*"; }
+
+# Wait for /health. It answers from the HTTP thread, so a 200 means the server is
+# listening; it says nothing about voices, which is what the rest of this script
+# is for.
+ready=0
+for ((i = 1; i <= HEALTH_WAIT; i++)); do
+    if curl -fsS --max-time 5 "${ENGINE_URL}/health" >/dev/null 2>&1; then
+        ready=1
+        break
+    fi
+    sleep 1
+done
+if (( ready == 0 )); then
+    log "engine did not answer ${ENGINE_URL}/health within ${HEALTH_WAIT}s; nothing warmed"
+    exit 1
+fi
+
+if [[ ! -d "$VOICES_DIR" ]]; then
+    log "no voice directory at ${VOICES_DIR}; nothing to warm (frank-tts will answer 400 with an empty voice list until packs are built)"
+    exit 0
+fi
+
+warmed=0
+for dir in "$VOICES_DIR"/*/; do
+    [[ -d "$dir" ]] || continue
+    name="${dir%/}"
+    name="${name##*/}"
+    if [[ ! -f "${dir}reference.wav" ]]; then
+        continue          # not a pack; frank-tts refuses this name too
+    fi
+    # The engine lowercases every voice name (tts_voice_name) while frank-tts
+    # matches the directory name exactly, so a mixed-case pack would work by
+    # accident on one side and not the other. Refuse it loudly instead. Pack
+    # names are also JSON string content here, so the character class is what
+    # keeps a directory name from writing structure into the request body.
+    if [[ ! "$name" =~ ^[a-z0-9][a-z0-9._-]*$ ]]; then
+        log "voice '${name}': name must be lowercase [a-z0-9._-] (the engine lowercases names; the shim does not) — skipped"
+        fail=1
+        continue
+    fi
+
+    # The audio enters through a redirection rather than a command substitution:
+    # the file is several hundred KB, and both a shell variable and an argument of
+    # that size are what this script used to die on.
+    {
+        printf '{"name":"%s","wav_b64":"' "$name"
+        base64 -w0 "${dir}reference.wav"
+        printf '"}'
+    } > "$body_file"
+    if ! code="$(curl -sS --max-time "$REQUEST_TIMEOUT" -o /dev/null -w '%{http_code}' \
+            -H 'Content-Type: application/json' --data-binary "@${body_file}" \
+            "${ENGINE_URL}/v1/audio/voices")" || [[ "$code" != "200" ]]; then
+        log "voice '${name}': registration failed (HTTP ${code:-no response}) — the shim will answer 400 for this name"
+        fail=1
+        continue
+    fi
+
+    # The cold pass. Its output is discarded; the point is the codec snapshot it
+    # leaves inside the engine.
+    start=$(date +%s%3N)
+    if ! curl -fsS --max-time "$REQUEST_TIMEOUT" -o /dev/null \
+            -H 'Content-Type: application/json' \
+            --data-binary "{\"input\":\"${warm_json}\",\"voice\":\"${name}\",\"response_format\":\"wav\"}" \
+            "${ENGINE_URL}/v1/audio/speech"; then
+        log "voice '${name}': registered, but the warm synthesis failed — first live request stays cold"
+        fail=1
+        continue
+    fi
+    cold=$(( $(date +%s%3N) - start ))
+
+    # The warm pass, same request. This is the number the fleet actually
+    # experiences, and it is what "the second request answers under a second" is
+    # measured against.
+    start=$(date +%s%3N)
+    if ! curl -fsS --max-time "$REQUEST_TIMEOUT" -o /dev/null \
+            -H 'Content-Type: application/json' \
+            --data-binary "{\"input\":\"${warm_json}\",\"voice\":\"${name}\",\"response_format\":\"wav\"}" \
+            "${ENGINE_URL}/v1/audio/speech"; then
+        log "voice '${name}': warm synthesis failed after a cold one that worked"
+        fail=1
+        continue
+    fi
+    warm=$(( $(date +%s%3N) - start ))
+
+    log "voice ${name} cold=${cold}ms warm=${warm}ms"
+    warmed=$(( warmed + 1 ))
+done
+
+# Failure first, emptiness second, and not the other way round: a pass where
+# every voice failed also has `warmed == 0`, and reading that as "nothing to do,
+# success" is how an endpoint that answers 400 for every voice name gets deployed
+# on a Friday.
+if (( fail )); then
+    log "${warmed} voice(s) warm, at least one failed (see the lines above)"
+    exit 1
+fi
+if (( warmed == 0 )); then
+    log "no voice with a reference.wav under ${VOICES_DIR}; engine is up but speaks nothing"
+    exit 0
+fi
+log "${warmed} voice(s) registered and warm"

scripts/build-voice-pack.sh

@@ -0,0 +1,483 @@
+#!/usr/bin/env bash
+# build-voice-pack.sh — turn a SOURCE recording plus a CROP OFFSET into a
+# deployable frank-tts voice pack: the reference WAV, the engine's own speaker
+# artifacts made from it, and manifest.json provenance.
+#
+# THE PACK. $PACKS_DIR/<voice>/ carries the three members the pack law in
+# scripts/frank-tts.env names:
+#
+#   reference.wav    the crop: 24 kHz mono PCM (pcm_s16le), 18-25 s of clean
+#                    single-speaker audio. This is what makes a voice NAME real
+#                    (dankclaw/voiceservice/app.py lists and resolves exactly
+#                    this file), so it is written LAST, once everything else in
+#                    the pack has been verified.
+#   reference.spk    the engine's x-vector: enc_dim 2048 f32 = 8,192 B.
+#   reference.rvq    the engine's RVQ code stream: 16 codebooks x 11 bits = 22 B
+#                    per 12.5 Hz frame = 22 * floor(samples / 1920).
+#   manifest.json    provenance: source path and sha256, crop start/end, sample
+#                    rate, duration, the tool + engine commit that made the
+#                    artifacts, and the voice name.
+#
+# Both artifacts come from the pinned engine build's speaker extractor — the
+# `qwen-codec` tool of qwentts.cpp at VOICE_PACK_ENGINE_COMMIT — run on the pack's
+# own WAV, and the extractor names them by swapping the input's extension, so
+# they land beside reference.wav with nothing to rename. Required, never a
+# replacement for the WAV: a voice another runtime cannot reuse is not saved.
+#
+# THE 10-SECOND GATE — THE REASON THIS SCRIPT EXISTS. Project-wide source-material
+# invariant: the first 10 s of any sample file used to generate voices is
+# forbidden material. An offset that starts inside that region is refused with a
+# nonzero exit BEFORE anything is created — no pack dir, no WAV, no artifact — and
+# the same gate is asserted a second time from the manifest that was just written
+# (plus the recorded sha256 against the source it claims). A pack carrying a
+# forbidden crop therefore cannot survive a build.
+#
+# THE ARTIFACT SIZES ARE CHECKED, NOT ASSUMED. They are a property of the codec
+# config inside the GGUF, so an engine bump that changes enc_dim or the codebook
+# count fails the build instead of shipping a pack the engine will reject at
+# synthesis time. Note the interaction with the WAV window: an 18.0 s crop is a
+# legal reference.wav but only 22 * 225 = 4,950 B of .rvq, under the recorded
+# 5,456 B floor, so the effective crop window is 19.84-25 s. That is a real
+# constraint and the builder says so up front rather than failing after a build;
+# serverAppConfigs-docs/Dankclaw/Voice Packs.md covers what to do on an engine bump.
+#
+# WHERE IT RUNS: the host that holds the engine build (Dankclaw). The extractor is
+# a CPU ggml binary — no GPU, no container, no fleet endpoint, no network. ffmpeg
+# does the crop; every spawned process runs `nice -n 19` so a pack build never
+# competes with the text endpoints on that box.
+#
+# IT NEVER DELETES. An existing pack is refused unless --force, and --force moves
+# the whole old directory aside into $PACKS_DIR/.AGENTTRASH/<voice>-<UTC>/ rather
+# than overwriting or unlinking a single byte.
+#
+# Usage:
+#   scripts/build-voice-pack.sh [OPTIONS] VOICE PACKS_DIR
+#   scripts/build-voice-pack.sh [OPTIONS] --all PACKS_DIR
+#
+# Options (anything not given comes from scripts/voice-packs.env):
+#   --env FILE      tunables file (default scripts/voice-packs.env)
+#   --source FILE   source recording for this voice
+#   --offset SEC    crop start, in seconds into the source (must be >= 10)
+#   --duration SEC  crop length; reference.wav comes out this long
+#   --sha256 HEX    expected sha256 of the source file
+#   --tool PATH     the pinned speaker extractor (qwen-codec)
+#   --all           build every voice in VOICE_PACKS, skipping none
+#   --dry-run       everything except the extractor: validate, cut the crop,
+#                   probe it, print the plan and the manifest it would write
+#   --force         retire an existing pack to .AGENTTRASH/ and rebuild
+#   -h, --help      this text
+set -euo pipefail
+
+REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+ENV_FILE="$REPO_ROOT/scripts/voice-packs.env"
+SOURCE_FORBIDDEN_SECONDS=10   # the source-material invariant; not a knob
+WORK_DIR=""                   # scratch dir a dry run owns, removed on exit
+
+# Only ever removes the scratch directory this script created for itself; pack
+# bytes on disk are retired to .AGENTTRASH/, never deleted (see --force).
+cleanup_work_dir() {
+    if [ -n "$WORK_DIR" ]; then
+        rm -rf -- "$WORK_DIR"
+    fi
+}
+trap cleanup_work_dir EXIT
+
+die() {
+    printf 'ERROR: %s\n' "$*" >&2
+    exit 1
+}
+
+usage() {
+    sed -n '2,/^set -euo/p' "${BASH_SOURCE[0]}" | sed '$d' | sed 's/^# \{0,1\}//'
+}
+
+# fcmp A OP B — float comparison (awk); OP is one of < <= > >= == and A/B are
+# already validated as plain decimals, so nothing user-shaped reaches awk as
+# program text.
+fcmp() {
+    awk -v a="$1" -v b="$3" "BEGIN { exit !(a $2 b) }"
+}
+
+# floorn X — greatest integer <= X, printed. Only ever called on positives.
+floorn() {
+    awk -v x="$1" 'BEGIN { printf "%d\n", int(x) }'
+}
+
+is_seconds() {
+    [[ "$1" =~ ^[0-9]+([.][0-9]+)?$ ]]
+}
+
+is_hex64() {
+    [[ "$1" =~ ^[0-9a-f]{64}$ ]]
+}
+
+# ---------------------------------------------------------------- arguments --
+VOICE=""
+PACKS_DIR=""
+ARG_SOURCE=""
+ARG_OFFSET=""
+ARG_DURATION=""
+ARG_SHA=""
+ARG_TOOL=""
+DRY_RUN=0
+FORCE=0
+BUILD_ALL=0
+
+while [ "$#" -gt 0 ]; do
+    case "$1" in
+        --env)      ENV_FILE="${2:?--env needs a path}"; shift 2 ;;
+        --source)   ARG_SOURCE="${2:?--source needs a file}"; shift 2 ;;
+        --offset)   ARG_OFFSET="${2:?--offset needs seconds}"; shift 2 ;;
+        --duration) ARG_DURATION="${2:?--duration needs seconds}"; shift 2 ;;
+        --sha256)   ARG_SHA="${2:?--sha256 needs a hex digest}"; shift 2 ;;
+        --tool)     ARG_TOOL="${2:?--tool needs a path}"; shift 2 ;;
+        --dry-run)  DRY_RUN=1; shift ;;
+        --force)    FORCE=1; shift ;;
+        --all)      BUILD_ALL=1; shift ;;
+        -h|--help)  usage; exit 0 ;;
+        --*)        die "unknown option: $1 (see --help)" ;;
+        *)
+            if [ -z "$VOICE" ]; then
+                VOICE="$1"
+            elif [ -z "$PACKS_DIR" ]; then
+                PACKS_DIR="$1"
+            else
+                die "unexpected argument: $1"
+            fi
+            shift
+            ;;
+    esac
+done
+
+[ -f "$ENV_FILE" ] || die "tunables file not found: $ENV_FILE"
+for tool in ffmpeg ffprobe jq sha256sum; do
+    command -v "$tool" >/dev/null 2>&1 || die "$tool is required and not on PATH"
+done
+
+# shellcheck disable=SC1090
+source "$ENV_FILE"
+
+# Tunables the env file owes us. Defaults are the engine facts read out of the
+# pinned tree; an env file that omits one still builds against the truth.
+VOICE_PACKS="${VOICE_PACKS:-}"
+SAMPLE_RATE="${VOICE_PACK_SAMPLE_RATE:-24000}"
+MIN_SECONDS="${VOICE_PACK_MIN_SECONDS:-18}"
+MAX_SECONDS="${VOICE_PACK_MAX_SECONDS:-25}"
+FRAME_RATE="${VOICE_PACK_FRAME_RATE:-12.5}"
+RVQ_BYTES_PER_FRAME="${VOICE_PACK_RVQ_BYTES_PER_FRAME:-22}"
+SPK_BYTES="${VOICE_PACK_SPK_BYTES:-8192}"
+RVQ_MIN_BYTES="${VOICE_PACK_RVQ_MIN_BYTES:-5456}"
+RVQ_MAX_BYTES="${VOICE_PACK_RVQ_MAX_BYTES:-6864}"
+TOOL="${ARG_TOOL:-${VOICE_PACK_TOOL:-}}"
+CODEC_MODEL="${VOICE_PACK_CODEC_MODEL:-}"
+TALKER_MODEL="${VOICE_PACK_TALKER_MODEL:-}"
+ENGINE_REPO="${VOICE_PACK_ENGINE_REPO:-https://github.com/ServeurpersoCom/qwentts.cpp}"
+ENGINE_COMMIT="${VOICE_PACK_ENGINE_COMMIT:-5916bf7c79dbb4e66fc059cdc507a79a23a28bb4}"
+DEVICE="${VOICE_PACK_DEVICE:-CPU}"
+THREADS="${VOICE_PACK_THREADS:-8}"
+NICE_LEVEL="${VOICE_PACK_NICE:-19}"
+TRASH_DIRNAME="${VOICE_PACK_TRASH_DIRNAME:-.AGENTTRASH}"
+DEFAULT_PACKS_DIR="${VOICE_PACK_DIR:-/home/dank/voices}"
+
+[ -n "$PACKS_DIR" ] || PACKS_DIR="$DEFAULT_PACKS_DIR"
+[ -n "$PACKS_DIR" ] || die "no packs directory (pass it as an argument)"
+is_seconds "$SAMPLE_RATE" || die "VOICE_PACK_SAMPLE_RATE is not a number: $SAMPLE_RATE"
+is_seconds "$MIN_SECONDS" || die "VOICE_PACK_MIN_SECONDS is not a number: $MIN_SECONDS"
+is_seconds "$MAX_SECONDS" || die "VOICE_PACK_MAX_SECONDS is not a number: $MAX_SECONDS"
+
+# hop / frame arithmetic, derived once: the codec runs at FRAME_RATE Hz over
+# SAMPLE_RATE audio, so one frame is HOP_SAMPLES samples and one second is
+# FRAME_RATE frames.
+HOP_SAMPLES="$(floorn "$(awk -v r="$SAMPLE_RATE" -v f="$FRAME_RATE" 'BEGIN { print r / f }')")"
+[ "$HOP_SAMPLES" -gt 0 ] || die "VOICE_PACK_FRAME_RATE ($FRAME_RATE) exceeds the sample rate"
+BYTES_PER_SECOND="$(awk -v b="$RVQ_BYTES_PER_FRAME" -v f="$FRAME_RATE" 'BEGIN { print b * f }')"
+
+# rvq_bytes_for DURATION — packed size the extractor will emit for a crop this
+# long: whole frames only, because it truncates to the hop boundary.
+rvq_bytes_for() {
+    local samples frames
+    samples="$(awk -v d="$1" -v r="$SAMPLE_RATE" 'BEGIN { printf "%d\n", int(d * r + 0.5) }')"
+    frames=$((samples / HOP_SAMPLES))
+    printf '%d\n' "$((frames * RVQ_BYTES_PER_FRAME))"
+}
+
+# ------------------------------------------------------------------- build --
+build_voice() {
+    local voice="$1"
+    # The pack dir name is the voice name on the wire: app.py's VOICE_NAME_RE
+    # matches it exactly while the engine lowercases names internally, so an
+    # uppercase or punctuated name would be reported one way by the façade and
+    # another by the engine. Lowercase only, and nothing that could escape
+    # $PACKS_DIR.
+    [[ "$voice" =~ ^[a-z0-9][a-z0-9._-]{0,63}$ ]] ||
+        die "voice name '$voice' is not a lowercase [a-z0-9._-] name starting with alphanumerics (app.py resolves it verbatim; the engine lowercases it)"
+
+    local prefix
+    prefix="VOICE_PACK_$(printf '%s' "$voice" | tr '[:lower:]' '[:upper:]' | tr -c '[:alnum:]' '_')"
+    local source_var="${prefix}_SOURCE" offset_var="${prefix}_OFFSET"
+    local duration_var="${prefix}_DURATION" sha_var="${prefix}_SHA256"
+    local source="${ARG_SOURCE:-${!source_var:-}}"
+    local offset="${ARG_OFFSET:-${!offset_var:-}}"
+    local duration="${ARG_DURATION:-${!duration_var:-}}"
+    local want_sha="${ARG_SHA:-${!sha_var:-}}"
+
+    if [ -z "$voice" ] || [ -z "$source" ]; then
+        die "no source for '$voice': pass --source or set ${source_var} in $ENV_FILE"
+    fi
+    [ -n "$offset" ] || die "no crop offset for '$voice': pass --offset or set ${offset_var}"
+    [ -n "$duration" ] || die "no crop duration for '$voice': pass --duration or set ${duration_var}"
+    is_seconds "$offset" || die "crop offset '$offset' is not a number of seconds"
+    is_seconds "$duration" || die "crop duration '$duration' is not a number of seconds"
+    [ -f "$source" ] && [ -r "$source" ] || die "source not readable: $source"
+
+    # === THE GATE. Source seconds 0..10 are forbidden voice material, full stop.
+    if ! fcmp "$offset" '>=' "$SOURCE_FORBIDDEN_SECONDS"; then
+        die "source-material invariant violated: the crop must start past the first ${SOURCE_FORBIDDEN_SECONDS} s of the source file, and '$voice' asks for ${offset} s into $source. Pick an offset at or past ${SOURCE_FORBIDDEN_SECONDS} s — nothing was written."
+    fi
+
+    local pack_dir="$PACKS_DIR/$voice"
+    if [ "$DRY_RUN" -ne 1 ] && [ -e "$pack_dir" ] && [ "$FORCE" -ne 1 ]; then
+        die "$pack_dir already exists; nothing was touched. Re-run with --force to retire it to $PACKS_DIR/$TRASH_DIRNAME/ and rebuild."
+    fi
+
+    local source_duration source_bytes source_sha
+    source_duration="$(ffprobe -v error -show_entries format=duration -of default=nw=1:nk=1 "$source")"
+    is_seconds "$source_duration" || die "ffprobe reports no numeric duration for $source: '$source_duration'"
+    source_bytes="$(stat -c%s "$source")"
+    if ! fcmp "$(awk -v a="$offset" -v d="$duration" 'BEGIN { print a + d }')" '<=' "$source_duration"; then
+        die "crop ends at $(awk -v a="$offset" -v d="$duration" 'BEGIN { print a + d }') s but $source is only $source_duration s; the crop would come out short"
+    fi
+    if ! fcmp "$duration" '>=' "$MIN_SECONDS" || ! fcmp "$duration" '<=' "$MAX_SECONDS"; then
+        die "crop duration $duration s is outside the ${MIN_SECONDS}-${MAX_SECONDS} s reference window"
+    fi
+    local crop_end planned_rvq
+    crop_end="$(awk -v a="$offset" -v d="$duration" 'BEGIN { print a + d }')"
+    planned_rvq="$(rvq_bytes_for "$duration")"
+    if ! fcmp "$planned_rvq" '>=' "$RVQ_MIN_BYTES" || ! fcmp "$planned_rvq" '<=' "$RVQ_MAX_BYTES"; then
+        die "a $duration s crop packs to ${planned_rvq} B of .rvq, outside the recorded engine window ${RVQ_MIN_BYTES}-${RVQ_MAX_BYTES} B; lengthen the crop (that window starts at $(awk -v m="$RVQ_MIN_BYTES" -v b="$BYTES_PER_SECOND" 'BEGIN { print m / b }') s) — the source, not the codec, sets this floor"
+    fi
+
+    echo "VOICE      $voice"
+    echo "SOURCE     $source ($source_bytes bytes, ${source_duration} s)"
+    echo "CROP       ${offset} s .. ${crop_end} s (${duration} s) — past the ${SOURCE_FORBIDDEN_SECONDS} s forbidden region"
+
+    source_sha="$(sha256sum "$source" | awk '{ print $1 }')"
+    if [ -n "$want_sha" ]; then
+        is_hex64 "$want_sha" || die "expected sha256 '$want_sha' is not 64 hex digits"
+        [ "$source_sha" = "$want_sha" ] ||
+            die "source sha256 is $source_sha, expected $want_sha: $source is not the file these offsets were cut from"
+    fi
+    echo "SHA256     $source_sha"
+
+    # Where the crop is cut. A dry run keeps its work in a scratch dir it owns;
+    # a real build stages INSIDE the pack dir so the final rename is on one
+    # filesystem and the pack becomes visible only when it is whole.
+    local stage_dir
+    if [ "$DRY_RUN" -eq 1 ]; then
+        WORK_DIR="$(mktemp -d "${TMPDIR:-/tmp}/voice-pack-$voice.XXXXXX")"
+        stage_dir="$WORK_DIR"
+    else
+        mkdir -p "$PACKS_DIR"
+        if [ -e "$pack_dir" ]; then
+            local trash
+            trash="$PACKS_DIR/$TRASH_DIRNAME/$voice-$(date -u +%Y%m%dT%H%M%SZ)"
+            mkdir -p "$(dirname "$trash")"
+            mv "$pack_dir" "$trash"
+            echo "RETIRED    $pack_dir -> $trash (nothing deleted)"
+        fi
+        mkdir "$pack_dir" || die "cannot create $pack_dir (it may exist now); nothing was overwritten"
+        stage_dir="$pack_dir"
+    fi
+    local stage_wav="$stage_dir/staging-reference.wav"
+
+    nice -n "$NICE_LEVEL" env OMP_NUM_THREADS="$THREADS" \
+        ffmpeg -hide_banner -loglevel error -y \
+        -ss "$offset" -t "$duration" -i "$source" \
+        -map 0:a:0 -vn -ac 1 -ar "$SAMPLE_RATE" -c:a pcm_s16le "$stage_wav"
+
+    local wav_rate wav_channels wav_codec wav_duration
+    wav_rate="$(ffprobe -v error -select_streams a:0 -show_entries stream=sample_rate -of default=nw=1:nk=1 "$stage_wav")"
+    wav_channels="$(ffprobe -v error -select_streams a:0 -show_entries stream=channels -of default=nw=1:nk=1 "$stage_wav")"
+    wav_codec="$(ffprobe -v error -select_streams a:0 -show_entries stream=codec_name -of default=nw=1:nk=1 "$stage_wav")"
+    wav_duration="$(ffprobe -v error -select_streams a:0 -show_entries stream=duration -of default=nw=1:nk=1 "$stage_wav")"
+    is_seconds "$wav_rate" || die "ffprobe reports no numeric sample rate for the crop: '$wav_rate'"
+    is_seconds "$wav_duration" || die "ffprobe reports no numeric duration for the crop: '$wav_duration'"
+    [ "$wav_rate" = "$SAMPLE_RATE" ] || die "reference.wav came out at ${wav_rate} Hz, not ${SAMPLE_RATE}"
+    [ "$wav_channels" = "1" ] || die "reference.wav came out with $wav_channels channels, not mono"
+    [ "$wav_codec" = "pcm_s16le" ] || die "reference.wav came out as $wav_codec, not the pcm_s16le the law names"
+    if ! fcmp "$wav_duration" '>=' "$MIN_SECONDS" || ! fcmp "$wav_duration" '<=' "$MAX_SECONDS"; then
+        die "reference.wav is ${wav_duration} s, outside the ${MIN_SECONDS}-${MAX_SECONDS} s window"
+    fi
+    echo "REFERENCE  ${wav_rate} Hz ${wav_codec} mono, ${wav_duration} s, $(stat -c%s "$stage_wav") bytes"
+
+    local spk_file="$stage_dir/staging-reference.spk" rvq_file="$stage_dir/staging-reference.rvq"
+    local stage_log="$stage_dir/staging-qwen-codec.log"
+    local spk_bytes=0 rvq_bytes=0 produced=false
+    if [ "$DRY_RUN" -eq 1 ]; then
+        if [ -n "$TOOL" ] && [ -x "$TOOL" ]; then
+            echo "EXTRACTOR  $TOOL (present; --dry-run will not run it)"
+        else
+            echo "EXTRACTOR  not present (${TOOL:-unset}) — --dry-run does not need it"
+        fi
+        echo "PLANNED    reference.spk ${SPK_BYTES} B, reference.rvq $(rvq_bytes_for "$wav_duration") B"
+    else
+        [ -n "$TOOL" ] && [ -x "$TOOL" ] ||
+            die "speaker extractor missing or not executable: ${TOOL:-VOICE_PACK_TOOL unset} (use --dry-run to build everything up to this point)"
+        [ -f "$CODEC_MODEL" ] || die "codec model missing: $CODEC_MODEL"
+        [ -f "$TALKER_MODEL" ] || die "talker model missing: $TALKER_MODEL"
+        # The extractor takes the WAV and writes its outputs next to it with the
+        # extension swapped — there is no -o, so the staged name decides where
+        # the artifacts land.
+        local extractor=("$TOOL" --model "$CODEC_MODEL" --talker "$TALKER_MODEL" -i "$stage_wav")
+        if [ -n "$DEVICE" ]; then
+            extractor+=(--device "$DEVICE")
+        fi
+        echo "EXTRACT    $(basename "$TOOL") at $ENGINE_COMMIT (device ${DEVICE:-auto}, $THREADS threads)"
+        if ! nice -n "$NICE_LEVEL" env OMP_NUM_THREADS="$THREADS" \
+            "${extractor[@]}" 2>&1 | tee "$stage_log" >&2; then
+            die "$TOOL failed on $stage_wav (its output is in $stage_log); the pack was not published"
+        fi
+        [ -f "$spk_file" ] || die "$TOOL wrote no $spk_file (see $stage_log)"
+        [ -f "$rvq_file" ] || die "$TOOL wrote no $rvq_file (see $stage_log)"
+        spk_bytes="$(stat -c%s "$spk_file")"
+        rvq_bytes="$(stat -c%s "$rvq_file")"
+        local expect_rvq
+        expect_rvq="$(rvq_bytes_for "$wav_duration")"
+        [ "$spk_bytes" = "$SPK_BYTES" ] ||
+            die "reference.spk is $spk_bytes B, expected ${SPK_BYTES} B (enc_dim x f32). The engine changed its speaker encoder — see [[Voice Packs]] before shipping this pack"
+        [ "$rvq_bytes" = "$expect_rvq" ] ||
+            die "reference.rvq is $rvq_bytes B, expected ${expect_rvq} B for a ${wav_duration} s crop (22 B per 12.5 Hz frame)"
+        if ! fcmp "$rvq_bytes" '>=' "$RVQ_MIN_BYTES" || ! fcmp "$rvq_bytes" '<=' "$RVQ_MAX_BYTES"; then
+            die "reference.rvq is $rvq_bytes B, outside the recorded engine window ${RVQ_MIN_BYTES}-${RVQ_MAX_BYTES} B — an engine bump? see [[Voice Packs]]"
+        fi
+        produced=true
+        echo "ARTIFACTS  reference.spk ${spk_bytes} B, reference.rvq ${rvq_bytes} B"
+    fi
+
+    local built stage_manifest
+    built="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+    stage_manifest="$stage_dir/staging-manifest.json"
+    jq -n \
+        --arg voice "$voice" \
+        --arg built "$built" \
+        --arg builder "scripts/build-voice-pack.sh" \
+        --arg env_file "$ENV_FILE" \
+        --arg src "$source" \
+        --arg src_sha "$source_sha" \
+        --argjson src_bytes "$source_bytes" \
+        --argjson src_duration "$source_duration" \
+        --argjson offset "$offset" \
+        --argjson end "$crop_end" \
+        --argjson duration "$duration" \
+        --argjson forbidden "$SOURCE_FORBIDDEN_SECONDS" \
+        --argjson rate "$SAMPLE_RATE" \
+        --argjson wav_duration "$wav_duration" \
+        --arg wav_codec "$wav_codec" \
+        --argjson wav_channels "$wav_channels" \
+        --argjson wav_bytes "$(stat -c%s "$stage_wav")" \
+        --arg tool "${TOOL:-unset}" \
+        --arg repo "$ENGINE_REPO" \
+        --arg commit "$ENGINE_COMMIT" \
+        --arg codec "$CODEC_MODEL" \
+        --arg talker "$TALKER_MODEL" \
+        --arg device "$DEVICE" \
+        --argjson produced "$produced" \
+        --argjson spk_bytes "$spk_bytes" \
+        --argjson rvq_bytes "$rvq_bytes" \
+        --argjson planned_rvq "$(rvq_bytes_for "$wav_duration")" \
+        --argjson dry_run "$DRY_RUN" \
+        '{
+            voice: $voice,
+            kind: "voice-pack",
+            built_utc: $built,
+            builder: $builder,
+            tunables: $env_file,
+            dry_run: ($dry_run == 1),
+            source: {
+                path: $src,
+                sha256: $src_sha,
+                bytes: $src_bytes,
+                duration_seconds: $src_duration
+            },
+            crop: {
+                offset_seconds: $offset,
+                end_seconds: $end,
+                duration_seconds: $duration
+            },
+            reference: {
+                file: "reference.wav",
+                codec: $wav_codec,
+                sample_rate: $rate,
+                channels: $wav_channels,
+                duration_seconds: $wav_duration,
+                bytes: $wav_bytes
+            },
+            artifacts: {
+                produced: $produced,
+                tool: $tool,
+                engine_repo: $repo,
+                engine_commit: $commit,
+                device: $device,
+                codec_model: $codec,
+                talker_model: $talker,
+                spk: {file: "reference.spk", bytes: $spk_bytes},
+                rvq: {file: "reference.rvq", bytes: $rvq_bytes, planned_bytes: $planned_rvq}
+            },
+            invariant: {
+                name: "source-material invariant",
+                rule: "a voice crop MUST start past the first 10 seconds of the source file",
+                forbidden_source_seconds: $forbidden,
+                crop_offset_seconds: $offset
+            }
+        }' >"$stage_manifest"
+
+    # Assert the gate a second time, FROM the manifest, next to the bytes it
+    # describes. Anything short of a pass leaves the staged pack unpublished.
+    local recorded_offset recorded_sha
+    recorded_offset="$(jq -r '.crop.offset_seconds' "$stage_manifest")"
+    recorded_sha="$(jq -r '.source.sha256' "$stage_manifest")"
+    jq -e --argjson min "$SOURCE_FORBIDDEN_SECONDS" \
+        '(.crop.offset_seconds | type == "number") and .invariant.forbidden_source_seconds == $min and (.crop.offset_seconds >= $min) and (.invariant.name == "source-material invariant")' \
+        "$stage_manifest" >/dev/null ||
+        die "manifest assertion failed: .crop.offset_seconds ($recorded_offset) does not clear the ${SOURCE_FORBIDDEN_SECONDS} s source-material invariant"
+    [ "$recorded_sha" = "$source_sha" ] ||
+        die "manifest assertion failed: .source.sha256 ($recorded_sha) is not the hash of $source ($source_sha)"
+    jq -e '(.voice | type == "string") and (.reference.sample_rate | type == "number") and (.reference.duration_seconds | type == "number") and (.artifacts.engine_commit | length == 40)' \
+        "$stage_manifest" >/dev/null ||
+        die "manifest assertion failed: voice / reference / engine provenance fields are not all present"
+    echo "MANIFEST   crop offset $recorded_offset s clears the ${SOURCE_FORBIDDEN_SECONDS} s invariant"
+
+    if [ "$DRY_RUN" -eq 1 ]; then
+        echo "MANIFEST_BEGIN"
+        cat "$stage_manifest"
+        echo "MANIFEST_END"
+        echo "PLAN       would write $pack_dir/{reference.wav,reference.spk,reference.rvq,manifest.json}"
+        echo "DRYRUN     $voice: inputs valid, crop cut and probed, extractor not run"
+    else
+        # reference.wav is the gate the shim reads, so it lands last: the voice
+        # name never exists on disk in a state the artifacts are not behind it.
+        mv "$stage_log" "$pack_dir/qwen-codec.log"
+        mv "$spk_file" "$pack_dir/reference.spk"
+        mv "$rvq_file" "$pack_dir/reference.rvq"
+        mv "$stage_manifest" "$pack_dir/manifest.json"
+        mv "$stage_wav" "$pack_dir/reference.wav"
+        echo "BUILT      $pack_dir (voice '$voice': ${wav_duration} s, spk ${spk_bytes} B, rvq ${rvq_bytes} B)"
+        echo "VOICE_PACK_BUILT $voice $pack_dir"
+    fi
+
+}
+
+if [ "$BUILD_ALL" -eq 1 ]; then
+    [ -z "$VOICE" ] || die "--all takes no voice name (got '$VOICE'); the list comes from VOICE_PACKS"
+    for flag in "$ARG_SOURCE" "$ARG_OFFSET" "$ARG_DURATION" "$ARG_SHA"; do
+        [ -z "$flag" ] || die "--all reads every crop from $ENV_FILE; --source/--offset/--duration/--sha256 would apply one value to all of them"
+    done
+    read -r -a voices <<<"$VOICE_PACKS"
+    [ "${#voices[@]}" -gt 0 ] || die "VOICE_PACKS is empty in $ENV_FILE"
+    for voice in "${voices[@]}"; do
+        build_voice "$voice"
+    done
+else
+    [ -n "$VOICE" ] || { usage >&2; die "no voice name given"; }
+    build_voice "$VOICE"
+fi

scripts/deploy-plan.py

@@ -62,6 +62,11 @@ SERVICE_ORDER = (
     "sonarr",
     "lidarr",
     "readarr",
+    # The voice pair keeps the inference family's ordering rule: the engine is
+    # a dependency of the 7772 facade, so it is planned (and therefore
+    # restarted) first.
+    "frank-tts-engine",
+    "frank-tts",
     "frank-dragoon",
     "frank-zealot",
     "frank-archon",
@@ -97,6 +102,8 @@ DANKCLAW_SERVICES = {
     "homepage",
     "frank-dragoon",
     "frank-zealot",
+    "frank-tts-engine",
+    "frank-tts",
 }
 
 DANKSERVER_SERVICES = {
@@ -326,6 +333,27 @@ def services_for_path(path: str, target: str) -> set[str]:
             # plans the pair, which deploy_open_notebook starts database-first.
             _add(services, "open-notebook")
             return services
+        if len(parts) >= 2 and parts[1] == "voiceservice":
+            # The voice stack's containers share one directory but are TWO
+            # deployables — the arm A engine and the 7772 façade in front of it
+            # — so this maps per file, the way the authentik trio does, and not
+            # per directory. Anything that is not named after one of the two
+            # services plans nothing, exactly as it did before the pair was
+            # registered.
+            if parts[-1] in {"frank-tts-engine.container", "frank-tts-engine.network",
+                             "Containerfile.engine", "tts-engine-start.sh",
+                             "tts-engine-warm.sh"}:
+                _add(services, "frank-tts-engine")
+            # The 7772 façade is the other deployable in this directory. The
+            # bridge file is named after the ENGINE unit (install_quadlet copies
+            # `$unit.network` beside `$unit.container`), yet both units attach
+            # to it, so a subnet change is a change to both. Anything else here
+            # belongs to neither deployable and plans nothing.
+            if parts[-1] in {"frank-tts.container", "app.py", "Containerfile"}:
+                _add(services, "frank-tts")
+            if parts[-1] == "frank-tts-engine.network":
+                _add(services, "frank-tts")
+            return services
         # frank-dragoon left the quadlet shape on 2026-09-19 (CIRU v4.4.1 host
         # build, root unit): its files live in scripts/ and map there.
         if len(parts) >= 2 and parts[1] == "observability":
@@ -429,6 +457,21 @@ def services_for_path(path: str, target: str) -> set[str]:
             # what the live frank-dragoon endpoint renders, so it plans
             # frank-dragoon.
             _add(services, "frank-dragoon")
+        if name == "frank-tts-engine.env":
+            # The engine's knobs are command-line flags, and this file is the
+            # repo's copy of them (the image entrypoint translates one line to
+            # one flag), so editing it is a restart of the engine. It also
+            # carries the boot warmer's three knobs, because the warmer is
+            # exec-ed into this container and inherits the same EnvironmentFile.
+            # A restart is what re-registers and re-warms every voice: the
+            # engine's voice registry is memory-only. (The warmer itself lives
+            # with the image, mapped above with the files it is built from, like
+            # the serve scripts of frank-zealot and frank-archon are mapped to
+            # the units that run them.)
+            # scripts/download-frank-tts-engine-qwentts.sh deliberately plans
+            # nothing: it fetches host-side state, like every other download
+            # script in this directory.
+            _add(services, "frank-tts-engine")
         if name in {"frank-archon.env", "frank-archon.service", "serve-frank-archon.sh"}:
             # llama.cpp frank-archon (2026-09-26, replacing the Lucebox
             # DS4.1 quadlet) keeps its unit, env and serve files here the

scripts/deploy-remote.sh

@@ -92,6 +92,7 @@ service_is_allowed() {
         dankclaw:caddy|dankclaw:homepage|dankclaw:seerr|dankclaw:marreta|\
         dankclaw:open-notebook|\
         dankclaw:frank-dragoon|dankclaw:frank-zealot|\
+        dankclaw:frank-tts-engine|dankclaw:frank-tts|\
         dankserver:romm-mariadb|dankserver:romm-redis|dankserver:romm|\
         dankserver:copyparty|dankserver:jellyfin|dankserver:calibre-web|dankserver:calibre-server|dankserver:plex|dankserver:tautulli|\
         dankserver:prowlarr|dankserver:qbittorrent|dankserver:radarr|\
@@ -540,6 +541,14 @@ deploy_observability() {
 
 build_compose_image() {
     local service="$1" image cfhash oldhash containerfile
+    # Every file the image COPIES IN, beside the Containerfile. The skip below
+    # compares a hash against the image's `cfhash` label, so anything the build
+    # bakes must be in that hash or the deploy silently keeps serving the old
+    # bytes: an edited app.py or warm hook leaves the Containerfile untouched,
+    # the label matches, `podman build` never runs, and the health gate passes on
+    # a stale container. Services whose Containerfile pulls everything at
+    # build time (comfyui, loki, alloy) keep an empty list.
+    local -a extra=()
     case "$service" in
         comfyui)
             image=comfyui-rocm:gfx1151
@@ -549,11 +558,32 @@ build_compose_image() {
             image="franksdank/$service:latest"
             containerfile="dankclaw/$service/Containerfile"
             ;;
+        frank-tts)
+            # The 7772 façade: stdlib python + ffmpeg, app.py copied in. Listed
+            # explicitly because build_compose_image's `*)` arm returns 0 — an
+            # unlisted service builds nothing and the unit's Pull=never then
+            # fails on a tag that was never made.
+            image=franksdank/frank-tts:latest
+            containerfile=dankclaw/voiceservice/Containerfile
+            extra=(dankclaw/voiceservice/app.py)
+            ;;
+        frank-tts-engine)
+            # The arm A TTS engine (qwentts.cpp `tts-server`). Built from
+            # source at a pinned upstream commit, so the build needs network
+            # and the cfhash label below is what keeps an unchanged re-deploy
+            # offline: the clone only happens when this Containerfile changes.
+            image=franksdank/frank-tts-engine:latest
+            containerfile=dankclaw/voiceservice/Containerfile.engine
+            # start.sh is the image's CMD and the warmer is the unit's
+            # ExecStartPost; both are COPY'd in, so both decide what this image is.
+            extra=(dankclaw/voiceservice/tts-engine-start.sh
+                   dankclaw/voiceservice/tts-engine-warm.sh)
+            ;;
         *)
             return 0
             ;;
     esac
-    cfhash="$(sha256sum "$containerfile" | cut -d' ' -f1)"
+    cfhash="$(sha256sum "$containerfile" "${extra[@]}" | cut -d' ' -f1 | tr -d '\n')"
     oldhash="$(podman image inspect "$image" --format '{{index .Config.Labels "cfhash"}}' 2>/dev/null || echo none)"
     if [[ "$oldhash" != "$cfhash" ]]; then
         # --format docker is required, not cosmetic: podman defaults to the OCI
@@ -744,6 +774,91 @@ deploy_open_notebook() {
     wait_for_health open-notebook http://127.0.0.1:5056/health 180
 }
 
+# frank-tts-engine is the arm A TTS engine behind frank-tts: one Quadlet unit
+# plus the private bridge its unit defines (install_quadlet copies the sibling
+# frank-tts-engine.network — without that file the v1 generator refuses to
+# produce the container unit at all, the same trap documented above). The
+# façade that consumes it is a separate service on a separate port and a
+# separate handler.
+deploy_frank_tts_engine() {
+    # Weights BEFORE the build, and refuse rather than fetch. The payload is
+    # 1.4 GiB of GGUF with byte and sha256 checks; silently pulling it inside a
+    # deploy would turn a stalled network into a deploy that looks hung, and
+    # would hide which of the two failure modes the operator is in. The fetcher
+    # is idempotent, so re-running this handler after the fetch is cheap.
+    if ! scripts/download-frank-tts-engine-qwentts.sh --verify-only >/dev/null; then
+        echo "frank-tts-engine: the talker/tokenizer GGUFs are missing or wrong-sized under /home/dank/models/Qwen3-TTS-GGUF; run scripts/download-frank-tts-engine-qwentts.sh and re-deploy" >&2
+        return 1
+    fi
+
+    # Build first: Image= is a locally built tag with Pull=never, so the
+    # generator cannot start a container from it before it exists.
+    build_compose_image frank-tts-engine
+
+    install_quadlet frank-tts-engine dankclaw/voiceservice/quadlet frank-tts-engine
+    systemctl --user start frank-tts-engine-network.service
+    # No `systemctl --user enable` (generated Quadlet units cannot be enabled
+    # on this host); boot persistence is the [Install] section in the unit.
+    #
+    # `restart` blocks until the unit reaches started, which includes the
+    # ExecStartPost warm pass — a boot of this service is therefore already
+    # warm by the time the next line runs.
+    systemctl --user restart frank-tts-engine.service
+    # NOT wait_for_health: this container publishes nothing, so there is no URL
+    # the deployer can dial from the host. The unit's HealthCmd runs inside the
+    # container's own namespace, and podman's recorded health status is what the
+    # host can actually observe.
+    wait_container_healthy frank-tts-engine 150 || return 1
+
+    # The warmer runs a second time here on purpose. ExecStartPost carries a
+    # `-` prefix so a failed warm can never crash-loop the endpoint, which also
+    # means the unit cannot fail the deploy on it. This call is where a voice
+    # that did not warm becomes a deploy result, and where the per-voice
+    # cold=/warm= numbers land on the operator's console instead of only in the
+    # journal. The pass itself is idempotent and the second cold cost is gone:
+    # the voices are already warm, so this costs about a second per voice. It is
+    # exec-ed into the container for the same reason the health gate is: no host
+    # address exists.
+    podman exec frank-tts-engine /app/warm-voices.sh
+}
+
+deploy_frank_tts() {
+    # The 7772 façade in front of frank-tts-engine. Weights and the engine build
+    # are not this handler's business, but the BRIDGE FILE is: this unit
+    # references frank-tts-engine.network, and with a referenced Network= file
+    # absent the v1 generator refuses to produce the container unit at all. So
+    # `--only frank-tts` installs the engine's quadlet pair too — idempotent, and
+    # it is what makes the façade deployable on a host where the engine was
+    # planned separately or not at all.
+    #
+    # The voice packs are host state (the pack builder writes them), but the
+    # directory is created here as the deploy user on purpose: rootless podman
+    # would otherwise auto-create a missing bind source as root-owned, and the
+    # container runs as uid 10000.
+    mkdir -p /home/dank/voices
+
+    build_compose_image frank-tts
+    install_quadlet frank-tts-engine dankclaw/voiceservice/quadlet frank-tts-engine
+    install_quadlet frank-tts dankclaw/voiceservice/quadlet frank-tts
+    systemctl --user start frank-tts-engine-network.service
+
+    # No `systemctl --user enable` (generated Quadlet units cannot be enabled on
+    # this host); boot persistence is the [Install] section in each unit. The
+    # façade unit carries Wants=/After= on frank-tts-engine.service, so this
+    # restart pulls the engine — and its ExecStartPost warm pass — ahead of it:
+    # an engine that will not start delays this gate instead of taking the
+    # endpoint down with it.
+    systemctl --user restart frank-tts.service
+    # The gate is podman's recorded health, driven by the unit's own HealthCmd
+    # (`wget --spider -q http://127.0.0.1:7772/health`, inside the container's
+    # namespace). /health answers 200 with the backend name and the resolved
+    # voice list, so an empty /voices still reads healthy while a dead app does
+    # not — and note what this gate cannot see: the engine publishes no port on
+    # purpose, so an engine that is down shows up in the /health payload and in
+    # the first synthesis, never here.
+    wait_container_healthy frank-tts 120
+}
+
 deploy_comfyui() {
     # Build first: the unit's Image= resolves against local storage, so the
     # image has to exist before the generator starts a container from it.
@@ -1344,7 +1459,7 @@ LLM_ZEALOT_RUNTIME="${LLM_ZEALOT_RUNTIME:-/home/dank/GitPackages/llama-prism-b10
 # image path — a deploy that starts without it silently ships a text-only
 # endpoint. Checked unconditionally, like frank-dragoon's. Q8_0 is MANDATORY,
 # not a preference: the card says the BF16 tower can crash llama-server when
-# several image requests run at once, and this endpoint runs --parallel 3. Its
+# several image requests run at once, and this endpoint runs --parallel 2. Its
 # 868.32 MiB worst-case VRAM (595.29 model + 248.10 compute in the boot ledger)
 # lands AFTER the engine's fit check, so it is not inside the q8_0 budget.
 LLM_ZEALOT_MMPROJ="${LLM_ZEALOT_MMPROJ:-/home/dank/models/Bonsai2-9B-MTP/Ternary-Bonsai-2-9B-mmproj-Q8_0.gguf}"
@@ -1690,6 +1805,8 @@ deploy_service() {
         frank-dragoon) deploy_llm_dragoon ;;
         frank-zealot) deploy_llm_zealot ;;
         frank-archon) deploy_llm_archon ;;
+        frank-tts-engine) deploy_frank_tts_engine ;;
+        frank-tts) deploy_frank_tts ;;
         hermes|hermes-dashboard|hermes-webui) deploy_hermes ;;
         romm|romm-mariadb|romm-redis|mariadb|redis) deploy_romm_stack "$service" ;;
         jellyfin) deploy_jellyfin ;;

scripts/deploy.sh

@@ -142,6 +142,7 @@ valid_service() {
         dankclaw:node-exporter|dankclaw:authentik-postgres|dankclaw:authentik-server|\
         dankclaw:authentik-worker|dankclaw:authentik-outpost|dankclaw:authentik-outpost-ldap|dankclaw:anubis|dankclaw:seerr|\
         dankclaw:open-notebook|\
+        dankclaw:frank-tts-engine|dankclaw:frank-tts|\
         dankclaw:frank-dragoon|dankclaw:frank-zealot|\
         dankserver:romm-mariadb|dankserver:romm-redis|dankserver:romm|\
         dankserver:copyparty|dankserver:jellyfin|dankserver:calibre-web|dankserver:calibre-server|dankserver:plex|dankserver:tautulli|\

scripts/download-frank-tts-engine-qwentts.sh

@@ -0,0 +1,93 @@
+#!/usr/bin/env bash
+# Download the frank-tts-engine payload: the two GGUF files the arm A engine
+# (qwentts.cpp `tts-server`, dankclaw/voiceservice/Containerfile.engine) loads
+# once at startup — Serveurperso/Qwen3-TTS-GGUF's **1.7 B base talker at
+# Q4_K_M** and the **12 Hz tokenizer at Q8_0**. Public repo — no auth header,
+# and never a token on the command line (world-readable in /proc/<pid>/cmdline).
+#
+# THE BASE VARIANT IS MANDATORY, NOT A PREFERENCE. The engine refuses every
+# voice registration unless the loaded model reports type "base"
+# (tools/tts-server.cpp, register_voice): on a customvoice or voicedesign talker
+# the cloned-voice product does not exist. The 0.6 B talker (628,905,056 B for
+# its Q4_K_M) also exists and is NOT the decided artifact — 1.7 B is what live
+# output was measured with on 2026-10-18.
+#
+# Fresh downloads, no resume (the same rule the frank-zealot fetcher learned the
+# hard way: `curl -C -` once produced an oversized file on a multi-GB payload);
+# -f/--fail-with-body so an HTTP error is never a success; then exact byte count
+# and sha256 against the Hub's own LFS oid. This repo IS LFS, so the sha values
+# below are the pointer oids the Hub publishes — verified at fetch, not
+# computed locally. Idempotent: a complete, correctly-hashed file is skipped,
+# and `--verify-only` reports without downloading (that is the mode the deployer
+# and the runbook use to answer "are the weights there?").
+#
+# Both files together are 1.4 GiB and the engine mmaps them: peak RSS measured
+# 5.7 GiB with both resident. Nothing here is deleted on a swap — the previous
+# talker stays on disk, because the rollback for a bad engine build is to point
+# QWENTTS_MODEL at a different file, not to re-download 1.4 GiB under pressure.
+#
+# Usage:
+#   scripts/download-frank-tts-engine-qwentts.sh [DEST_DIR] [--verify-only]
+# Default DEST_DIR is the host directory the frank-tts-engine unit mounts
+# read-only at /models.
+set -euo pipefail
+
+DEST=""
+VERIFY_ONLY=0
+for arg in "$@"; do
+    case "$arg" in
+        --verify-only) VERIFY_ONLY=1 ;;
+        *) DEST="$arg" ;;
+    esac
+done
+DEST="${DEST:-/home/dank/models/Qwen3-TTS-GGUF}"
+
+# repo | hub-name | dest-name | bytes | sha256 (Hub LFS oid, resolved 2026-10-18)
+FILES=(
+  "Serveurperso/Qwen3-TTS-GGUF|qwen-talker-1.7b-base-Q4_K_M.gguf|qwen-talker-1.7b-base-Q4_K_M.gguf|1219245248|ea393ebaf2167ea23ce9fc18b093822851358a950d7075cd47ab4f6ce23e887d"
+  "Serveurperso/Qwen3-TTS-GGUF|qwen-tokenizer-12hz-Q8_0.gguf|qwen-tokenizer-12hz-Q8_0.gguf|291150624|1883beeed99348fc35e23dd225e9082f93f6f8c109330a33d935baa8acdbfd94"
+)
+
+mkdir -p "$DEST"
+status=0
+for entry in "${FILES[@]}"; do
+  IFS='|' read -r repo hubname destname size sha <<<"$entry"
+  url="https://huggingface.co/${repo}/resolve/main/${hubname}"
+  f="$DEST/$destname"
+  have=0
+  if [[ -f "$f" ]] && [[ "$(stat -c%s "$f")" == "$size" ]]; then
+    if sha256sum -c --quiet <(printf '%s  %s\n' "$sha" "$f"); then
+      have=1
+    fi
+  fi
+  if (( have )); then
+    echo "OK        $destname"
+    continue
+  fi
+  if (( VERIFY_ONLY )); then
+    echo "MISSING   $destname"
+    status=1
+    continue
+  fi
+  echo "FETCHING  $destname (from $repo)"
+  tmp="$f.part"
+  curl -fsSL --fail-with-body -o "$tmp" "$url"
+  mv "$tmp" "$f"
+  if [[ "$(stat -c%s "$f")" != "$size" ]]; then
+    echo "SIZE FAIL $destname ($(stat -c%s "$f") != $size)"
+    status=1
+    continue
+  fi
+  if ! sha256sum -c --quiet <(printf '%s  %s\n' "$sha" "$f"); then
+    echo "SHA FAIL  $destname"
+    status=1
+    continue
+  fi
+  echo "VERIFIED  $destname"
+done
+if (( status == 0 )); then
+  echo "DOWNLOAD_DONE $DEST"
+else
+  echo "DOWNLOAD_FAILED $DEST" >&2
+fi
+exit "$status"

scripts/frank-tts-engine.env

@@ -0,0 +1,147 @@
+# frank-tts-engine.env — tunables for **frank-tts-engine**, the arm A TTS
+# engine on Dankclaw (qwentts.cpp `tts-server`, container port **8880**, never a
+# fleet endpoint). Read by the Quadlet unit
+# (dankclaw/voiceservice/quadlet/frank-tts-engine.container) as its only
+# EnvironmentFile=, which is why every path below is the value the CONTAINER
+# sees. The host directories those mounts come from are named in
+# dankclaw/voiceservice/quadlet/frank-tts-engine.container and
+# scripts/download-frank-tts-engine-qwentts.sh.
+#
+# WHAT SITS HERE AND WHAT DOES NOT. `tts-server` reads its configuration from
+# command-line flags only — it looks at no environment variable — so this file
+# is consumed by the image's entrypoint
+# (dankclaw/voiceservice/tts-engine-start.sh), which turns each key below into
+# the matching flag. Every value has a default baked into that script, and the
+# default equals the value below: this file exists so the decided shape is
+# written down in the repo and one line can be changed without a rebuild, not
+# because the engine would otherwise fail to boot.
+#
+# THE THREAD LAW (read this before reaching for CPUQuota=, CPUAffinity=,
+# taskset or a systemd slice). There is **no `-t`/`--threads` flag** in this
+# build: src/backend.h computes the CPU thread count as
+# `std::thread::hardware_concurrency() / 2` (its own comment: GEMM shares SIMD
+# units across hyperthreads). The engine therefore sizes its pools from what the
+# kernel *reports*, not from what it is allowed to use. Pin the container to a
+# cpuset and the thread count silently changes with it — different GEMM
+# tiling, different timings, no log line saying so, and the measured numbers
+# below stop describing the process you are running. Nothing in this fleet
+# pins this container; that is a decision, not an oversight.
+#
+# THE REGISTRY LAW (why the unit has an ExecStartPost at all). Registrations live
+# in memory only, so a restart loses them, and re-registration alone does NOT warm
+# a voice — the warm pass has to synthesize something. Without it the façade
+# answers 400 for every name until somebody asks for audio. So
+# dankclaw/voiceservice/tts-engine-warm.sh (in the image at /app/warm-voices.sh)
+# runs on every start and speaks a short sentence twice per voice. The penalty it
+# removes is about 0.6 s, NOT the trial's 6.2-8.0 s: measured on the built
+# container 2026-10-18 against an empty registry, the first synthesis cost
+# 1,883 ms and the requests after it 1,226-1,283 ms. The hook runs INSIDE this
+# container — `podman exec`, from the unit's ExecStartPost — so it reads /voices
+# here and the keys at the bottom of this file are its knobs too.
+#
+# STREAMING IS NOT BUFFERED. The same seed gives audio that differs in 92.2 %
+# of samples (-41.6 dB RMS) between `response_format=pcm` (the streaming path,
+# codec chunks pushed as they decode) and `response_format=wav` (the buffered
+# path). Nothing in this stack may compare the two, cache one against the
+# other, or assume a seed pins output across `response_format`. frank-tts always
+# asks for `wav` and re-encodes to mp3 itself; the warmer below also asks for
+# `wav`, for that reason and because the streamed path would need a reader.
+#
+# THE ROUTE LIST, verbatim from tts-server at the pinned commit, so nobody
+# debugs against a route that does not exist: GET /health, GET /v1/models,
+# GET|POST /v1/audio/voices, DELETE /v1/audio/voices/{name},
+# POST /v1/audio/speech (response_format wav or pcm). Everything else is a bare
+# 404. Note two traps in that surface: `GET /v1/audio/voices` returns an empty
+# JSON object rather than the voice list at this commit (the handler builds the
+# array and never attaches it to the document), and a `POST /v1/audio/voices`
+# carrying `spk_b64` without `rvq_b64` is rejected outright — it is `wav_b64` or
+# BOTH of the pair.
+
+# --- the two weights (see scripts/download-frank-tts-engine-qwentts.sh) -------
+# Container paths; the host directory /home/dank/models/Qwen3-TTS-GGUF is
+# mounted read-only at /models. 1,219,245,248 B + 291,150,624 B, fetched from
+# https://huggingface.co/Serveurperso/Qwen3-TTS-GGUF and byte-checked at fetch.
+#
+# The 1.7 B talker is the decided artifact (Frank, 2026-10-18). A 0.6 B talker
+# exists at 628,905,056 B and is NOT what live output was measured with; the
+# Q4_K_M quantization is the size that leaves the measured RTF margin intact on
+# this box, and the tokenizer rides at Q8_0 because the codec is where clone
+# fidelity is lost first.
+#
+# It has to be the **base** variant, not customvoice/voicedesign: the engine
+# refuses any voice registration unless qt_model_type() reports "base"
+# (tools/tts-server.cpp, the register_voice lambda). Cloned voices — the whole
+# product — are impossible on the other two variants.
+QWENTTS_MODEL=/models/qwen-talker-1.7b-base-Q4_K_M.gguf
+QWENTTS_CODEC=/models/qwen-tokenizer-12hz-Q8_0.gguf
+
+# What GET /v1/models reports, and what scripts/frank-tts.env's
+# TTS_UPSTREAM_MODEL names. A model id, never a file name.
+QWENTTS_ALIAS=frank-tts-engine
+
+# 0.0.0.0 is required and is not an exposure decision: tts-server binds
+# 127.0.0.1 by default, and inside its own netns that address is reachable by no
+# one, not even the façade on the same bridge — which is why a host-loopback
+# publish would not have helped either (netavark DNATs published ports only, and
+# the unit publishes nothing at all). Binding 0.0.0.0 exposes the server to the
+# one network it is attached to: the private voice bridge
+# (systemd-frank-tts-engine, 10.89.5.0/24), whose only other member is frank-tts.
+QWENTTS_HOST=0.0.0.0
+QWENTTS_PORT=8880
+
+# Language label applied when a request omits one. `auto` is upstream's default
+# and what the trial ran; naming a language is a per-request field on
+# /v1/audio/speech, so this is only the fallback.
+QWENTTS_LANG=auto
+
+# Serialised FIFO: one synthesis at a time, everyone else queued. Warm RTF on
+# this box is 0.55-0.67 against real time 1.0, which is the entire margin a live
+# stream has; two concurrent syntheses split the same cores and the margin is
+# gone, with the added effect that the second caller's time-to-first-audio now
+# includes the first one's whole utterance. The façade's own budget
+# (SHIM_TIMEOUT=600, and open-notebook's ESPERANTO_TTS_TIMEOUT=660 sitting one
+# round-trip outside it) is what absorbs the queue.
+QWENTTS_MAX_BATCH=1
+
+# --- the boot warmer (dankclaw/voiceservice/tts-engine-warm.sh) --------------
+# These three are read by the warm hook, not by tts-server. They live here
+# because the hook is exec-ed into this container and therefore inherits this
+# same EnvironmentFile — one file, one restart, no second source of truth.
+
+# Container path of the voice packs; the host directory is /home/dank/voices,
+# mounted read-only by the unit and mounted (read-only, same source) by
+# frank-tts as well. A directory counts as a voice exactly when it contains
+# reference.wav, which is the same rule frank-tts applies.
+VOICES_DIR=/voices
+
+# How long the hook waits for /health before giving up. Model load dominates
+# this: both GGUFs are read and the context is built before the HTTP thread
+# binds, and a boot competes with every other unit on the box. 300 s is generous
+# against a cold cache; the unit's TimeoutStartSec (900 s) is what bounds the
+# whole pass, warming included.
+HEALTH_WAIT=300
+
+# The sentence each voice speaks to snapshot its codec state, and the text the
+# second (warm-timing) pass repeats. Fixed on purpose: the cold=/warm= numbers in
+# the journal are comparable across boots only if the input is the same. Kept
+# short because warming a library is serial — two syntheses per voice, ~5 s each,
+# inside the unit's start deadline.
+# QUOTED, and the quoting means two different things to the two readers of this
+# file, which is the trap here:
+#   * bash (`set -a; source`, how the repo's seams and any human read it) needs
+#     the quotes — an unquoted value with spaces is word-split and the second
+#     word is executed as a command.
+#   * podman's `--env-file` (how the unit actually reads it) does NOT strip
+#     quotes: measured 2026-10-18 against the image's pinned base, the value
+#     arrives as `"Warm up, one two three."` WITH them. Interpolated into the
+#     hook's JSON body that is `""Warm up…""`, the engine's parser rejects it,
+#     every voice stays cold and the boot still looks healthy.
+# So the value stays quoted for bash and the hook strips one matched pair before
+# it builds the request, then escapes what is left. Both readers now agree, and a
+# sentence containing a quote or a backslash still arrives verbatim.
+WARM_TEXT="Warm up, one two three."
+
+# Per-request ceiling for the hook. A cold voice measures 6-8 s, so 120 s is
+# ~15x margin: reaching it means the engine is wedged, and systemd is still
+# waiting on this pass before it calls the unit started.
+REQUEST_TIMEOUT=120

scripts/frank-tts.env

@@ -30,23 +30,43 @@
 #
 # BACKEND SWITCH. TTS_BACKEND picks the shape and nothing else changes for the
 # consumer:
-#   omni-http      forward to an OpenAI-shaped upstream on the host (:8880),
-#                  carrying the voice along as base64 reference_audio. The
-#                  engine does the inference; the shim resolves the voice and
-#                  re-encodes to mp3 when asked.
+#   omni-http      forward to an OpenAI-shaped upstream, carrying the voice along
+#                  as base64 reference_audio. The engine does the inference; the
+#                  shim resolves the voice and re-encodes to mp3 when asked. The
+#                  shipped engine (frank-tts-engine) speaks a voice it has
+#                  REGISTERED on itself, from the same /home/dank/voices packs,
+#                  and warms them at boot — see [[Frank TTS Engine]] for what that
+#                  boot warm is for (a memory-only registry: without it every name
+#                  is a 400) and what it saves (~0.6 s).
 #   llama-tts-cli  run LLAMA_TTS_BIN once per request with
 #                  --tts-speaker-file <reference.wav>, nice 19 so a narration
 #                  never starves the text endpoints on this box. Needs
 #                  LLAMA_TTS_BIN + LLAMA_TTS_MODEL filled in; LLAMA_TTS_MMPROJ
 #                  only if that binary takes a projector.
-# The upstream address is host.containers.internal — the gateway name a bridge
-# container uses for the host. It is NOT the LAN IP and it is NOT
-# 127.0.0.1: a bridge netns has neither.
+
+# THE UPSTREAM ADDRESS. The engine is a container on the private bridge this
+# unit also joins (dankclaw/voiceservice/quadlet/frank-tts-engine.network), so
+# this is its container DNS name. It used to read
+# `http://host.containers.internal:8880`, which is a shape that cannot work: a
+# bridge container reaches the host's network namespace, netavark DNATs PUBLISHED
+# ports only, and an engine on the host's loopback is published to nobody
+# ([[Container Network Namespaces]] — the trap that 502'd hermes). Inert under
+# TTS_BACKEND=llama-tts-cli, which needs no upstream at all.
 VOICES_DIR=/voices
 TTS_BACKEND=omni-http
-TTS_UPSTREAM=http://host.containers.internal:8880
+TTS_UPSTREAM=http://frank-tts-engine:8880
 TTS_UPSTREAM_MODEL=voxcpm2
 
+# THE DEFAULT VOICE — what a request that names NO voice speaks. The omp harness
+# has no setting that feeds a voice to its speech device (`voice_id` is a
+# per-call argument; `speech.voice` belongs to the TUI's Kokoro speak-aloud and
+# never reaches an HTTP request), so a harness voiceover arrives voice-less and
+# would otherwise be a 400 for every caller that does not name one. An UNKNOWN
+# name still 400s with the list that exists — this covers the absent case only —
+# and the journal marks such a line `(default)` so an unrequested voice never
+# reads as a requested one. Any pack directory in /home/dank/voices is legal.
+DEFAULT_VOICE=narrator1
+
 # CLI-backend knobs, inert while TTS_BACKEND=omni-http. Empty means "not
 # configured": the endpoint answers a 500 that says so instead of running
 # `nice env -m ...` with an empty binary name.

scripts/frank-zealot.env

@@ -2,12 +2,14 @@
 # prism-ml/Ternary-Bonsai-2-9B-gguf at PQ2_0 **with the MTP head in the file**
 # on the RTX 3090, :7771.
 #
-# 2026-10-18 (Frank): swap from the Bonsai-2-**27B** PQ2_0 to the 9B MTP export
-# at THREE 262,144-token conversations (Frank: "if you can possibly fit a third
-# context, do it"). The 9B bills HALF the KV of the 27B per token, which is what
-# funds 3 x the native window on one 24,123 MiB card. Speculative decoding ships
-# OFF — measured, not assumed; see the MTP law below, which is the whole story
-# and the reason the publisher's "depth 2 works best" line does not transfer.
+# 2026-10-18 (Frank): swap from the Bonsai-2-**27B** PQ2_0 to the 9B MTP export,
+# and the same evening the shape moved to TWO 262,144-token conversations over an
+# UNQUANTIZED (f16) KV cache — "shift frank-zealot to 2 parallels of unquantized
+# kv". Exact K and V is the retrieval-fidelity ask; the price is one concurrent
+# conversation, because f16 owns the card. Speculative decoding ships OFF —
+# measured, not assumed; see the MTP law below, which is the whole story and the
+# reason the publisher's "depth 2 works best" line does not transfer (and why
+# exact KV makes the drafter illegal outright).
 #
 # THE RUNTIME IS A LOCK, NOT A PREFERENCE. The file is general.file_type 141
 # carrying custom GGML type 142 tensors plus prism.hadamard.* metadata
@@ -27,7 +29,7 @@ MODEL_FILE=/home/dank/models/Bonsai2-9B-MTP/Ternary-Bonsai-2-9B-PQ2_0-MTP-Q8_0.g
 # 624,229,664 B, Hub LFS sha256 e0cb6f69… — Q8_0 IS MANDATORY, not a preference:
 # the publisher's card says the BF16 mmproj "can crash llama-server when several
 # image requests run at once; Q8_0 is not affected", and this endpoint runs
-# --parallel 3, i.e. exactly that shape. The projector's worst case lands AFTER
+# --parallel 2, i.e. exactly that shape. The projector's worst case lands AFTER
 # the engine's own fit check, so it is never inside a projection number.
 MMPROJ_FILE=/home/dank/models/Bonsai2-9B-MTP/Ternary-Bonsai-2-9B-mmproj-Q8_0.gguf
 # Base alignment: Bonsai-2 is the censored BASE lineage. The 27B CRACK re-export
@@ -42,16 +44,18 @@ MMPROJ_FILE=/home/dank/models/Bonsai2-9B-MTP/Ternary-Bonsai-2-9B-mmproj-Q8_0.ggu
 ALIAS=frank-zealot
 BIND_ADDR=0.0.0.0
 LISTEN_PORT=7771
-# CTX_SIZE is the POOL llama.cpp divides across slots: 786,432 / 3 = 262,144 per
-# conversation — each slot at the model's TRAINED window, which is the point of
-# the swap (the 27B era had to cut each conversation to 200,704 to fit two).
-# MUST stay divisible by PARALLEL (the seam enforces it) and the harness
-# contextWindow quotes the PER-SLOT number — a longer prompt is answered with a
-# 400, never truncated. The ceiling cannot go past 3 x 262,144: that is the
-# native wall (no YaRN in this path) and the arithmetic agrees — a 4th slot
-# would push each below the compaction contract.
-CTX_SIZE=786432
-PARALLEL=3
+# CTX_SIZE is the POOL llama.cpp divides across slots: 524,288 / 2 = 262,144 per
+# conversation — each slot STILL at the model's TRAINED window; the per-slot
+# contract did not move. MUST stay divisible by PARALLEL (the seam enforces it)
+# and the harness contextWindow quotes the PER-SLOT number — a longer prompt is
+# answered with a 400, never truncated. THE POOL CANNOT STAY AT 786,432 UNDER
+# EXACT KV: f16 bills 32,768 B/token, so that pool is 24,576 MiB — more than the
+# 24,123 MiB the driver leaves addressable, before a single weight loads.
+# Halving the POOL to 524,288 (16,384 MiB) is what funds exact KV. The window
+# cannot go past 262,144 a slot either: that is the native wall (no YaRN in this
+# path), so a 3rd slot would be a KV-dtype cut, not more context.
+CTX_SIZE=524288
+PARALLEL=2
 BATCH_SIZE=4096
 # Ubatch is a prefill knob (decode never moves) with NO interior optimum on this
 # CUDA card up to 2048 — 2048 is the measured optimum (+4.6 % prefill). It has a
@@ -60,38 +64,47 @@ BATCH_SIZE=4096
 UBATCH_SIZE=2048
 # KV law (header + boot ledger, both confirmed): qwen35 hybrid, 32 layers with
 # qwen35.full_attention_interval = 4 ⇒ 8 full-attention + 24 Gated DeltaNet;
-# 4 KV heads × 256 dim = 8,192 elements per token per cache. q8_0 bills 8,704 B
-# per cache ⇒ 17,408 B/token = 17 KiB, so the 786,432 pool is 13,056.00 MiB —
-# the ledger said exactly that. HALF the 27B's 34,816 B/token, which is the
-# whole reason three native windows fit. f16 would bill 26,112 MiB at this pool
-# (against a 24,123 MiB card) and dies at cudaMalloc; the 24 DeltaNet layers
-# bill a fixed recurrent state per SLOT instead of per token — the PRODUCTION
-# ledger prints "RS buffer size = 150.75 MiB (3 cells, 32 layers, 3 seqs)"
-# (~50 MiB a cell), while the SPEC-ARMED arms print 452.25 MiB, because MTP
-# depth 2 bills three seqs per slot (9 cells) — which is why pool arithmetic
-# alone under-prices the shape.
-CACHE_TYPE_K=q8_0
-CACHE_TYPE_V=q8_0
+# 4 KV heads × 256 dim (n_embd_k_gqa = n_embd_v_gqa = 1,024 per layer) = 8,192
+# elements per token per cache. EXACT KV: f16 = 2 B/element ⇒ 16,384 B per cache
+# ⇒ 32,768 B/token = 32 KiB, so the 524,288 pool is 16,384.00 MiB. q8_0 bills
+# 1.0625 B/element (32 codes + one 2-byte scale per 32-block) ⇒ 17,408 B/token,
+# which is the 13,056.00 MiB the 3-slot ledger printed at the 786,432 pool.
+# THE RATIO IS 1.882×, NOT 2×: the old note here said "f16 would bill 26,112
+# MiB" because it doubled the q8_0 figure with its scale overhead included;
+# exact arithmetic says 24,576 MiB at that pool. The wall stands, only its
+# height moves. The 24 DeltaNet layers bill a fixed recurrent state per SLOT
+# instead of per token — the 3-slot ledger printed "RS buffer size = 150.75 MiB
+# (3 cells, 32 layers, 3 seqs)", ~50.25 MiB a cell so two slots bill 100.50 —
+# while the SPEC-ARMED arms print 452.25 MiB, because MTP depth 2 bills three
+# seqs per slot (9 cells). Pool arithmetic alone under-prices the shape.
+CACHE_TYPE_K=f16
+CACHE_TYPE_V=f16
 # SPECULATIVE DECODING: OFF, MEASURED. The head is in the file and the drafter
 # is GOOD (acceptance 0.798/0.617 per position, mean accepted length 2.41) — it
 # still loses, because the draft context bills its OWN f16 KV over the WHOLE
-# pool: 4,096 B/position × 786,432 = 3,072.00 MiB, plus its compute buffers,
-# 4,830 MiB all told. Booted arms, same card, same traffic (2026-10-18):
+# pool at its default dtype. That dtype IS a knob (--spec-draft-type-k /
+# --spec-draft-type-v, both default f16 — verified against this build's --help),
+# but SPEC_TYPE=none never sends them. Under the
+# 3-slot q8_0 shape that bill was 4,096 B/position × 786,432 = 3,072.00 MiB plus
+# ~1,758 MiB of buffers. Booted arms, same card, same traffic (2026-10-18, the
+# WHOLE table is q8_0 K + q8_0 V — it predates exact KV):
 #   3 × 262,144  spec OFF  ub 2048 → 17,876 used / 6,249 free, decode 167.2 t/s
 #   3 × 262,144  spec ON   ub 2048 → 22,706 used / 1,419 free, decode 109.2 t/s
 #   3 × 262,144  spec ON   ub 1024 → 21,400 used / 2,725 free, decode 213.5 t/s
 #   2 × 262,144  spec ON   ub 2048 → 17,178 used / 6,947 free, decode 213.2 t/s
 #   1 × 262,144  spec ON   ub 2048 → 11,652 used / 12,473 free, decode 214.2 t/s
-# i.e. MTP is worth +28 % decode whenever the card has room, and at the 3-slot
-# pool it costs 1.3 GiB of compute buffers that ubatch 2048 refuses to give up —
-# the squeeze, not the drafter, is what halves decode. The arm that WOULD run
-# MTP at three windows is SPEC_TYPE=draft-mtp + UBATCH_SIZE=1024 (decode 213.5,
-# 3-stream 250.8 aggregate) and pays prefill −17 % and 2.7 GiB of headroom on a
-# card whose projector worst-case lands after the fit check. This endpoint's
-# load is the fleet's COMPACTION HUB (prefill-bound, ~170k in) plus 2-3
-# concurrent subagents, so the deployed arm takes the +17 % prefill
-# (2,877 vs 2,395 t/s at 106,418 tokens) and the +12 % three-stream aggregate
-# (280.2 vs 250.8) over single-stream speed, and keeps 6.2 GiB free.
+# MTP is worth +28 % decode whenever the card has room. At the SHIPPED exact-KV
+# shape an f16-draft arm has none: the draft KV alone is 4,096 × 524,288 =
+# 2,048.00 MiB plus its buffers, on a trunk that already projects ~21,200 MiB of
+# the 24,123 the driver leaves addressable. DOORS BACK TO THE DRAFTER: one
+# window per conversation; KV back to q8_0 with UBATCH_SIZE=1024 (213.5 t/s);
+# or the UNMEASURED arm --spec-draft-type-k q8_0 --spec-draft-type-v q8_0, which
+# halves the draft bill to 1,088 MiB and is legal on this build (>= b10776).
+# Nobody has booted that beside exact KV — measure before promising it.
+# This endpoint's load is still the fleet's COMPACTION HUB (prefill-bound,
+# ~170k in): prefill is weight-bandwidth bound and does not read the KV cache
+# per generated token, which is why exact KV is affordable here at all; what it
+# buys back is concurrency — TWO conversations, not three.
 # SPEC_TYPE=none strips the WHOLE spec set (--spec-type, every --spec-draft-*):
 # flags move as a set or the arm measures a crash instead of an absence.
 SPEC_TYPE=none
@@ -105,27 +118,33 @@ SPEC_DRAFT_P_MIN=0
 # PRESENCE_PENALTY="" is the documented opt-out.
 PRESENCE_PENALTY=1.0
 NGL=99
-# Boot ledger (2026-10-18 PRODUCTION boot under the unit, verbosity 4):
-#   17,922 MiB used / 6,203 MiB free of 24,123 (nvidia-smi settled)
+# Boot ledger REFERENCE — the previous production boot (2026-10-18 13:19,
+# 3 × 262,144, q8_0 K + q8_0 V, verbosity 4), i.e. the shape this file replaced:
+#   17,956 MiB used / 6,169 MiB free of 24,123 addressable (nvidia-smi settled;
+#   its total column reads 24,576 — the driver reserves the difference, and
+#   older notes quoting "a 24,123 MiB card" mean this addressable figure)
 #   CUDA0 model 2,036.71 MiB + CPU_Mapped 257.66 MiB
 #   CUDA0 KV 13,056.00 MiB (q8_0 K + q8_0 V, 786,432 positions)
 #   CUDA0 RS 150.75 MiB (3 cells, 32 layers, 3 seqs)
 #   compute 1,409.02 MiB CUDA + 1,088.87 MiB CUDA_Host (+2.84 MiB output buf)
-#   mmproj worst-case estimate 868.32 MiB (248.10 CUDA + 24.93 CPU compute
-#   meta) — charged AFTER the engine's own fit check, as always
+#   mmproj 595 MiB weights + 248.10 MiB CUDA compute meta; estimated worst case
+#   868.32 MiB — charged AFTER the engine's own fit check, as always
 #   no clamp line, no cudaMalloc error
-# Measured on this boot (/completion timings, greedy, ignore_eos, 512 tokens):
-# 168.7 t/s decode (three runs 168.4-168.7) and ~300 t/s aggregate across
-# THREE concurrent streams (102.8 each). The trial arm's record (167.2 decode,
-# 280.2 aggregate, 2,877 t/s prefill at 106,418) stands; the 27B it replaces
-# gave 76.6 / 109.4 / 691.7 at 166k. The FIRST request after a boot is a
-# warmup artifact (37.7 t/s class) and a natural generation that stops early
-# makes a wall-clock aggregate read 4x low - measure with ignore_eos and read
-# the engine's own timings.
-# Fallback rung if the margin is ever eaten (desktop, co-tenant): q4_0 KV on the
-# 27B era measured 16,392 used / 7,733 free at 2 × 200,704; the same drop here
-# frees ~6.5 GiB at three windows. UBATCH_SIZE=1024 is the cheaper lever
-# (−1,306 MiB measured on this shape).
+# Measured on THAT boot (/completion timings, greedy, ignore_eos, 512 tokens):
+# 168.7 t/s decode (three runs 168.4-168.7), ~300 t/s aggregate across THREE
+# concurrent streams (102.8 each), 2,877 t/s prefill at 106,418. The 27B it
+# replaced gave 76.6 / 109.4 / 691.7 at 166k. These are the numbers the exact-KV
+# arm is judged against: decode reads 1.882× the KV bytes per token, so a decode
+# drop is EXPECTED and must be measured, not assumed, while prefill should hold.
+# Every non-KV term of that ledger survives this reslice except RS (−50.25 MiB,
+# one fewer cell) and one slot's worth of scheduler state, so the f16 arm
+# PROJECTS 17,956 − 13,056 + 16,384 − 50 = 21,234 MiB used / 2,889 free, and
+# ~2.0 GiB free through the projector's worst case. REPLACE THIS PROJECTION WITH
+# THE MEASURED PAIR after the boot: read the new ledger AND settled nvidia-smi.
+# Fallback rungs if that margin gets eaten (desktop, co-tenant), cheapest first:
+# CACHE_TYPE_V=q8_0 (exact K, quantized V) frees 8,192 MiB at this pool;
+# CTX_SIZE=401408 (two 200,704 conversations) puts exact KV at 12,544.00 MiB and
+# buys ~6.7 GiB back; UBATCH_SIZE=1024 hands 1,306 MiB of compute buffers back.
 # Log verbosity threshold (llama.cpp -lv). 4 = debug: KV layout, buffer sizes
 # and graph capture land in the journal, which is what the VRAM-fit forensics
 # read. Levels above 4 flood the journal.

scripts/frank-zealot.service

@@ -1,5 +1,5 @@
 [Unit]
-Description=llama.cpp (PrismML build 10777) Ternary-Bonsai-2-9B PQ2_0-MTP GGUF (qwen35 hybrid, 3x262144 slots over one 786432 pool, q8_0 K+V, MTP off, mmproj Q8_0 vision) on the RTX 3090 (dankclaw, frank-zealot)
+Description=llama.cpp (PrismML build 10777) Ternary-Bonsai-2-9B PQ2_0-MTP GGUF (qwen35 hybrid, 2x262144 slots over one 524288 pool, unquantized f16 K+V, MTP off, mmproj Q8_0 vision) on the RTX 3090 (dankclaw, frank-zealot)
 After=network-online.target
 Wants=network-online.target
 

scripts/serve-frank-zealot.sh

@@ -3,33 +3,35 @@
 # in the file) as frank-zealot on Dankclaw's RTX 3090 via llama.cpp (PrismML
 # vendor build 10777, CUDA sm_86).
 #
-# 2026-10-18 (Frank): Bonsai-2 27B PQ2_0 → the 9B MTP export at THREE
-# 262,144-token conversations (--ctx-size 786432 --parallel 3), q8_0 K + q8_0 V.
-# The 9B bills 17,408 B/token against the 27B's 34,816 (8 full-attention layers
-# instead of 16), and that halved rate is what funds three NATIVE windows where
-# the 27B could only afford two cut to 200,704. Verbosity 4 ships so the
-# VRAM-fit forensics (KV layout, buffer sizes, graph capture) land in the
-# journal.
+# 2026-10-18 (Frank): Bonsai-2 27B PQ2_0 → the 9B MTP export, then the same
+# evening TWO 262,144-token conversations (--ctx-size 524288 --parallel 2) over
+# an UNQUANTIZED f16 KV cache. The 9B bills 8,192 elements per token per cache
+# (8 full-attention layers instead of the 27B's 16), so exact K and V costs
+# 32,768 B/token — 16,384.00 MiB at the 524,288 pool, which is what a 24,123 MiB
+# addressable card can carry beside the trunk. Verbosity 4 ships so the VRAM-fit
+# forensics (KV layout, buffer sizes, graph capture) land in the journal.
 #
 # Architecture (engine ledger, not the marketing page): qwen35 hybrid, 32
 # layers with qwen35.full_attention_interval = 4 ⇒ 8 full-attention + 24 Gated
 # DeltaNet, 4 KV heads × 256 dim, native 262,144. The KV pool scales with the 8
-# full layers (13,056.00 MiB at the 786,432 pool, ledger-exact); the DeltaNet
-# layers cost a fixed recurrent state per SLOT — 452.25 MiB for 3 cells, ~151
-# MiB each. The runtime is a hard lock, not a preference: custom GGML type 142
-# plus prism.hadamard.* metadata, which only the vendor build registers, and
-# MTP beside quantized V needs build ≥ b10776 — so the prebuilt moved 10754 →
-# 10777 with the payload. Vision comes from the publisher's Q8_0 projector (the
-# BF16 one can crash the server on concurrent images, and this endpoint runs
-# three slots), so --mmproj is what gives this endpoint eyes; MMPROJ_FILE="" is
-# the documented text-only opt-out.
+# full layers (16,384.00 MiB of f16 at the 524,288 pool); the DeltaNet layers
+# cost a fixed recurrent state per SLOT — ~50.25 MiB a cell, so 100.50 MiB for
+# two. The runtime is a hard lock, not a preference: custom GGML type 142 plus
+# prism.hadamard.* metadata, which only the vendor build registers (the b10776
+# gate that moved the prebuilt 10754 → 10777 was MTP beside quantized V, which
+# exact KV now makes moot — the type-142 lock alone keeps the build pinned).
+# Vision comes from the publisher's Q8_0 projector (the BF16 one can crash the
+# server on concurrent images, and this endpoint runs two slots), so --mmproj is
+# what gives this endpoint eyes; MMPROJ_FILE="" is the documented text-only
+# opt-out.
 #
 # Speculative decoding ships OFF, measured: the head loads and accepts well
 # (0.798/0.617 per position, mean length 2.41) but the draft context bills its
-# own f16 KV over the WHOLE pool — 4,096 B/position × 786,432 = 3,072 MiB plus
-# buffers — and at ubatch 2048 that squeeze HALVES decode (167.2 → 109.2 t/s).
-# frank-zealot.env carries the six-arm table and the arm that turns it back on
-# (--ubatch-size 1024, decode 213.5 t/s) with its price.
+# own f16 KV over the WHOLE pool — 4,096 B/position × 524,288 = 2,048 MiB plus
+# buffers — and the trunk already projects 21,234 MiB with exact KV. Exact KV
+# and MTP cannot share this card; frank-zealot.env carries the q8_0-era arm table
+# and the two doors back to the drafter (one window, or KV back to q8_0 at
+# --ubatch-size 1024 for 213.5 t/s).
 #
 # Sampling: the checkpoint carries the publisher's thinking recipe as GGUF
 # metadata (general.sampling.* = temp 1.0 / top_p 0.95 / top_k 20 / min_p 0 /
@@ -56,40 +58,46 @@ fi
 : "${ALIAS:=frank-zealot}"
 : "${BIND_ADDR:=0.0.0.0}"
 : "${LISTEN_PORT:=7771}"
-# ctx-size is the POOL llama.cpp divides across slots: 786,432 / 3 = 262,144
-# per conversation — every slot at the model's trained window. The harness
+# ctx-size is the POOL llama.cpp divides across slots: 524,288 / 2 = 262,144
+# per conversation — every slot still at the model's trained window. The harness
 # contextWindow MUST quote the PER-SLOT number — a longer prompt is answered
-# with a 400, never truncated.
-: "${CTX_SIZE:=786432}"
-: "${PARALLEL:=3}"
+# with a 400, never truncated. Under exact KV the pool cannot stay at 786,432:
+# 32,768 B/token × 786,432 = 24,576 MiB, more than the card's whole addressable
+# 24,123 MiB before a single weight loads.
+: "${CTX_SIZE:=524288}"
+: "${PARALLEL:=2}"
 # Compute-buffer geometry. Ubatch is a prefill knob (decode never moves).
 # 2048 is the measured CUDA optimum (MiMo era, same arch/shape: +4.6 % prefill
 # at 8.9k depth, decode flat, 616 MiB). The logical batch is VRAM- and
 # throughput-neutral at a fixed ubatch. It ALSO sets the compute-buffer size,
-# which is the term that decides whether an MTP draft context fits beside a
-# 786,432-position pool: 1024 hands back 1,306 MiB and is the arm that runs the
-# drafter at three slots (frank-zealot.env carries the table).
+# which is the term that decides whether an MTP draft context fits beside a KV
+# pool: 1024 hands back 1,306 MiB and was the arm that ran the drafter at three
+# q8_0 windows (frank-zealot.env carries the table).
 : "${BATCH_SIZE:=4096}"
 : "${UBATCH_SIZE:=2048}"
-# Quantized KV: q8_0 K + q8_0 V — the only pair that funds 3 × 262,144 on this
-# card. 17 KiB/token at this geometry (8 full-attention layers × 4 KV heads ×
-# 256 dim); 13,056.00 MiB at the 786,432 pool, ledger-exact. f16 would bill
-# 26,112 MiB against a 24,123 MiB card and dies at cudaMalloc; q4_0 is the
-# fallback rung. Explicit either way so the contract is visible in the argv,
-# and --flash-attn stays required for quantized V (no true fp8 KV dtype exists
-# in this build).
-: "${CACHE_TYPE_K:=q8_0}"
-: "${CACHE_TYPE_V:=q8_0}"
+# Exact KV: f16 K + f16 V — no quantization error anywhere in the attention
+# state. 32 KiB/token at this geometry (8 full-attention layers × 4 KV heads ×
+# 256 dim × 2 B × 2 caches); 16,384.00 MiB at the 524,288 pool. That is the whole
+# reason the slot count is 2: the same dtype at the old 786,432 pool is 24,576
+# MiB and dies at cudaMalloc. q8_0 K + q8_0 V (17,408 B/token, 13,056.00 MiB at
+# 786,432) is the documented fallback rung and funds three windows; CACHE_TYPE_V
+# alone is the halfway door. Explicit either way so the contract is visible in
+# the argv, and --flash-attn stays pinned because quantized V — the fallback —
+# is illegal without it (no true fp8 KV dtype exists in this build).
+: "${CACHE_TYPE_K:=f16}"
+: "${CACHE_TYPE_V:=f16}"
 # Speculative decoding defaults OFF, measured on this card and shape: the head
 # IS in the checkpoint (qwen35.nextn_predict_layers = 1 — MTP is a property of
 # the FILE, so the plain PQ2_0 sibling could not run it at any flag value), it
 # loads, and it accepts well (mean accepted length 2.41) — but the draft context
-# bills its own f16 KV over the WHOLE pool (4,096 B/position, 3,072 MiB here)
-# and at ubatch 2048 that squeeze halves decode: 167.2 → 109.2 t/s. There is no
-# --spec-draft-cache-type knob in this build to make the draft cheap, and no
-# --spec-draft-model either: the draft rides the main model's weights. Card gate:
-# quantized V alongside MTP needs fork build >= prism-b10776, which is why
-# LLAMA_BIN moved to the 10777 prebuilt; on an older build the pair is illegal.
+# bills its own f16 KV over the WHOLE pool (4,096 B/position, 2,048 MiB at the
+# 524,288 pool) and at ubatch 2048 that squeeze halves decode: 167.2 → 109.2 t/s
+# on the q8_0 3-slot shape. The draft cache dtype IS a knob (--spec-draft-type-k
+# / --spec-draft-type-v, both default f16 — verified in this build's --help), so
+# an armed drafter can halve its own bill; there is no --spec-draft-model because
+# the draft rides the main model's weights. Card gate: quantized V alongside MTP
+# needs fork build >= prism-b10776, which is why LLAMA_BIN moved to the 10777
+# prebuilt; exact KV removes that gate but NOT the type-142 loader lock.
 # SPEC_TYPE=draft-mtp + UBATCH_SIZE=1024 is the documented MTP arm (213.5 t/s);
 # SPEC_TYPE=none strips the whole set (flags move together).
 : "${SPEC_TYPE:=none}"
@@ -104,7 +112,7 @@ fi
 : "${NGL:=99}"
 # Log verbosity threshold (llama.cpp -lv). 3 is the engine default (info);
 # 4 adds debug detail (KV layout, buffer sizes, graph capture) which is what
-# the VRAM-fit forensics need — the q8_0 KV contract and the draft-KV bill are
+# the VRAM-fit forensics need — the exact-KV size and the draft-KV bill are
 # only provable from this log. Levels above 4 flood the journal.
 : "${VERBOSITY:=4}"
 # /metrics needs the flag: llama.cpp returns 501 unless the server starts with
@@ -169,11 +177,11 @@ fi
 # open after boot; make sure it exists before the server needs it.
 nvidia-modprobe -u -c=0 2>/dev/null || true
 
-# Flash attention stays pinned on: it is REQUIRED for quantized V (q8_0),
-# and the build carries GGML_CUDA_FA_ALL_QUANTS=ON (since 2026-09-17), so
-# the q8_0 KV contract in frank-zealot.env is a real path — without this
-# flag or that build option the engine silently falls back and the
-# contract becomes a lie.
+# Flash attention stays pinned on. Exact f16 KV runs fine with or without it,
+# but the documented fallback rung (quantized V) is ILLEGAL without it, and the
+# build carries GGML_CUDA_FA_ALL_QUANTS=ON (since 2026-09-17) so that rung is a
+# real path — dropping the flag here would leave the retreat route silently
+# falling back to something the env file does not describe.
 ARGS=(
     --model "$MODEL_FILE"
     --alias "$ALIAS"

scripts/test-changed.sh

@@ -138,6 +138,21 @@ for path in "${CHANGED[@]}"; do
             add_test tests/docs_completeness.bats
             add_test tests/deployment_scoping.bats
             ;;
+        # The voice stack: the arm A engine unit, the private bridge it owns,
+        # its image and its entrypoint. Like the open-notebook block above,
+        # this case MUST precede the dankclaw/*.container glob — that `*`
+        # crosses `/`, so without this case
+        # dankclaw/voiceservice/quadlet/frank-tts-engine.container is routed to
+        # the open-webui/pihole/searxng seams and its own seam never runs.
+        # The façade's seam rides along: the two share a directory, a network
+        # and the request path a consumer takes.
+        dankclaw/voiceservice/*)
+            add_test tests/frank_tts_engine.bats
+            add_test tests/frank_tts_unit.bats
+            add_test tests/deployment_flow.bats
+            add_test tests/deployment_scoping.bats
+            add_test tests/docs_completeness.bats
+            ;;
         dankclaw/*.container|dankclaw/*.network)
             add_test tests/open_webui_quadlet.bats
             add_test tests/pihole.bats
@@ -197,6 +212,19 @@ for path in "${CHANGED[@]}"; do
         # as additions, with "no focused-test mapping".
         .AGENTTRASH/*|*/.AGENTTRASH/*)
             ;;
+        # The two voice env files both reach a container through a Quadlet unit
+        # (EnvironmentFile=), so they select the voice seams plus the
+        # script-syntax seam. This case has to precede the generic
+        # scripts/*.service and scripts/* fallbacks below, or a change to
+        # scripts/frank-tts-engine.env would run nothing but bash -n. The
+        # warmer is NOT here: it ships inside the engine image and is routed
+        # with the rest of dankclaw/voiceservice/* above.
+        scripts/frank-tts-engine.env|scripts/frank-tts.env)
+            add_test tests/frank_tts_engine.bats
+            add_test tests/frank_tts_unit.bats
+            add_test tests/deployment_scoping.bats
+            add_test tests/scripts_syntax.bats
+            ;;
         # frank-archon is llama.cpp (the unsloth b11030-mix prebuilt) on the
         # two R9700s as a ROOT unit — the 2026-09-26 swap that replaced the
         # Lucebox DS4.1 quadlet on :7770. Its env, unit and serve script all
@@ -229,6 +257,14 @@ for path in "${CHANGED[@]}"; do
             add_test tests/scripts_syntax.bats
             add_test tests/deployment_scoping.bats
             ;;
+        # The voice-pack builder is the only thing that enforces the 10-second
+        # source-material invariant and the artifact sizes the packs are pinned
+        # to, so it selects its own seam rather than landing on the generic
+        # scripts/* syntax fallback. This case has to precede that fallback.
+        scripts/build-voice-pack.sh|scripts/voice-packs.env)
+            add_test tests/voice_pack_unit.bats
+            add_test tests/scripts_syntax.bats
+            ;;
         scripts/*)
             add_test tests/scripts_syntax.bats
             ;;

scripts/voice-packs.env

@@ -0,0 +1,123 @@
+# voice-packs.env — tunables for the **frank-tts voice packs**: the three
+# numbers per voice (source file, crop offset, crop length) plus the pinned
+# engine facts that turn a crop into a pack. Read by
+# `scripts/build-voice-pack.sh`, which is the only thing that consumes this
+# file — the running service reads none of it, because the packs themselves are
+# the interface (see scripts/frank-tts.env for what the shim resolves).
+#
+# WHAT IS TRACKED HERE AND WHAT IS NOT. Paths and numbers, never credentials,
+# which is the same rule the other `scripts/*.env` files follow. The pack
+# DIRECTORIES are host state under $VOICE_PACK_DIR and stay out of the repo; the
+# crops that produce them are exactly the kind of decision worth a diff, so the
+# offsets live here. If a crop changes, change it here and rebuild with
+# --force — the manifest inside the pack records what was actually cut.
+#
+# THE OFFSETS ARE NOT ARBITRARY. Two rules pick them:
+#   1. The source-material invariant: seconds 0-10 of any sample file are
+#      forbidden voice material. The builder refuses a crop that starts inside
+#      that region and asserts the same thing again from the manifest it just
+#      wrote, so the values below are checked, not trusted.
+#   2. Speech density: the trial cut these from a silencedetect scan of the
+#      source (noise -35 dB, 0.6 s) and took the longest run of continuous
+#      speech at or past the scan window — a reference that starts mid-word or
+#      contains a page-turn of silence clones the artefacts, not the voice.
+#      serverAppConfigs-docs/Dankclaw/Voice Packs.md carries the recipe.
+#
+# WHY THE SHA256 LINES EXIST. A crop offset is a statement about one exact
+# file: 98.739 s into a re-encode of the same audiobook is a different sentence
+# and therefore a different voice. The builder hashes the source, compares it
+# with the pinned digest when one is set, and writes the digest into the pack's
+# manifest — so a pack can always be traced back to the bytes it was cut from.
+# The three values below are the trial's digests (2026-10-18), verified against
+# the files on disk.
+#
+# THE ENGINE BLOCK IS A PIN, NOT A DEFAULT. The speaker artifacts come from
+# `qwen-codec` in the qwentts.cpp tree at $VOICE_PACK_ENGINE_COMMIT: it takes a
+# 24 kHz WAV, writes the RVQ code stream next to it with the extension swapped,
+# and with --talker also runs that talker's speaker encoder to write the
+# x-vector .spk. The talker has to be a **Base** build — the customvoice and
+# voicedesign GGUFs carry no speaker encoder and the extractor says so. The
+# sizes the builder then verifies (8,192 B of .spk, 5,456-6,864 B of .rvq) are
+# derived from the codec config in the GGUF, so an engine bump that changes them
+# fails the build on purpose; see [[Voice Packs]] for the bump procedure.
+#
+# HOST PATHS, NOT CONTAINER PATHS. This runs on the host that holds the engine
+# build (Dankclaw), outside any container, with no GPU and no fleet endpoint.
+# The model paths below are where scripts/download-frank-tts-engine-qwentts.sh
+# puts the GGUFs; until that fetch has run, the same two files sit in the trial
+# tree at /home/dank/voice-audition/qwentts/models/ and the tool is only in its
+# build directory. The SOURCE paths are the third thing to place: the three
+# sample files live on the workstation today and have to be copied to
+# $VOICE_PACK_SOURCE_DIR on Dankclaw before a build can read them.
+
+# The packs root on the host: the directory frank-tts mounts read-only at
+# /voices, one sub-directory per voice.
+VOICE_PACK_DIR=/home/dank/voices
+
+# The pack list. `--all` walks it in order; every name has to carry the four
+# per-voice values below.
+VOICE_PACKS="narrator1 narrator2 narrator3"
+
+# Where the source recordings live on the engine host.
+VOICE_PACK_SOURCE_DIR=/home/dank/voice-sources
+
+# narrator1 — Randall Munroe "How To", read by Wil Wheaton. Longest speech run
+# at or past the scan window: 98.739-118.636 s, 19.897 s, which packs to the
+# 5,456 B floor of the .rvq window.
+VOICE_PACK_NARRATOR1_SOURCE=${VOICE_PACK_SOURCE_DIR}/audiosample.mp3
+VOICE_PACK_NARRATOR1_OFFSET=98.739
+VOICE_PACK_NARRATOR1_DURATION=19.897
+VOICE_PACK_NARRATOR1_SHA256=2299510467eb9143455d8c1e6a21601c3b451dd59c1dc99b99d4aacb54d1d850
+
+# narrator2 — "Abyssal Archive" (Lokey). 25 s is the ceiling of the reference
+# window and packs to exactly 6,864 B of .rvq.
+VOICE_PACK_NARRATOR2_SOURCE=${VOICE_PACK_SOURCE_DIR}/audiosample2.m4b
+VOICE_PACK_NARRATOR2_OFFSET=191.13
+VOICE_PACK_NARRATOR2_DURATION=25
+VOICE_PACK_NARRATOR2_SHA256=8e1e33317baf67b2cca67e4ce1b095ae477a18285c7373ec18ad013f2cc320e0
+
+# narrator3 — "Children of Time" (Adrian Tchaikovsky, author-read).
+VOICE_PACK_NARRATOR3_SOURCE=${VOICE_PACK_SOURCE_DIR}/audiosample3.m4b
+VOICE_PACK_NARRATOR3_OFFSET=489.232
+VOICE_PACK_NARRATOR3_DURATION=25
+VOICE_PACK_NARRATOR3_SHA256=6875d2c1db421ab96ccbb68855fa9efd4e054297e94dd1b4345eb6a9869da945
+
+# The pinned extractor and the two GGUFs it needs. $VOICE_PACK_TOOL is a build
+# output, not a download: rebuild it at $VOICE_PACK_ENGINE_COMMIT after a bump
+# rather than pointing this line at a newer tree.
+VOICE_PACK_TOOL=/home/dank/voice-audition/qwentts/qwentts.cpp/build/qwen-codec
+VOICE_PACK_CODEC_MODEL=/home/dank/models/Qwen3-TTS-GGUF/qwen-tokenizer-12hz-Q8_0.gguf
+VOICE_PACK_TALKER_MODEL=/home/dank/models/Qwen3-TTS-GGUF/qwen-talker-1.7b-base-Q4_K_M.gguf
+VOICE_PACK_ENGINE_REPO=https://github.com/ServeurpersoCom/qwentts.cpp
+VOICE_PACK_ENGINE_COMMIT=5916bf7c79dbb4e66fc059cdc507a79a23a28bb4
+
+# CPU only, and never in the way of the text endpoints on this box: ggml thread
+# count and `nice -n`. The extractor picks the best backend it is given, so the
+# device is stated rather than guessed.
+VOICE_PACK_DEVICE=CPU
+VOICE_PACK_THREADS=8
+VOICE_PACK_NICE=19
+
+# The reference window and the shape the packs are cut to. 24 kHz mono PCM is
+# the codec's own input rate, so no resampling happens inside the engine.
+VOICE_PACK_SAMPLE_RATE=24000
+VOICE_PACK_MIN_SECONDS=18
+VOICE_PACK_MAX_SECONDS=25
+
+# Artifact arithmetic, all four values read out of the pinned tree: the codec
+# runs at 12.5 Hz (1,920 samples per frame at 24 kHz), packs 16 codebooks at 11
+# bits = 22 bytes per frame, and the Base talker's speaker encoder emits
+# enc_dim 2048 f32 = 8,192 bytes. The .rvq window is 22 x 248 = 5,456 B up to
+# 22 x 312 = 6,864 B, i.e. crops of 19.84-25 s: an 18 s crop is a legal
+# reference.wav but too little code for the engine, and the builder says so
+# before it runs anything.
+VOICE_PACK_FRAME_RATE=12.5
+VOICE_PACK_RVQ_BYTES_PER_FRAME=22
+VOICE_PACK_SPK_BYTES=8192
+VOICE_PACK_RVQ_MIN_BYTES=5456
+VOICE_PACK_RVQ_MAX_BYTES=6864
+
+# Where a --force rebuild puts the pack it replaced. Nothing is ever deleted;
+# the retired directory stays readable beside its replacement until a human
+# clears it.
+VOICE_PACK_TRASH_DIRNAME=.AGENTTRASH

serverAppConfigs-docs/Dankclaw/Frank TTS Engine.md

@@ -0,0 +1,133 @@
+---
+type: reference
+description: "frank-tts-engine is the arm A TTS engine on Dankclaw: qwentts.cpp's resident tts-server with the 1.7 B base talker, on a private podman bridge behind frank-tts — deployed 2026-10-18, and it publishes no port on purpose."
+tags:
+  - dankclaw
+  - tts
+  - voice
+  - quadlet
+  - cpu
+timestamp: 2026-10-18
+---
+
+# Frank TTS Engine
+
+`frank-tts-engine` is the **arm A text-to-speech engine** on Dankclaw: [qwentts.cpp](https://github.com/ServeurpersoCom/qwentts.cpp)'s resident `tts-server` HTTP process, holding the Qwen3-TTS **1.7 B base talker (Q4_K_M)** and the **12 Hz tokenizer (Q8_0)** in RAM once and synthesizing from there. It listens on container port **8880** and is **deliberately not a fleet endpoint** — the endpoint consumers address is `frank-tts` on **7772**, which resolves voice names, re-encodes to mp3 and owns the timeout budget. This page is the engine runbook; the endpoint's contract lives with its own page.
+
+**Deployed 2026-10-18.** The chain ran in the order at the bottom of this page — fetch (1.4 GiB, byte + LFS oid verified, 18 s), image build against the pinned commit, unit + network install, container-health gate, warm pass — and the live state still reads the way this page describes it: unit `active` with no drop-ins, container healthy 31 s after the build, **4.0 GiB** resident on a host that kept 17 GiB available, `3 voice(s) registered and warm` in the journal, and no published port anywhere. Two things the first real boot taught: the warm hook's registration body must reach curl through a **file**, not an argument (Troubleshooting), and `STEP 3/13 RUN useradd` is the first honest proof of the image's non-root user.
+
+**Host:** Dankclaw (`192.168.0.143`), rootless Podman, user `dank` — **Port:** 8880, **never published** — **Network:** the private `systemd-frank-tts-engine` bridge (10.89.5.0/24) and no other — **Deployer:** `frank-tts-engine` — **Consumers:** `frank-tts` (7772) and, through it, every voice request in the fleet including [[Open Notebook]]'s podcast renders.
+
+## Facts (verified 2026-10-18 against the pinned upstream commit, the Hub, and the CPU trial on this host)
+
+| Item | Value |
+|------|-------|
+| Engine | `tts-server` from qwentts.cpp, pinned at commit `5916bf7c79dbb4e66fc059cdc507a79a23a28bb4` (`dankclaw/voiceservice/Containerfile.engine`). The source is **not vendored**: the image clones that commit and its recorded `ggml` submodule, so the build needs outbound HTTPS and the `cfhash` label is what keeps an unchanged re-deploy offline |
+| Build line | `cmake -B build -DCMAKE_BUILD_TYPE=Release -DGGML_CCACHE=OFF -DGGML_BACKEND_DL=OFF -DGGML_CPU_ALL_VARIANTS=OFF -DGGML_OPENMP=ON -DGGML_BLAS=OFF -DGGML_CUDA=OFF -DGGML_HIP=OFF -DGGML_VULKAN=OFF -DGGML_METAL=OFF -DGGML_SYCL=OFF -DGGML_RPC=OFF && cmake --build build -j 8` — the exact line the 2026-10-18 trial ran on this box. `GGML_BLAS=OFF` is **forced**: Dankclaw has `libopenblas.so.0` and no BLAS dev headers, so upstream's own `Dockerfile` and `buildcpu.sh` (both of which pass BLAS on) cannot be copied. No `-DGGML_NATIVE` is passed, and ggml defaults it on, so the binary is `-march=native` for the machine that built it: **build this image on the host that runs it** |
+| Image | built locally as `franksdank/frank-tts-engine:latest`, two stages from one digest-pinned base `docker.io/library/ubuntu:24.04@sha256:68ee22004a9109b44973313b02ff7b1de250f1de0f5ecb628d73f579aaff33ac` (index digest resolved 2026-10-18). Runtime stage: `libgomp1` (OpenMP is on), `curl` (the unit's `HealthCmd` runs as `/bin/sh -c`, and the warmer speaks HTTP), uid **10000**, `LD_LIBRARY_PATH=/app` because ggml builds shared by default and the link-time RPATH names the build tree |
+| Talker | `qwen-talker-1.7b-base-Q4_K_M.gguf`, **1 219 245 248 B**, sha256 `ea393ebaf2167ea23ce9fc18b093822851358a950d7075cd47ab4f6ce23e887d` (the Hub's LFS pointer oid) |
+| Tokenizer | `qwen-tokenizer-12hz-Q8_0.gguf`, **291 150 624 B**, sha256 `1883beeed99348fc35e23dd225e9082f93f6f8c109330a33d935baa8acdbfd94` |
+| Source of both | `https://huggingface.co/Serveurperso/Qwen3-TTS-GGUF`, fetched by `scripts/download-frank-tts-engine-qwentts.sh` into `/home/dank/models/Qwen3-TTS-GGUF`, mounted read-only at `/models`. It has to be the **base** variant: the engine refuses every voice registration unless the model reports type `base`, so on `customvoice`/`voicedesign` the cloned-voice product does not exist. A 0.6 B talker (628 905 056 B) exists and is **not** the decided artifact |
+| Memory | **5.7 GiB peak RSS** with both files resident (2026-10-18 trial). No `LimitMEMORY`/`MemoryMax`: a limit would turn a busy moment into an OOM kill in the middle of an utterance |
+| Concurrency | `--max-batch 1`: a serialised FIFO. Warm RTF on this box is 0.55–0.67 against real time 1.0, and that margin is the entire headroom a live stream has; two concurrent syntheses split the same cores and the second caller's first byte additionally waits for the first utterance to finish |
+| Network | `systemd-frank-tts-engine` (10.89.5.0/24, `dankclaw/voiceservice/quadlet/frank-tts-engine.network`) and **nothing else**, with **no `PublishPort` at all**. `frank-tts` joins the same bridge and dials `http://frank-tts-engine:8880` |
+| Voices | `/home/dank/voices` mounted read-only at `/voices`, and it is the **warmer** that reads it, not the server: `tts-server` receives reference audio as base64 in a registration body and keeps its registry in memory only |
+| Health | `GET /health` → `{"status":"ok"}`, served by the HTTP thread rather than the synthesis queue, so a busy engine still reads healthy. Probed by the unit (`HealthCmd`, 30 s interval, 120 s start period) **inside the container's namespace**, because there is no published port to probe from outside |
+| Routes | `GET /health`, `GET /v1/models`, `GET|POST /v1/audio/voices`, `DELETE /v1/audio/voices/{name}`, `POST /v1/audio/speech` (`response_format` = `wav` or `pcm`; **default `pcm`**). Everything else is a bare 404. `POST /v1/audio/speech` requires `input`; unknown `voice`, missing `input` and a bad `speed` are 400s, an empty generation is a 502 |
+
+## Why this engine, and not the alternatives
+
+The criterion Frank set on 2026-10-18 was **"whatever is better for live output"**, and live output is decided by time-to-first-audio and by whether the stream stays ahead of real time — not by benchmark throughput. RTF only has to stay under 1.0 with margin; what separates the arms is first-byte latency and **spread**. Measured on this host the same day (CPU; the full A/B is the section *"Decision: arm A for live output (2026-10-18)"* in [[Local TTS and Voice Cloning]], which is the source of these numbers):
+
+| Measure | Resident `tts-server` (arm A, chosen) | Mainline per-request CLI path (arm B) |
+|---|---|---|
+| first audio byte | **86–451 ms** end to end; **94–112 ms** server-side | model load, per request |
+| warm real-time factor while streaming | **0.55–0.67** | 0.93–0.99 |
+| run-to-run spread | **±0.01** | ±0.25 |
+| HTTP surface | serves `/v1/audio/speech` itself | none — façade CLI only |
+
+The spread is the whole argument: at ±0.01 the engine finishes synthesizing 1.5–1.8× faster than the audio plays, every run; at ±0.25 some runs fall behind real time and a live listener hears the stream stall mid-sentence. The rollback path stays in the repo untouched — `TTS_BACKEND=llama-tts-cli` in `scripts/frank-tts.env` still selects the per-request CLI engine, and that file's header documents what it costs.
+
+## Three laws this service lives under
+
+**1. The registry law → the unit warms at boot.** The voice registry is **memory only**: a restart forgets every voice, and re-registering one does **not** warm it — only synthesizing does. A boot that registers nothing leaves the façade answering 400 for every name, which is why `frank-tts-engine.container` carries
+
+```
+ExecStartPost=-/usr/bin/podman exec frank-tts-engine /app/warm-voices.sh
+TimeoutStartSec=900
+```
+
+and the warm pass runs on every start including boot. What it buys is registration (mandatory) plus a measurably smaller first request — and the size of that saving is **not** the number the trial published. **Re-measured on the deployed build, 2026-10-18,** against an empty registry (register, then time the synthesis): the first request for `narrator1` cost **1 883 ms**, the second **1 283 ms**, the third **1 226 ms** — about **0.6 s** of saved silence. A ~110-word request cost **9.4 s** and then **9.8 s**, so request time tracks the audio generated, not snapshot state. The trial's **6.2–8.0 s / first audio byte 5 530 ms / later requests 0.5 ms** ladder does **not** reproduce here; the 0.5 ms figure is an internal state-restore cost that was never an end-to-end request time, and the honest claim is the ~0.6 s above. The `-` prefix is load-bearing: with `Restart=always`, a warmer that exits non-zero would restart the container and crash-loop the endpoint forever. The hook is `podman exec` rather than a host script **because this container publishes nothing** — there is no address the host could dial — and a consequence worth knowing: an exec inherits the unit's `EnvironmentFile`, so the warmer's knobs (`VOICES_DIR`, `HEALTH_WAIT`, `WARM_TEXT`, `REQUEST_TIMEOUT`) live in `scripts/frank-tts-engine.env` beside the engine's own. The deployer runs the same hook a second time so a failed warm becomes a deploy result rather than only a journal line, and so the per-voice numbers land on the console:
+
+```
+frank-tts-engine-warm: voice narrator1 cold=1402ms warm=1812ms
+frank-tts-engine-warm: 3 voice(s) registered and warm
+```
+
+**2. The thread law → nothing is ever pinned.** `tts-server` in this build has **no `-t`/`--threads` flag**: `src/backend.h` computes the CPU thread count as `std::thread::hardware_concurrency() / 2` (its comment: GEMM shares SIMD units across hyperthreads). Thread count therefore follows what the kernel *reports*, not what a cgroup *allows* — so `CPUQuota=`, `CPUAffinity=`, `taskset` or a slice silently changes the engine's GEMM tiling and its timings, with no log line. Nothing in this fleet pins this container. If a neighbour starves it, fix the neighbour.
+
+**3. Streaming is not buffered.** At the same seed, `response_format=pcm` (chunked, codec chunks pushed as they decode) and `response_format=wav` (buffered) differ in **92.2 % of samples**, −41.6 dB RMS. Nothing may compare the two paths, cache one against the other, or assume a seed pins output across `response_format`. `frank-tts` always asks for `wav`; the warmer asks for `wav`; the test seam is forbidden from pinning either.
+
+## The voice registry contract
+
+A voice becomes known to the engine through `POST /v1/audio/voices`, and only these shapes are accepted:
+
+- `{"name": …, "wav_b64": …}` — the reference clip travels as base64 WAV (the engine resamples to 24 kHz internally). **This is what the boot warmer sends.**
+- `{"name": …, "spk_b64": …, "rvq_b64": …}` — the extracted embedding plus the reference codec codes. **`spk_b64` alone is rejected** (`src/tts-server.h:480`): it is `wav_b64` or *both* of the pair.
+
+Whether a registered voice is *embedding-only* or *in-context-learning* is then decided by `ref_text`: `tools/tts-server.cpp:258` selects ICL only when **both** `ref_text` and the reference codes are present. Registering `{name, wav_b64}` with no `ref_text` therefore yields the **x-vector voice** — the shipped default (0.57–0.63 warm RTF against ICL's 0.67) and the only one this fleet can produce honestly, because the audition crops have no trustworthy transcript to put in `ref_text`. The ICL door stays open for batch work like the podcast render: a pack that wants it needs its text in the pack plus one key in the payload built by `dankclaw/voiceservice/tts-engine-warm.sh`.
+
+The packs themselves are host state at `/home/dank/voices/<name>/reference.wav` (24 kHz mono PCM), alongside the `reference.spk` / `reference.rvq` extraction and a manifest. Both halves of the voice stack read that directory — `frank-tts` for its name list, the warmer for its registrations — and `tts-server` never opens it. Two naming facts, both from the source: pack names must be **lowercase**, because `tts_voice_name` lowercases every name engine-side while the façade matches the directory name exactly (the warmer refuses anything outside `[a-z0-9._-]`); and `GET /v1/audio/voices` at this commit returns an empty JSON object rather than the voice list (the handler builds the array and never attaches it to the document), so **use the façade's `/v1/voices` for "which voices exist"** and treat the engine's listing route as broken, not empty.
+
+## Status visibility
+
+The engine is scraped by **nothing in Prometheus** and has **no homepage card**, and both are shape decisions rather than gaps. It exposes no metrics endpoint; and since it publishes no port, there is no address the host's status checker (`scripts/homepage-status.py`, which dials `host:port`) or the `dankclaw_default` Prometheus container could reach. That absence is the point of the network shape, not a cost of it (see [[Container Network Namespaces]] for the netavark rule that makes a host-loopback publish useless to a peer container anyway). The pair's public signal is the endpoint in front of it: [[Frank TTS]] carries the card and is what a consumer can dial. Its up-state is visible in four places, and the runbook uses all of them:
+
+- `systemctl --user status frank-tts-engine` — the unit, including whatever the warm hook logged on the way to `active`.
+- `podman healthcheck run frank-tts-engine` — runs the unit's own `HealthCmd` against `/health` on demand and exits non-zero when the engine does not answer. This is also what `scripts/deploy-remote.sh` gates the deploy on (`wait_container_healthy`), precisely because there is no URL to gate on.
+- `podman exec frank-tts-engine curl -fsS http://127.0.0.1:8880/health` — loopback is valid **inside** the container's namespace, which is where the address lives.
+- The journal of the warm pass: `journalctl --user -u frank-tts-engine`, whose per-voice `cold=` / `warm=` lines are the only signal that voices are actually registered — a live HTTP listener with an empty registry still looks healthy.
+
+The **façade** on 7772 is the pair's public surface and carries the probe. Note the honest limit there: a façade that answers `/health` does **not** prove the engine behind it is alive — it reports its backend and its voice list, not an upstream ping. That is exactly why the warm pass is part of the deploy and not only of the boot.
+
+## Files this service owns
+
+| Path | Role |
+|---|---|
+| `dankclaw/voiceservice/Containerfile.engine` | two-stage build of the pinned commit, proven cmake line, digest-pinned base, ships both scripts |
+| `dankclaw/voiceservice/tts-engine-start.sh` | image entrypoint (`/app/start.sh`): env → flags, refuses to boot without weights |
+| `dankclaw/voiceservice/tts-engine-warm.sh` | boot warmer (`/app/warm-voices.sh`): register from `reference.wav` (body via a temp file), speak a fixed sentence twice, report cold/warm |
+| `dankclaw/voiceservice/quadlet/frank-tts-engine.container` | the unit: bridge only, no publish, env file, two read-only mounts, health probe, warm hook, `Restart=always` |
+| `dankclaw/voiceservice/quadlet/frank-tts-engine.network` | the private 10.89.5.0/24 bridge, with the subnet registry |
+| `scripts/frank-tts-engine.env` | paths and numbers only, with the thread law and the registry law in its header |
+| `scripts/download-frank-tts-engine-qwentts.sh` | weight fetcher: no resume, byte count + LFS oid check, `--verify-only` |
+| `scripts/deploy-remote.sh` → `deploy_frank_tts_engine` | weights gate → build → quadlet → restart → container health → warm |
+| `tests/frank_tts_engine.bats` | the seam: generator output, entrypoint argv, warmer against a stub engine, planner and routing maps |
+
+## Deploy record (host steps, in the order they ran)
+
+Run 2026-10-18 as `./scripts/deploy.sh dankclaw --service frank-tts-engine`, then
+`--service frank-tts`. Steps 1–6 are this service and the façade; only step 7 is
+still open.
+
+1. **Fetch the weights** — `scripts/download-frank-tts-engine-qwentts.sh` (1.4 GiB, byte + sha256 verified, idempotent; `--verify-only` is what the deployer calls).
+2. **Deploy the engine** — `./scripts/deploy.sh dankclaw --service frank-tts-engine` (`--service` is the only way to name one service; `deploy-remote.sh` is the remote half and takes `<target> <git-revision> [service]...`, so never call it by hand with a bare service name). It builds the image (needs github.com once), installs the unit and the network file, gates on the container's health status, then warms.
+3. **Confirm the endpoint is alive** — `podman exec frank-tts-engine curl -fsS http://127.0.0.1:8880/health` → `{"status":"ok"}`, and `systemctl --user status frank-tts-engine` showing the unit `active` with the warm pass behind it.
+4. **Confirm the voices are known** — the warmer's journal lines name every pack, and once the façade is up `curl http://127.0.0.1:7772/v1/audio/voices` is the authoritative list (the façade has exactly three routes: `/health`, `/v1/audio/voices`, `/v1/audio/speech`).
+5. **Measure the ladder instead of trusting the trial** — two identical requests for one voice back to back. The design expected 6.2-8.0 s then 0.5 ms; the deployed container gave **1,883 ms then 1,226-1,283 ms**, so the hook buys ~0.6 s and stays only for the registry reason (law 1). The retired numbers must not be quoted.
+6. **Then the façade on 7772** (its own page), after the engine answered — that order is the whole point of step 6: publishing the façade in front of a dead engine would make every consumer fail at the first voice line.
+7. **Open:** [[Open Notebook]] is still not installed, so nothing renders a podcast yet; the voice leg it waits on now exists.
+
+## Troubleshooting
+
+| Symptom | Meaning | Move |
+|---|---|---|
+| Unit restarts every 10 s, journal says `cannot read /models/…` | weights missing or the mount is empty | run the fetcher; re-deploy |
+| Unit `active`, but every voice name returns 400 from the façade | the engine restarted and lost its in-memory registry, or the warm pass failed | `journalctl --user -u frank-tts-engine` for the warmer's lines; `podman exec frank-tts-engine /app/warm-voices.sh` |
+| Every voice logs `registration failed (HTTP no response)`, with `/usr/bin/curl: Argument list too long` on the line above it | the hook handed the registration body to curl as one argument: the kernel caps a single argument at 131 072 bytes (`MAX_ARG_STRLEN`), and a shipped `reference.wav` base64's to about 1.27 MB | the body goes through a temp file and `--data-binary @file` (2026-10-18). Any pack over ~96 KB trips this, so no small fixture can see it — the seam ships a 300 KB pack for exactly that reason |
+| Everything is ~2× slower after a systemd tweak | a cpuset/cap pin changed `hardware_concurrency()` and the engine resized its thread pools | remove the pin (law 2) |
+| `502` from the façade with `frank-tts upstream request failed` | the façade cannot resolve or reach the engine | `podman network inspect systemd-frank-tts-engine` and `podman inspect frank-tts --format '{{json .NetworkSettings.Networks}}'` — the façade must be attached to the bridge; a `127.0.0.1:8880` or `host.containers.internal:8880` upstream in `scripts/frank-tts.env` is the old shape and cannot work |
+| A voice is missing from the list | its directory has no `reference.wav`, or the name is not lowercase | fix the pack; both are refused loudly by design |
+| `podman exec` in the deploy says `no such file or directory` for `/app/warm-voices.sh` | the image predates the warmer | re-deploy: since 2026-10-18 `build_compose_image` hashes every file the image `COPY`s, not only `Containerfile.engine`, so editing the warmer rebuilds it — see [[deployment]] |
+| The warm pass logs `registered, but the warm synthesis failed` for EVERY voice, while a hand-run `/app/warm-voices.sh` succeeds | `WARM_TEXT` arrived **with its quotes**. podman's `--env-file` does no shell parsing — it takes the literal remainder of the line — so the env-file reader got `"Warm up, one two three."` where `source` gives `Warm up, one two three.`; the quotes plus a backslash then make the synthesis body invalid JSON | the hook strips one matched pair and escapes what is left; prove the value with `podman exec frank-tts-engine env \| grep WARM_TEXT`. The seam pins both readers, because a test that only sources the env file cannot see this |
+| A `502` for `/v1/voices` where the engine answers `200` on `/health` from the same boot | the engine restarted and its in-memory registry is empty again — `/health` is model-loaded, NOT voices-registered | re-run `podman exec frank-tts-engine /app/warm-voices.sh`; that is the same distinction the `frank-tts` healthcheck enforces |

serverAppConfigs-docs/Dankclaw/Frank TTS.md

@@ -0,0 +1,204 @@
+---
+type: reference
+description: "frank-tts is the fleet's cloned-voice speech endpoint on Dankclaw :7772 — the one voice surface consumers address, in front of frank-tts-engine; deployed 2026-10-18 and wired as the harness speech role."
+tags:
+ - dankclaw
+ - tts
+ - voice
+ - quadlet
+---
+
+# Frank TTS
+
+`frank-tts` is the fleet's only speech endpoint: an OpenAI-shaped
+`POST /v1/audio/speech` on **Dankclaw :7772** that answers `voice=<name>` with
+audio in that cloned voice. Everything else in the voice stack sits behind it —
+the engine ([[Frank TTS Engine]]) publishes no port on purpose, and consumers
+never learn a path.
+
+**Deployed 2026-10-18** — `./scripts/deploy.sh dankclaw --service frank-tts`,
+both units `active`, no drop-ins, and the homepage card's `wip` gate came off in
+the same change. Probes on the deployed endpoint: `/health` answers
+`{"status":"ok","backend":"omni-http","voices":["narrator1","narrator2","narrator3"]}`,
+and two different voices rendered the same sentence into **different** bytes
+(24 kHz mono PCM16, 4.24 s, healthy RMS) — so name resolution is real, not a
+pass-through of one default. The operator harness routes its `speech` role here;
+see [[#The harness speech role]]. What still waits is [[Open Notebook]]: its
+render needs the app installed, not this endpoint.
+
+| | |
+| --- | --- |
+| Host | Dankclaw (`192.168.0.143`), rootless podman, user unit `frank-tts.service` |
+| Port | **7772**, published (`PublishPort=7772:7772`); the family is 7770 dragoon, 7771 zealot, 7772 tts |
+| Routes | `GET /health`, `GET /v1/audio/voices`, `POST /v1/audio/speech`; everything else 404, and speech is POST-only |
+| Image | `localhost/franksdank/frank-tts:latest`, built from `dankclaw/voiceservice/Containerfile`, `Pull=never` |
+| Networks | `dankclaw_default` first (it owns the default route and the consumers), then `frank-tts-engine.network` (10.89.5.0/24, the bridge to the engine) |
+| Voice packs | `/home/dank/voices` mounted read-only at `/voices` — host state, never repo state |
+| Upstream | `http://frank-tts-engine:8880` (`scripts/frank-tts.env`, `TTS_UPSTREAM`) |
+| Default voice | `DEFAULT_VOICE` (`scripts/frank-tts.env`) answers a request that names none; the journal marks that line `(default)`, and an **unknown** name is still a 400 |
+| Rollback | `TTS_BACKEND=llama-tts-cli` runs a CLI binary per request and needs no upstream at all |
+
+## Naming a voice
+
+A voice **is** a directory name. `voice=narrator1` resolves to
+`/voices/narrator1/reference.wav`, and that file — not a manifest, not a config
+entry — is what makes the name real. omp's TTS device may send `voice_id`; the
+shim accepts either. A call that sends **neither** — the harness's normal shape,
+because no harness setting carries a voice for this transport — speaks
+`$DEFAULT_VOICE`; empty default makes it a 400 again.
+
+The usable shape is `^[a-z0-9][a-z0-9._-]*$`: lowercase, starting with a letter
+or digit, then letters, digits, `.`, `_`, `-`, at most 64 characters. No slash,
+no `..`, no space, no uppercase. The lowercase requirement is where two rules
+meet: `app.py` would accept `[A-Za-z0-9…]`, but `tts-server` **lowercases
+names**, so a pack called `Narrator1` resolves through the façade and not
+through the engine. The boot warmer therefore refuses a mixed-case directory
+loudly instead of letting it half-work.
+
+Names are user-visible: an unknown voice comes back as
+`400 unknown voice 'x'; available voices: …`, and that list is the honest
+census. The podcast speakers are `narrator1`, `narrator2`, `narrator3` —
+[[Open Notebook]] is configured with exactly those three, so renaming them
+breaks episode rendering, not just speech. A personal voice gets the person's
+name, lowercase.
+
+## Voice packs
+
+One directory per voice under `/home/dank/voices`:
+
+```
+reference.wav    24 kHz mono PCM, 18-25 s of clean single-speaker audio
+reference.spk    engine speaker embedding (8 192 B)
+reference.rvq    reference codec codes (22 B per 12.5 Hz frame)
+manifest.json    source file, offsets, engine, sha256
+```
+
+`reference.wav` is the engine-agnostic term the façade gates on; the other two
+are what makes a voice reusable by this engine, and they come from the pack
+builder ([[Voice Packs]]) — never by hand, never fabricated from the WAV. Two
+laws apply to the
+source material: offsets always start **past the first 10 seconds** of the
+sample, and packs are host state that stays out of this repo. Because the
+container runs as uid 10000, files must be world-readable (`644`/`755`), and the
+directory must exist before the first deploy: rootless podman auto-creates a
+missing bind source **root-owned**, which reads as "no voices" rather than as an
+error.
+
+Adding a voice to a running stack is a two-step thing — drop the pack, then
+register **and warm** it with
+`podman exec frank-tts-engine /app/warm-voices.sh` — because registering alone
+does not warm it. The reason is the cold-voice law in [[Frank TTS Engine]], and
+the procedure with its proof (the second request under a second) is the
+`frank-tts-add-cloned-voice` skill.
+
+## Why the upstream is a container name
+
+`scripts/frank-tts.env` used to point at `http://host.containers.internal:8880`.
+That cannot work, and it is the trap this shape exists to avoid: a bridge
+container reaches the host's network namespace, netavark DNATs **published**
+ports only, and an engine on the host's loopback is published to nobody — the
+same shape that 502'd hermes ([[Container Network Namespaces]]). So both units
+attach to one committed Quadlet network and the façade dials the engine's
+container DNS name.
+
+The consequence worth stating before an operator meets it: **the engine is not
+reachable from the host at all** — not over the LAN, not over loopback. Its
+health, voice registry and logs are observable only through
+`podman exec frank-tts-engine …` and `systemctl --user status`. And the façade's
+own `/health` answers 200 with the backend name and the voice list it resolved
+without dialing the engine, so "façade healthy, engine down" is a real state: it
+shows up as a failed synthesis, never as a down probe.
+
+## Files
+
+| Path | What |
+| --- | --- |
+| `dankclaw/voiceservice/app.py` | the shim: stdlib only — resolves the voice, forwards, re-encodes mp3 |
+| `dankclaw/voiceservice/Containerfile` | python 3.12-alpine pinned by digest + ffmpeg, uid 10000 |
+| `dankclaw/voiceservice/quadlet/frank-tts.container` | the unit: two networks, `Restart=always`, `HealthCmd`, `[Install]` |
+| `dankclaw/voiceservice/quadlet/frank-tts-engine.network` | the shared bridge, named after the engine unit and attached by both |
+| `scripts/frank-tts.env` | backend, upstream, port, limits, and the default voice — paths and numbers, no credentials |
+| `tests/frank_tts_unit.bats` | the shim against stub engines over real sockets |
+| `tests/frank_tts_engine.bats` | the pair's wiring: generator output, planner, homepage, deployer |
+
+## Deploying it
+
+`./scripts/deploy.sh dankclaw --service frank-tts` (or `--service frank-tts-engine --service frank-tts` for the pair):
+builds the façade image, installs **both** Quadlet units — including the
+engine's `.network` file, because a referenced `Network=` file the generator
+cannot find means the façade unit is not produced at all — creates
+`/home/dank/voices` as the deploy user, restarts the unit (whose `Wants=` and
+`After=` pull the engine and its warm pass ahead of it) and gates on podman's
+recorded health. It never runs `systemctl --user enable`; boot persistence is
+the `[Install]` section in each unit. Order matters in a full deploy:
+[[Frank TTS Engine]] is planned before this, and both before [[Open Notebook]].
+
+## Not scraped, and why
+
+`shared/prometheus/` gets **no** frank-tts job, and that is a considered
+absence. The façade exports no `/metrics` — `app.py` serves `/health` plus the
+speech route only — and this Prometheus 3 install refuses non-metrics content
+types: [[Prometheus]] records that the existing HTML probes (`comfyui`, the two
+`services` targets) sit **down** with
+`received unsupported Content-Type … and no fallback_scrape_protocol specified`.
+A `/health` probe job would therefore be structurally never-green, and because
+`LlmEndpointDown` is scoped `up{job=~"frank-.*"} == 0`, a permanently red
+`frank-tts` target would page on Signal every few minutes for an endpoint that
+is fine — the frank-archon lesson pointed the other way. The engine cannot be
+scraped at all: it publishes nothing. Status lives in `systemctl --user status`,
+`podman healthcheck run`, the two unit journals, and the homepage card, which
+probes `127.0.0.1:7772` for real now — the `wip: down` gate came off with the
+2026-10-18 deploy.
+
+## The harness speech role
+
+The operator harness reaches this endpoint through
+`~/.omp/agent/models.yml` — provider `frank-tts (dankclaw)`,
+`baseUrl: http://192.168.0.143:7772/v1`, `auth: none`, and the runner api
+`openai-speech` on the **model** row (naming a runner api at *provider* level
+fails the whole file's validation and disables every custom provider, which is
+how the fleet's chat endpoints disappear) — plus `config.yml`
+`modelRoles.speech: frank-tts (dankclaw)/frank-tts`. Four laws, read out of the
+harness bundle and measured the day of the flip:
+
+- **The only voice the harness can send is the `voice_id` argument of the call.**
+  The transport builds `{model, input, response_format, voice?}` and adds `voice`
+  **only** when the caller passed `voice_id`; no setting feeds it.
+  `tts.localVoice` is the *local Kokoro backend's* voice (it is what answered
+  `voice=kokoro/bm_george, backend=local` in the control test), and
+  `speech.voice` is the TUI's **speak-aloud** voice — its enum is Kokoro's list,
+  and it never reaches an HTTP request. So a harness call arrives voice-less by
+  default, which is exactly why the endpoint grew `DEFAULT_VOICE`: the declared
+  pack answers a voice-less request and the journal marks that line `(default)`,
+  while an **unknown** name still 400s with the list that exists.
+- **`speech.voice` must stay a Kokoro name.** Setting it to a pack name does not
+  select a pack; it hands the vocalizer a value outside its enum. (The first
+  draft of this section said the opposite and was reverted the same day, after a
+  fresh session's call came back `unknown voice None`.)
+- **There is no silent fallback.** An explicitly configured `modelRoles.speech`
+  yields exactly one candidate, so a dead 7772 fails the speech device with
+  *"No available speech model matches the speech role"* instead of quietly
+  degrading to Kokoro. That is the price of `auth: none` (which makes a dead
+  endpoint read as available) and it is the wanted shape: a narration job should
+  fail loudly rather than ship a voice Frank never asked for.
+- **A session older than the models.yml row cannot see it.** `models.yml` loads
+  at process start while `config.yml` is read live, so a long-lived session
+  carrying the flipped role fails exactly like a dead endpoint while a fresh
+  process succeeds in the same minute. Measured 2026-10-18: the open session
+  failed twice (provider/id form, then the bare id), `local/kokoro` succeeded in
+  that same session, and a fresh `omp -p --tools tts` returned `Saved 180524
+  bytes (model=frank-tts (dankclaw)/frank-tts, voice=narrator1, codec=wav)`
+  while the façade logged the matching `speech voice=narrator1 format=wav
+  chars=51 -> 180524 bytes` from the podman bridge. Rule the stale registry out
+  before blaming the service.
+
+## Troubleshooting
+
+| Symptom | Cause |
+| --- | --- |
+| `400 unknown voice 'x'; available voices: …` | the name is not a pack: case, spelling, missing `reference.wav`, or an empty/root-owned `/home/dank/voices` |
+| `(none: no voice pack with a reference.wav in /voices)` | the mount, not the voices: `podman inspect frank-tts --format '{{json .Mounts}}'`, then the directory owner |
+| Endpoint answers, synthesis fails | the engine: `podman healthcheck run frank-tts-engine`, then `systemctl --user status frank-tts-engine.service` |
+| First request of the day is ~0.6 s slower than the rest — or every name returns 400 | the warm pass did not run; it carries `-`, so it cannot fail the unit. `journalctl --user -u frank-tts-engine` for the warmer's lines, then `podman exec frank-tts-engine /app/warm-voices.sh` — the registry is memory-only (law 1 of [[Frank TTS Engine]]) |
+| The unit never appears after a deploy | the generator dropped it: `frank-tts-engine.network` is missing from `~/.config/containers/systemd/` |
+| A consumer rejects `narrator1` by listing 29 names (`af_heart … bm_fable`) and no request ever reaches this endpoint | that consumer is synthesizing **in the browser** with Kokoro.js, whose voice pack is fixed — OpenWebUI 0.11.4 ships it as the `browser-kokoro` TTS engine; see [[OpenWebUI]] |

serverAppConfigs-docs/Dankclaw/Open Notebook.md

@@ -59,7 +59,7 @@ podman exec open-notebook curl -sS http://frank-tts:7772/health
 podman exec open-notebook curl -sS http://host.containers.internal:7771/v1/models
 ```
 
-**The blocker to state plainly:** frank-tts is built, named and tested but **not deployed** — nothing answers on 7772 (`ss -ltn`, Dankclaw, 2026-10-18; [[Local TTS and Voice Cloning]] records the same census). open-notebook deployed today writes scripts and fails at the first voice line. frank-tts ships first, or podcast generation waits.
+**The blocker moved; it did not vanish.** frank-tts and frank-tts-engine are **deployed** (2026-10-18) and answer on 7772, so the voice leg works end to end — `podman exec open-notebook curl -sS http://frank-tts:7772/health` is the check to run the day the app exists. What still blocks a render is open-notebook itself: not installed on this host yet. When it is, the two provider rows above are the only wiring, and the seeded speaker profiles carrying OpenAI voice names are the first trap.
 
 **Why frank-zealot and not frank-dragoon:** podcast scriptwriting asks the model for a JSON-schema response (with a plain-JSON fallback). llama.cpp's OpenAI-compatible endpoint is a known-good target for that; frank-dragoon's halogen runtime has **unverified** structured-output behaviour, so it is the unproven alternative, not the fallback. `ESPERANTO_LLM_TIMEOUT=180` (the app's own default) covers an outline or transcript call on zealot comfortably; upstream's note is to keep it under 600 so a slow call fails with a clear error instead of a UI timeout.
 

serverAppConfigs-docs/Dankclaw/OpenWebUI.md

@@ -43,14 +43,16 @@ As of 2026-10-07 the picker exposes **exactly one model: `frank-zealot`** *(unve
 |---|---|---|---|---|---|
 | 0 | `http://host.containers.internal:7770/v1` | no (2026-10-07) | `frank-dragoon` | halogen flash-server (Strix Halo iGPU) | Dankclaw |
 | 1 | `http://192.168.0.235:7770/v1` | no (2026-10-07) | `frank-archon` | radiance TP=2 (2× R9700) | Dankserver |
-| 2 | `http://host.containers.internal:7771/v1` | yes | `frank-zealot` | llama.cpp CUDA (RTX 3090; production shape 3×262,144 per `scripts/frank-zealot.env`) | Dankclaw |
+| 2 | `http://host.containers.internal:7771/v1` | yes | `frank-zealot` | llama.cpp CUDA (RTX 3090; production shape 2×262,144 exact f16 KV per `scripts/frank-zealot.env`) | Dankclaw |
 
 The URLs in the first column are the DB's recorded values and predate the 2026-08-22
 bridge move; on this network they are wrong — see the reachability gotcha below, which
 is the corrected law. Note also that the 2026-10-18 **bench window** on `:7771`
 closed the same day (production unit stopped 03:38 per the repo Benchmarking
 Policy while candidate arms held the port): the candidate — Ternary-Bonsai-2-**9B**
-PQ2_0 with the MTP head, 3 × 262,144 — was **deployed as production**, so the
+PQ2_0 with the MTP head, deployed that afternoon at 3 × 262,144 q8_0 KV and
+resliced the same evening to **2 × 262,144 over exact f16 KV** — was **deployed
+as production**, so the
 picker row below was re-keyed to it (see the next paragraph).
 
 The `model` table carries exactly two decoration rows, `frank-zealot` and
@@ -292,6 +294,42 @@ carries base64 image data or a URL.
 Failure modes: connection refused ⇒ OpenWebUI or ComfyUI is down; timeouts
 on large sizes ⇒ check ComfyUI resources; 401 ⇒ the token is bad.
 
+## Text-to-speech (frank-tts)
+
+TTS is the fleet's one OpenAI-compatible speech endpoint —
+`http://host.containers.internal:7772/v1` (`audio.tts.openai.api_base_url`
+in the config DB, 2026-10-18), model `frank-tts`, voice `narrator1`. That
+port is the rootless quadlet `frank-tts` (this repo:
+`dankclaw/voiceservice/quadlet/frank-tts.container`,
+`scripts/frank-tts.env`), and its shim resolves `voice=<name>` against
+`/home/dank/voices/<name>/reference.wav` — a name without a reference is a
+400 listing the voices that exist, never a silent fallback.
+
+**The 29-voice `af_* … bm_fable` list is NOT frank-tts.** That enum belongs
+to **Kokoro.js running in the browser**: the deployed front end (0.11.4)
+ships an in-page Kokoro implementation (chunk carrying a frozen voice table
+`{af_heart:{name:"Heart",…}}` and `_validate_voice`, model
+`onnx-community/Kokoro-82M-v1.0-ONNX`, plus a personal *Kokoro.js dtype*
+setting). Its engine select takes `""` (Default) or `browser-kokoro`; when
+`browser-kokoro` is chosen the page synthesizes locally and rejects any
+voice outside its fixed pack — so `narrator1` fails with
+`Voice: "narrator1" not found. Should be one of: af_heart, …` **without a
+single request reaching the server**. Personal audio settings are per
+browser: no `user.settings` row and no container env carries an audio
+override, yet the toast still appears ⇒ the choice lives in that browser's
+own storage. Fix in the UI: Settings → Audio → TTS Engine → **Default**,
+which hands synthesis to the admin config (frank-tts); picking `af_heart`
+instead keeps Kokoro, and Kokoro cannot clone — fixed pack only.
+
+Verified 2026-10-18 from inside the container with the exact OpenWebUI body
+(`{"model":"frank-tts","input":…,"voice":"narrator1",
+"response_format":"mp3","speed":1.0}`) → **200, `audio/mpeg`, 7,629 B**,
+while `podman logs open-webui` recorded **zero** `audio/speech` requests for
+the failing click — that contrast is the instrument: a server-path failure
+leaves a log line and a frank-tts error, a `browser-kokoro` failure leaves
+neither.
+
+
 ## Retired instances
 
 - The compose `open-webui` service (port 3000) was never run: 3000 is Gitea's HTTP port, so it could not bind.
@@ -349,6 +387,7 @@ on large sizes ⇒ check ComfyUI resources; 401 ⇒ the token is bad.
 ## See Also
 
 - [[Dankclaw Stack]]
+- [[Frank TTS]] — the speech endpoint behind *Text-to-speech (frank-tts)*
 - [[Hermes]] — the agent OpenWebUI can talk to
 - [[SearXNG]] — the search engine on this host
 - [LLM knowledge base](../LLM/index.md) — the vLLM and llama.cpp endpoints

serverAppConfigs-docs/Dankclaw/Voice Packs.md

@@ -0,0 +1,261 @@
+---
+type: reference
+description: "How a frank-tts voice pack is built on Dankclaw: the three files every pack must carry, the 10-second source-material gate scripts/build-voice-pack.sh enforces, how to add a fourth voice, and what to do when a pinned engine bump changes the extractor's output sizes."
+tags:
+  - dankclaw
+  - frank-tts
+  - voices
+  - tts
+timestamp: 2026-10-18
+---
+
+# Voice Packs
+
+A **voice pack** is the unit of identity for **frank-tts**: one directory under
+`/home/dank/voices`, named by the voice, carrying the reference audio that makes
+the name real plus the pinned engine's own speaker artifacts and a provenance
+record. `voice=narrator1` on `POST /v1/audio/speech` resolves to
+`/home/dank/voices/narrator1/reference.wav` and to nothing else — a name without
+that file is a 400 that lists the names that do exist, because a silent fallback
+voice is how a wrong-voice endpoint stays wrong for weeks.
+
+**Host:** Dankclaw (192.168.0.143) — **Pack root:** `/home/dank/voices`, host
+state that stays out of the repo, mounted read-only at `/voices` by the façade
+unit — **Builder:** `scripts/build-voice-pack.sh` with tunables in
+`scripts/voice-packs.env` — **Seam:** `tests/voice_pack_unit.bats` — **Engine:**
+arm A `qwentts.cpp`, decided in [[Local TTS and Voice Cloning]].
+
+Packs are **world-readable on purpose** (`drwxr-xr-x`, owner `dank`): the façade
+container runs as uid 10000 and reads the mount from outside its own uid map.
+
+## The required files
+
+| File | What it is | Who reads it |
+|------|------------|--------------|
+| `reference.wav` | the crop: 24 kHz mono `pcm_s16le`, **18–25 s** of clean single-speaker audio | the façade (it is the existence gate for the name) and the engine's boot warmer, which base64s it and registers the voice with no transcript |
+| `reference.spk` | the engine's x-vector: **8,192 B** = `enc_dim` 2048 × f32 | the engine, for the ICL/`--ref-spk` path |
+| `reference.rvq` | the engine's RVQ code stream: **5,456–6,864 B**, 16 codebooks × T frames packed at 11 bits = 22 B per 12.5 Hz frame | the engine, for the ICL/`--ref-rvq` path |
+| `manifest.json` | provenance: source path and sha256, crop start/end offsets, sample rate, duration, the tool and engine commit that made the artifacts, and the `voice` name | humans, and the builder itself on its second gate assertion |
+
+`qwen-codec.log` rides along with the extractor's own record of the run; the
+façade ignores anything it does not name and never deletes anything.
+
+Division of enforcement, which is deliberate and not a gap: the **façade** gates
+on `reference.wav` because that is the only engine-agnostic term (see the
+voice-pack law in `scripts/frank-tts.env`); the **builder** is what refuses to
+emit a pack without its engine artifacts; the **engine** registers a voice from
+the WAV alone because its own `POST /v1/audio/voices` refuses a lone embedding —
+it wants `wav_b64` or **both** `spk_b64` and `rvq_b64`. So the artifacts are in
+the pack to make ICL a per-voice opt-in, not to boot it.
+
+## How a pack is built
+
+```bash
+# everything except the extractor: gate, crop, probe, plan, the manifest it would write
+scripts/build-voice-pack.sh --dry-run narrator1 /home/dank/voices
+
+# the real thing, on the host that holds the engine build
+scripts/build-voice-pack.sh narrator1 /home/dank/voices
+```
+
+Crops come from `scripts/voice-packs.env` — per voice: source path, offset,
+duration, and the source's pinned sha256 — and any of them can be overridden on
+the command line (`--source`, `--offset`, `--duration`, `--sha256`, `--tool`).
+`--all` walks `VOICE_PACKS`. The builder assumes no GPU, no container, no fleet
+endpoint and no network: `ffmpeg` cuts the crop, the pinned extractor makes the
+artifacts, and both run `nice -n 19` so a build never competes with the text
+endpoints on that box.
+
+The extractor is `qwen-codec` in the `qwentts.cpp` tree at
+`VOICE_PACK_ENGINE_COMMIT` (`5916bf7c79dbb4e66fc059cdc507a79a23a28bb4`). Its
+usage text, read out of that tree and not guessed:
+
+```
+Usage: qwen-codec --model <gguf> [-i <input>] [--talker <gguf>] [--format <fmt>]
+
+Required:
+  --model <gguf>          Codec GGUF (qwen-tokenizer-12hz-*.gguf)
+
+Optional:
+  --device <name>         Compute device: CUDA0, Vulkan0, MTL0, CPU...
+                          (default: best available)
+  -i <path>               Input. WAV -> encode, .rvq -> decode
+  --talker <gguf>         Talker GGUF (Base only). Encode also extracts the speaker
+                          embedding and writes it next to the .rvq as a .spk file
+  --format <fmt>          WAV output format: wav16, wav24, wav32 (default: wav16)
+
+Output is auto-named next to input : clip.wav -> clip.rvq, clip.rvq -> clip.wav.
+```
+
+Three consequences shape the builder. **There is no `-o`**, so the pack's WAV is
+staged under its final stem and the artifacts land beside it with nothing to
+rename. **`--talker` must be a _Base_ talker** — the customvoice and voicedesign
+GGUFs carry no speaker encoder and the tool says `has no speaker encoder (Base
+only)`. **Encode truncates to the hop boundary**, so the `.rvq` size is arithmetic,
+not chance: `22 × floor(samples / 1920)` bytes, which is where the recorded
+5,456–6,864 B window comes from and why the **effective crop window is
+19.84–25 s** even though the WAV law says 18–25 s. A crop shorter than that is
+refused before the extractor runs, with the number in the message.
+
+The build is staged and published, never assembled in place: `reference.wav` is
+the file the façade reads, so it moves into position **last**, after the
+artifacts and the manifest. A failed extractor therefore leaves a pack directory
+that is not a voice. Nothing is ever deleted — an existing pack is refused unless
+`--force`, and `--force` moves the whole old directory to
+`/home/dank/voices/.AGENTTRASH/<voice>-<UTC>/` and builds fresh beside it.
+
+Measured on the shipped `narrator1` crop (2026-10-18, `--dry-run` against the
+real source): 98.739–118.636 s → `955,378 B` of 24 kHz mono `pcm_s16le`, 19.897
+s, planned `.rvq` 5,456 B — the same byte counts the trial produced by hand, and
+the extractor itself costs 1.8–2.1 s and 1.3–1.5 GiB peak per voice.
+
+## The 10-second gate
+
+Project-wide source-material invariant: **the first 10 seconds of any sample
+file used to generate voices is forbidden material.** An offset that starts
+inside it is refused with exit 1 and a message that names the invariant, before
+a directory is created:
+
+```
+ERROR: source-material invariant violated: the crop must start past the first
+10 s of the source file, and 'narrator1' asks for 4.5 s into … — nothing was
+written.
+```
+
+The same gate is then asserted **from the manifest** that was just written —
+`.crop.offset_seconds >= .invariant.forbidden_source_seconds`, plus the recorded
+sha256 against the source it claims — so a pack cannot reach disk carrying a
+forbidden crop even if the offsets in the env file are edited into nonsense.
+`10` is not a knob: `scripts/voice-packs.env` carries the offsets, the sample
+rate, the windows and the engine facts, but the forbidden region is a constant in
+the builder. `tests/voice_pack_unit.bats` pins both halves (a refusal that
+creates nothing, and one legal crop that builds the whole pack) and applies the
+invariant to every crop in the tracked pack list.
+
+## Adding a fourth voice
+
+1. Pick the source file and hash it: `sha256sum /path/to/sample.wav`. A crop
+   offset is a claim about one exact file, so the digest goes in the env with it.
+2. Find a speech-dense stretch **past 10 s**. The trial's recipe, applied once:
+   `ffmpeg -ss 60 -t 600 -i SRC -af silencedetect=noise=-35dB:d=0.6 -f null -`,
+   build the runs of non-silence, keep runs ≥ 18 s, take the longest (earliest
+   on ties), and cap at 25 s. Aim for 20–25 s: shorter than 19.84 s and the
+   `.rvq` falls under the floor.
+3. Add the four lines to `scripts/voice-packs.env` and the name to
+   `VOICE_PACKS`:
+
+   ```
+   VOICE_PACKS="narrator1 narrator2 narrator3 narrator4"
+
+   VOICE_PACK_NARRATOR4_SOURCE=/home/dank/voice-sources/audiosample4.m4b
+   VOICE_PACK_NARRATOR4_OFFSET=142.31
+   VOICE_PACK_NARRATOR4_DURATION=24
+   VOICE_PACK_NARRATOR4_SHA256=<64 hex>
+   ```
+
+   The name must be lowercase `[a-z0-9._-]`: the façade matches the directory
+   name verbatim while `tts-server` lowercases names internally, so an uppercase
+   name would be reported one way by the façade and another by the engine. The
+   builder refuses one anyway.
+4. `scripts/build-voice-pack.sh --dry-run narrator4 /home/dank/voices`, read the
+   plan, then drop `--dry-run`.
+5. `./tests/run.sh` (the pack-list invariant test covers the new row for free).
+6. Register it with the running engine. The engine's voice registry is
+   memory-only and warm-on-boot, but a restart re-decodes **every** voice (6–8 s
+   each), so adding one pack uses the hook instead:
+
+   ```bash
+   podman exec frank-tts-engine /app/warm-voices.sh
+   curl -s localhost:7772/v1/audio/voices      # the façade's list, not the engine's
+   ```
+
+   The hook walks `/voices` and registers **every** pack that has a
+   `reference.wav`, on every run — the engine replaces a name it already holds
+   (`tools/tts-server.cpp:148` at the pinned commit: *"Re-registering a name
+   replaces the previous entry."*) — then synthesizes twice per voice and logs
+   `voice <name> cold=…ms warm=…ms` to the unit's journal. The two numbers should
+   be close; see law 1 of [[Frank TTS Engine]] for what they measure. The rootless
+   unit restart — `systemctl --user restart frank-tts-engine.service` — is for when
+   the unit or its env changed, not for a new pack.
+
+## When the extractor's output size changes on an engine bump
+
+The builder treats the two artifact sizes as properties of the pinned engine, so
+an engine bump that changes them **fails the build**: `reference.spk is N B,
+expected 8192 B` or `reference.rvq is N B, expected …`. That is the failure being
+loud, not a bug. Work through it in order:
+
+1. Re-read the tool's own numbers rather than trusting this page: `qwen-codec`
+   prints `SpeakerEncoder] Loaded: enc_dim=…` and `Pipeline] Ready: hop … , …
+   codebooks @ … Hz` on every run, and the pinned tree's
+   `tools/qwen-codec.cpp` documents the packing. `enc_dim × 4` is the `.spk`;
+   `codebooks × code_bits / 8` bytes per frame × frames is the `.rvq`.
+2. Decide whether the new number is intended. A changed `enc_dim` means the old
+   `.spk` files are unreadable by the new engine, so **every** pack must be
+   rebuilt, not just the failing one.
+3. Update the four arithmetic lines in `scripts/voice-packs.env`
+   (`VOICE_PACK_SPK_BYTES`, `VOICE_PACK_RVQ_MIN_BYTES`, `VOICE_PACK_RVQ_MAX_BYTES`,
+   and `VOICE_PACK_RVQ_BYTES_PER_FRAME` if the codebook packing changed) **and**
+   `VOICE_PACK_ENGINE_COMMIT`, `VOICE_PACK_TOOL`, `VOICE_PACK_CODEC_MODEL`,
+   `VOICE_PACK_TALKER_MODEL` to the new build. An env diff that moves the sizes
+   without moving the commit is the mistake to avoid.
+4. Rebuild all three packs with `--force` (the retired directories keep the old
+   bytes readable beside their replacements until a human clears them), then
+   re-run the warm hook: `podman exec frank-tts-engine /app/warm-voices.sh`. That
+   hook registers **every** pack it finds on every run, and the engine replaces a
+   name it already holds — `tools/tts-server.cpp:148` at the pinned commit says so
+   in its own words: *"Re-registering a name replaces the previous entry."* So the
+   rebuilt `reference.wav` is what the running engine speaks afterwards, and the
+   hook's cold/warm pass is what re-snapshots it. A restart
+   (`systemctl --user restart frank-tts-engine.service`) is what an ENGINE bump
+   needs — the registry is memory-only and lives in that process — and the unit
+   runs the same hook on every start anyway, so a restart is never worse, only
+   slower.
+5. `./tests/voice_pack_unit.bats` — the stub in that seam reproduces the packing
+   law, so it needs the same arithmetic update as the env file. The seam's
+   engine-bump test is exactly this scenario with a wrong `.spk` size, and its
+   assertion — no `reference.wav`, no manifest — is the property that matters.
+
+## Host state (census 2026-10-18, read-only)
+
+- `/home/dank/voices/` holds `narrator1`, `narrator2`, `narrator3`, each with
+  `reference.wav`, a `reference16k.wav`, and a `manifest.json` **in the trial's
+  own schema** (`kind: voice-reference-pack`, a silence-scan record). They carry
+  **no** `reference.spk` / `reference.rvq`: the trial's artifacts live in its own
+  work directory (`/home/dank/voice-audition/qwentts/voices/`, and only for
+  narrator1 and narrator2). The builder's first real run is therefore a
+  migration, and it should be a `--force` run per voice so the old directories
+  are retired rather than left half-updated.
+- The three source files (`/home/blank/audiosample.mp3`,
+  `audiosample2.m4b`, `audiosample3.m4b`, digests pinned in
+  `scripts/voice-packs.env`) live on the workstation, not on Dankclaw; the
+  builder reads them from `$VOICE_PACK_SOURCE_DIR=/home/dank/voice-sources`, so
+  they have to be copied there once before a build.
+- `VOICE_PACK_TOOL` points at the trial's build tree
+  (`/home/dank/voice-audition/qwentts/qwentts.cpp/build/qwen-codec`, checked out
+  at exactly `5916bf7c`), and the two GGUFs at
+  `/home/dank/models/Qwen3-TTS-GGUF/`, which is where the engine slice's
+  download script puts them — that directory does not exist yet, so until it
+  does the models have to come from the trial's `models/` directory.
+- Nothing is deployed: nothing listens on 7772 or 8880 today, so building packs
+  is possible on that host while serving them is not.
+
+## Known gaps, on purpose
+
+- **No transcript in the manifest.** ICL wants a `ref_text` that matches the
+  crop, and the trial's machine transcripts came back wrong ("Demon Souls" for
+  *Dark Souls*). Transcribing on the host is not a fix, so the pack carries none
+  and the engine registers the WAV-only voice, which is what its boot warmer
+  does anyway. When ICL becomes a per-voice opt-in, the curated transcript
+  belongs in this manifest — a human-supplied field, not something the builder
+  can derive.
+- **No 16 kHz variant.** The packs the trial left behind carry
+  `reference16k.wav` for the `llama-tts-cli` rollback engine; arm A is native
+  24 kHz, so the builder emits one reference. `--force` retires the whole
+  directory including that variant, so if the rollback engine is ever revived:
+  `ffmpeg -i reference.wav -ar 16000 -c:a pcm_s16le reference16k.wav`.
+- **No loudness pass.** The trial's pipeline also measured and normalised
+  (two-pass `loudnorm`, `astats`, `ebur128`, spectrograms) to a `-16 LUFS` spec.
+  None of that is in the pack law, which asks for 24 kHz mono inside the
+  duration window, so the builder does only that; a future engine that is
+  loudness-sensitive should get the pass as an explicit, documented step.

serverAppConfigs-docs/LLM/deployment.md

@@ -116,6 +116,34 @@ On a later ordinary deployment, a service remains pending only while its
 recorded revision differs from the checkout and the planner still finds a
 change in that service's inputs.
 
+## Locally built images
+
+`build_compose_image` in `scripts/deploy-remote.sh` builds the images that have
+no registry digest — `comfyui-rocm`, `franksdank/loki`, `franksdank/alloy` and
+the voice pair `franksdank/frank-tts` / `franksdank/frank-tts-engine` — and
+**skips** the build when a `cfhash` label on the installed image matches a hash
+it computes from the checkout now. That skip is what keeps the engine's
+ten-minute `git clone --recursive` off every re-deploy, so the rule has to be
+honest about what the image bakes:
+
+- The hash covers the `Containerfile` **plus the files its `COPY` lines pull
+  in**, named as `extra=(…)` in each case arm. Hashing the `Containerfile`
+  alone was wrong in practice: editing `dankclaw/voiceservice/app.py` or
+  `tts-engine-warm.sh` left the label matching, `podman build` never ran, and
+  the redeployed container still carried the previous code while `/health`
+  answered — invisible to every gate. Corrected 2026-10-18;
+  `tests/frank_tts_engine.bats` drives the function against a stub `podman`
+  (first deploy builds, unchanged tree does not, a `COPY`'d file rebuilds).
+- A base-image assumption is part of the image's identity too. The engine's
+  runtime stage creates its unprivileged user with `useradd`, not `adduser`,
+  because the pinned `ubuntu:24.04` base ships no `adduser` — checked by
+  running the command against the digest on 2026-10-18. That failure mode is a
+  build that dies at the `RUN` line, so it is loud, unlike the stale-hash one.
+
+Both engines keep serving during a rebuild: `build_compose_image` runs after
+`install_quadlet` only for the LLM-style handlers, and the voice deploy gates on
+recorded health rather than a fixed sleep — see [[Frank TTS Engine]].
+
 ## Manual recovery
 
 If the LLM handler fails after the target pull:

serverAppConfigs-docs/LLM/frank-zealot-llama-mimo-q5km.md

@@ -26,7 +26,7 @@ timestamp: 2026-10-03
 > the PrismML 27B era of [[frank-zealot-llama-prism-bonsai2-pq20]] (build 10754,
 > 2 × 200,704 q8_0 KV, MTP off) — retired 2026-10-17 → 10-18 as a rollback
 > target; the active row today is build **10777** on
-> `Ternary-Bonsai-2-9B-PQ2_0-MTP-Q8_0.gguf` at 3 × 262,144 q8_0 KV, MTP off by
+> `Ternary-Bonsai-2-9B-PQ2_0-MTP-Q8_0.gguf` at 2 × 262,144 exact f16 KV, MTP off by
 > measurement (AGENTS.md Runbook Index). The Q5_K_M
 > payload is still on disk (`stat -c %s` 2026-10-18 → 6876124704).
 

serverAppConfigs-docs/LLM/frank-zealot-llama-mimo-q6k.md

@@ -20,13 +20,16 @@ timestamp: 2026-10-01
 > [[frank-zealot-llama-mimo-q5km]], the same runtime and shape one quant rung
 > down. The Q6_K file stays at `/home/dank/models/MiMo-Q6K/` as the rollback
 > target (on disk 2026-10-18, `stat -c %s` → 7793710624). :7771 today runs
-> [[frank-zealot-llama-prism-bonsai2-pq20]] (llama.cpp PrismML fork build 10754,
-> `Ternary-Bonsai-2-27B-PQ2_0.gguf`, 2 × 200,704, q8_0 K + q8_0 V, MTP off).
+> [[frank-zealot-llama-prism-bonsai9-mtp]] (llama.cpp PrismML fork build
+> **10777**, `Ternary-Bonsai-2-9B-PQ2_0-MTP-Q8_0.gguf`, 2 × 262,144,
+> exact f16 K + f16 V, MTP off by measurement).
 >
 > Original order (Frank, 2026-10-01 night): move this endpoint to the GGUF
 > path for **asymmetric KV** — unquantized K + q8_0 V — which only llama.cpp
 > exposes per-tensor. The per-tensor lever stayed; this pairing did not — the
-> live endpoint bills q8_0 K + q8_0 V (`scripts/frank-zealot.env:55-56`).
+> live endpoint bills **exact f16 K + f16 V** — 32,768 B/token = 16,384 MiB
+> over the 524,288-position pool of two 262,144 windows
+> (`scripts/frank-zealot.env:57-58,80-81`).
 
 ## Identity
 

serverAppConfigs-docs/LLM/frank-zealot-llama-prism-bonsai9-mtp.md

@@ -1,7 +1,7 @@
 ---
 type: reference
-title: "frank-zealot on Dankclaw — llama.cpp (PrismML fork 10777), Bonsai-2-9B PQ2_0 with the MTP head, 3 × 262144, q8_0 KV (ACTIVE)"
-description: "The ACTIVE frank-zealot runbook (since 2026-10-18) — the PrismML fork build 10777 of llama.cpp serving prism-ml/Ternary-Bonsai-2-9B-gguf at PQ2_0 on the RTX 3090: THREE conversations of 262,144 tokens (every slot at the model's trained window) over q8_0 K + q8_0 V, vision through the publisher's Q8_0 Qwen3-VL projector, and the five-arm boot census that put speculative decoding OFF by measurement even though the checkpoint carries the MTP head."
+title: "frank-zealot on Dankclaw — llama.cpp (PrismML fork 10777), Bonsai-2-9B PQ2_0 with the MTP head, 2 × 262144, exact f16 KV (ACTIVE)"
+description: "The ACTIVE frank-zealot runbook (since 2026-10-18) — the PrismML fork build 10777 of llama.cpp serving prism-ml/Ternary-Bonsai-2-9B-gguf at PQ2_0 on the RTX 3090: TWO conversations of 262,144 tokens (every slot at the model's trained window) over an UNQUANTIZED f16 K + V cache, vision through the publisher's Q8_0 Qwen3-VL projector, and the boot-arm census that put speculative decoding OFF by measurement even though the checkpoint carries the MTP head."
 tags:
   - llm
   - frank-zealot
@@ -14,15 +14,22 @@ tags:
 timestamp: 2026-10-18
 ---
 
-# frank-zealot — llama.cpp (PrismML) Bonsai-2-9B PQ2_0 + MTP head, 3 × 262,144, q8_0 KV
+# frank-zealot — llama.cpp (PrismML) Bonsai-2-9B PQ2_0 + MTP head, 2 × 262,144, exact f16 KV
 
 Live since 2026-10-18, replacing the
 [[frank-zealot-llama-prism-bonsai2-pq20]] era (Ternary-Bonsai-2-**27B** PQ2_0 at
-2 × 200,704). The trade in one sentence: the 9B bills **half** the KV per token
-of the 27B, and that is exactly what funds **three** conversations at the
-model's **native 262,144** window where the 27B afforded only two shortened
-ones (Frank's ask: *"if you can possibly fit a third context, do it"*). Every
-axis improved — decode, prefill, three-stream aggregate, and free VRAM.
+2 × 200,704). The original trade: the 9B bills **half** the KV per token of the
+27B, and that is what funded **three** conversations at the model's **native
+262,144** window where the 27B afforded only two shortened ones (Frank's ask:
+*"if you can possibly fit a third context, do it"*).
+
+The shape moved again the same evening (Frank: *"shift frank-zealot to 2
+parallels of unquantized kv"*). The KV cache went **exact** — f16 K + f16 V, no
+quantization error anywhere in the attention state — and the **slot count paid
+for it: 3 → 2**. The per-slot contract never moved; every conversation is still
+262,144, still the trained window. What the dtype bought is fidelity, and what
+it costs is one concurrent conversation plus the bytes attention reads per
+generated token.
 
 ## Payload identity
 
@@ -46,9 +53,12 @@ axis improved — decode, prefill, three-stream aggregate, and free VRAM.
    refuses the custom type at load; a loader that ignored the Hadamard metadata
    would dequant **wrong**, silently. Same lock class as the ROCmFPX era.
 2. **The build floor.** The fork's card gates **MTP beside a quantized V cache**
-   on `prism-b10776-d00e252` or newer, so the prebuilt moved **10754 → 10777**
-   for this swap. The 10754 tree stays on disk (`~/GitPackages/llama-prism/`) as
-   the 27B rollback runtime. `tests/frank_zealot_unit.bats` pins both paths.
+   on `prism-b10776-d00e252` or newer, which is why the prebuilt moved
+   **10754 → 10777** for the swap. Exact f16 KV makes that gate moot — there is
+   no quantized V to pair with the drafter — but tumbler 1 pins the runtime on
+   its own: stock llama.cpp cannot load this file at any flag value. The 10754
+   tree stays on disk (`~/GitPackages/llama-prism/`) as the 27B rollback
+   runtime. `tests/frank_zealot_unit.bats` pins both paths.
 
 ## Header census (read from the GGUF, not the card)
 
@@ -71,41 +81,66 @@ axis improved — decode, prefill, three-stream aggregate, and free VRAM.
 | `general.sampling.*` | temp 1.0 / top_p 0.95 / top_k 20 / min_p 0.0 / repeat 1.0 | the card recipe; llama.cpp reads it itself |
 
 **KV accounting.** Only the 8 full-attention layers scale with context:
-8 × 4 KV heads × 256 dim = **8,192 elements/token per cache**, so
-**q8_0 K + q8_0 V bills 17,408 B/token** — the 786,432-position pool is
-**13,056.00 MiB**, ledger-exact. That is exactly HALF the 27B's 34,816 B/token.
-**f16 KV would bill 26,112 MiB against a 24,123 MiB card** and dies at
-`cudaMalloc`. The 24 DeltaNet layers bill a fixed recurrent state per SLOT
-instead: the PRODUCTION ledger prints `RS buffer size = 150.75 MiB (3 cells,
-32 layers, 3 seqs)` ≈ 50 MiB a cell, while the SPEC-ARMED arms printed
-452.25 MiB — MTP depth 2 bills three seqs per slot, so the drafter triples
-even the recurrent state. Pool arithmetic alone under-prices the shape.
+8 × 4 KV heads × 256 dim = **8,192 elements/token per cache** (the engine prints
+`n_embd_k_gqa = n_embd_v_gqa = 1024`). **The deployed pair is exact: f16 K +
+f16 V bills 32,768 B/token** (2 B/element × 8,192 elements × 2 caches), so the
+524,288-position pool is **16,384 MiB**. The q8_0 pair this endpoint shipped
+first billed **17,408 B/token** — 1.0625 B/element, 32 codes plus one 2-byte
+scale per 32-block — the **13,056.00 MiB** its ledger printed at the 786,432
+pool, exactly HALF the 27B's 34,816 B/token.
+
+**Corrected arithmetic, and it matters.** The note that lived here and in
+`frank-zealot.env` — "f16 would bill 26,112 MiB" — doubled the q8_0 figure
+*including* its scale overhead, overstating exact KV by 6.25 %. Exact f16 at the
+786,432 pool is **24,576 MiB** against the **24,123 MiB** the driver leaves
+addressable (`nvidia-smi`'s total column reads 24,576; used + free reads 24,123
+— the difference is driver reservation). The wall stands in both readings; the
+honest rate is what makes the fit calculable instead of superstitious. **Halving
+the POOL is what funds exact KV** — the window is already at the native ceiling
+and there is no YaRN in this path.
+
+The 24 DeltaNet layers bill a fixed recurrent state per SLOT instead: the 3-slot
+ledger printed `RS buffer size = 150.75 MiB (3 cells, 32 layers, 3 seqs)` ≈
+**50.25 MiB a cell**, so two slots bill 100.50. The SPEC-ARMED arms printed
+452.25 MiB — MTP depth 2 bills three seqs per slot, so the drafter triples even
+the recurrent state. Pool arithmetic alone under-prices the shape.
 
 ## The shape (`scripts/frank-zealot.env`)
 
-`--ctx-size 786432 --parallel 3` (⇒ `n_ctx_slot = 262,144`), `--flash-attn on`,
-`--cache-type-k q8_0 --cache-type-v q8_0`, `--batch-size 4096`,
+`--ctx-size 524288 --parallel 2` (⇒ `n_ctx_slot = 262,144`), `--flash-attn on`,
+`--cache-type-k f16 --cache-type-v f16`, `--batch-size 4096`,
 `--ubatch-size 2048`, `--n-gpu-layers 99`, `--jinja`, `--reasoning auto`,
 `--reasoning-format deepseek`, `--metrics`, `--mmproj …`, `--log-verbosity 4`,
 `--presence-penalty 1.0`,
 **`SPEC_TYPE=none`** (which strips `--spec-type` AND every `--spec-draft-*`).
 
 Per-slot window is the **contract** the harness quotes: `models.yml` carries
-`contextWindow: 262144`. llama.cpp refuses a prompt longer than the SLOT with a
-400 naming the limit — it never truncates — and since this swap the slot window
-equals the native window, so no YaRN and no cap is in play.
+`contextWindow: 262144`, and it did **not** move with the slot count because
+llama.cpp divides `--ctx-size` across slots. It refuses a prompt longer than the
+SLOT with a 400 naming the limit — never a truncation — and since this swap the
+slot window equals the native window, so no YaRN and no cap is in play.
+`tests/frank_zealot_unit.bats` now gates the arithmetic: the shipped dtype ×
+pool plus the measured non-KV ledger terms must fit 24,123 MiB with ≥1 GiB of
+slack, and the gate is proven to REFUSE the impossible arm (exact KV at the old
+786,432 pool = 24,576 MiB of cache alone).
 
 ## The MTP verdict: the head is in the file and it is still OFF
 
 The drafter is **good**: acceptance 0.798 / 0.617 per position, mean accepted
-length 2.41, and the card recommends depth 2. It loses **at this shape**
-because the draft context bills its own **f16** KV over the WHOLE pool —
-`blk.32` carries real attention (4 KV heads × 256 × 2 caches × 2 B =
-**4,096 B/position**) × 786,432 positions = **3,072.00 MiB**, 4,830 MiB with its
-compute buffers — and `--ubatch-size 2048` refuses to give that up.
+length 2.41, and the card recommends depth 2. It is OFF because the draft
+context bills its own **f16** KV over the WHOLE pool — `blk.32` carries real
+attention (4 KV heads × 256 × 2 caches × 2 B = **4,096 B/position** at the
+default dtype). The draft dtype is itself a knob — `--spec-draft-type-k` /
+`--spec-draft-type-v`, both default f16, verified against this build's `--help`
+(so the "no flag exists" claim that lived here is FALSE) — and quantizing the
+draft to q8_0 would bill 2,176 B/position, **1,088 MiB** at the shipped pool.
+**No measured arm runs a drafter beside exact KV**; every row below is f16 draft.
 
-Booted arms, same card, same traffic, 2026-10-18 (`/completion` `timings`,
-greedy 512 tokens; never the first request after a boot):
+The census below is the **q8_0 era**: every row is q8_0 K + q8_0 V at the
+786,432 pool, where the draft bill was 3,072.00 MiB and 4,830 MiB with its
+compute buffers. Booted arms, same card, same traffic, 2026-10-18
+(`/completion` `timings`, greedy 512 tokens; never the first request after a
+boot):
 
 | slots | spec | ubatch | used / free | decode | 3-stream | prefill @106k |
 |---|---|---|---|---|---|---|
@@ -117,15 +152,26 @@ greedy 512 tokens; never the first request after a boot):
 
 **MTP is worth +28 % single-stream decode whenever the card has room** (rows
 4–5 prove the drafter itself is a win; row 2 proves the squeeze is what halves
-it). The arm that runs MTP at three windows is `SPEC_TYPE=draft-mtp` +
-`UBATCH_SIZE=1024` (row 3) and pays **prefill −17 %** and **2,725 MiB of
+it). The arm that ran it at three windows was `SPEC_TYPE=draft-mtp` +
+`UBATCH_SIZE=1024` (row 3), paying **prefill −17 %** and **2,725 MiB of
 headroom** on a card whose mmproj worst-case lands AFTER the engine's own fit
-check. This endpoint is the fleet's **compaction hub** — prefill-bound ~170k
-inputs plus 2–3 concurrent subagents — so the shipped arm takes the +17 %
-prefill and +12 % three-stream aggregate over single-stream speed, and keeps
-6.2 GiB free. Frank confirmed this arm on 2026-10-18.
+check.
 
-## Boot ledger (production boot 2026-10-18 13:19, under the unit, verbosity 4)
+**Under exact KV an f16-draft arm is priced out of this card.** The draft
+context is built at the TARGET's pool, so at 524,288 positions it bills
+4,096 × 524,288 = **2,048.00 MiB** plus its own buffers, on a trunk that already
+projects **~21,200 MiB** of the 24,123 MiB addressable. The doors back to
+speculation are **one window per conversation** (row 5's class of shape), **KV
+back to q8_0** with `UBATCH_SIZE=1024`, or the **unmeasured**
+`--spec-draft-type-k q8_0 --spec-draft-type-v q8_0` arm — 1,088 MiB of draft,
+legal on b10777, never booted beside exact KV. Frank chose exact KV over the
+drafter on 2026-10-18, and the endpoint's actual job is what made that
+affordable: the fleet's **compaction hub** is prefill-bound on ~170k inputs,
+prefill is weight-bandwidth bound and does not re-read the cache per generated
+token — so the dtype is paid in decode and concurrency, not in the work this
+service exists to do.
+
+## Boot ledger — the q8_0 3-slot production boot (2026-10-18 13:19, under the unit, verbosity 4)
 
 ```
 CUDA0 model buffer size  =  2036.71 MiB    # + 257.66 MiB CPU_Mapped (mmap)
@@ -141,7 +187,30 @@ No clamp line, no `cudaMalloc` error. The engine's own projection (21,439-class
 numbers from the 27B era) excludes the projector — **read settled `nvidia-smi`,
 never the projection**.
 
-## Measured (production boot, `/completion` `timings`, greedy, `ignore_eos`)
+**The exact-KV boot, measured** (2026-10-18 evening, PR #21, under the unit,
+verbosity 4 — the live shape):
+
+```
+CUDA0 model buffer size  =  2036.71 MiB    # + 257.66 MiB CPU_Mapped (mmap)
+CUDA0 KV buffer size     = 16384.00 MiB    # f16 K + f16 V, 524,288 positions
+CUDA0 RS buffer size     =   100.50 MiB    # 2 cells, 32 layers, 2 seqs
+CUDA0 compute buffer     =  1408.06 MiB    # + 1088.07 MiB CUDA_Host
+mmproj worst-case (est.) =   868.32 MiB    # 248.10 CUDA + 24.93 CPU, AFTER fit
+nvidia-smi settled: 21,176 MiB used / 2,949 MiB free of 24,123
+n_slots = 2, n_ctx_slot = 262144, kv_unified = false
+```
+
+The pre-flight projection was right to the MiB, because the two terms it moved
+are exact arithmetic: **16,384.00 MiB of KV is precisely 32,768 B/token ×
+524,288 positions** — rate derivation and ledger agree with no slop, which is
+what buries the old 26,112 MiB figure for good — and the recurrent state is one
+50.25 MiB cell lighter (100.50 exactly). Settled card state landed at **21,176
+used / 2,949 free**, within 24 MiB of the 21,200 / 2,920 projection,
+`DropInPaths` empty, no clamp line, no `cudaMalloc` error. It is a desktop
+margin, though: the mmproj's 868 MiB worst case is still charged AFTER the
+engine's own fit check, so ~2 GiB is what an image storm has to live inside.
+
+## Measured — the q8_0 3-slot boot (`/completion` `timings`, greedy, `ignore_eos`)
 
 - **168.7 t/s** decode — three runs of 512 tokens: 168.4 / 168.7 / 168.7
   (the trial arm printed 167.2; same shape, same noise band).
@@ -156,15 +225,52 @@ never the projection**.
   stops on its own: a 24-token countdown measured 72 t/s across three streams
   while the same shape with `ignore_eos` gave 300.
 
+## Measured — the exact-KV boot (floors, not a clean A/B)
+
+Instrument: `/v1/chat/completions` `timings` (this fork refuses the raw
+`/completion` path for greedy runs — see *Contract traps*), greedy,
+`ignore_eos`, 512 tokens, first request discarded.
+
+|Arm|q8_0 3-slot record|f16 2-slot, live co-tenancy|
+|---|---|---|
+|single-stream decode|168.7|**134.1 – 141.5** over five back-to-back runs; 145.8 and 163.2 in a lighter minute|
+|concurrent aggregate|≈300 across 3 (102.8 each)|**256.6 / 262.4 / 265.1** across 2 (≈128–133 each)|
+|prefill at ~106k|2,877 at 106,418|**3,159.5 at 106,282**|
+|decode at 106k depth|never measured|**71.5**|
+
+**These are floors, not the shape's rates.** Someone else was driving the
+endpoint through the whole window — 56 new prompts on the other slot in three
+minutes, `nvidia-smi` at 96 % GPU-util — which is the exact condition the
+Benchmarking Policy forbids, and a contended deep arm even came back truncated
+(a 512 KB body accepted as `prompt_n = 4`). What the floors already support:
+**per-conversation concurrency improved** (two streams hold ~130 t/s each where
+three held 102.8), endpoint aggregate sits ~12 % under the 3-slot record,
+prefill beat the record (+9.8 %) while contended, and single-stream decode is
+between parity and −20 % against it. The 1.882× KV byte bill is real; its true
+size on this card is still unmeasured, and quoting 134 t/s or 163 t/s as "the"
+number would be a guess in either direction. Re-run the same arms with the box
+quiet before the figure is carried anywhere else.
+
 ## Contract traps
 
 - **`--metrics` is mandatory.** Without it llama.cpp answers **501** on
   `/metrics`, so the Prometheus scrape reads DOWN while `/health` answers 200 —
   that is how this endpoint sat red across four payload generations
+
   (`up{job="frank-zealot"}` oldest retained sample, 2026-10-11, is already 0).
+- **Bare `/completion` is a dead instrument on this fork build.** A greedy
+  `ignore_eos` run answers **500 — "The model produced output that does not
+  match the expected Content-only format"**, because the fork guards the raw
+  path the moment reasoning markup leaks (older builds only logged `failed to
+  parse reasoning content` and answered anyway). The honest per-request
+  instrument on THIS build is `/v1/chat/completions`, whose non-stream response
+  carries the same `timings` object (`prompt_n`, `prompt_per_second`,
+  `predicted_n`, `predicted_per_second`). `AGENTS.md` still names the
+  `/completion` `timings` object as this endpoint's instrument — on build 10777
+  read it off the chat path.
 - **Q8_0 mmproj, not BF16.** The publisher's card: the BF16 tower "can crash
   llama-server when several image requests run at once; Q8_0 is not affected" —
-  and `--parallel 3` is precisely that shape.
+  and `--parallel 2` is still precisely that shape.
 - **Only the `image_url` content part reaches the model.** The legacy top-level
   `images` field bumps `usage.prompt_tokens` and the model still invents an
   answer. Probe with a solid color and expect the exact word.
@@ -216,9 +322,11 @@ never the projection**.
 `frank-zealot` here — 262,144 is the widest window in the fleet and the only one
 that comfortably fits a worst-case compaction input (~170k tokens; the clamp is
 `min(maxTokens 16384, contextWindow − est − 4096)`, compaction fires at 85 % of
-the window ≈ 222,822 est, worst case ≈ 245,891 ≤ 262,144). With `--parallel 3`
-a compaction request no longer serializes behind a live generation (the Gemma4
-era's `--parallel 1` law).
+the window ≈ 222,822 est, worst case ≈ 245,891 ≤ 262,144). What the reslice to
+**two** slots does cost is here: a compaction request still runs beside ONE live
+generation, but with two conversations already busy a third waits — the Gemma4
+era's `--parallel 1` serialization law at half strength. The window itself is
+untouched, and the window is the term the compaction contract depends on.
 
 ## Deploy ledger (2026-10-18)
 
@@ -263,12 +371,24 @@ era's `--parallel 1` law).
 
 ## Fallback rungs
 
-1. `UBATCH_SIZE=1024` — frees **1,306 MiB** measured on this shape (prefill
-   −17 %).
-2. `CACHE_TYPE_K/V=q4_0` — frees ~6.5 GiB at three windows (the 27B era measured
-   the q4_0 rung at 16,392 used / 7,733 free at 2 × 200,704).
-3. Cut to 2 slots — but that breaks the third concurrent subagent, so it is a
-   last resort, not a knob.
+Cheapest first; every one is a single line of `scripts/frank-zealot.env`, and
+the KV figures are for the 524,288-position pool unless stated otherwise:
+
+1. `UBATCH_SIZE=1024` — hands back **1,306 MiB** of compute buffers measured on
+   this card (prefill −17 %).
+2. `CACHE_TYPE_V=q8_0` — exact K, quantized V: the pool goes 16,384 →
+   **12,544 MiB**, freeing 3,840, and it is the halfway door back.
+   `--flash-attn on` is what keeps quantized V legal.
+3. `CTX_SIZE=401408` — two 200,704 conversations: exact KV at
+   **12,544.00 MiB**, same 3,840 freed, but `models.yml` `contextWindow` MUST
+   follow the per-slot number or long turns start 400-ing.
+4. Revert to `q8_0` K + `q8_0` V at `CTX_SIZE=786432 PARALLEL=3` — the shape
+   this one replaced: 13,056.00 MiB of cache and the THIRD conversation back.
+5. `CACHE_TYPE_K/V=q4_0` — the far rung: 10,240 B/token ⇒ **5,120 MiB** here
+   (the 27B era measured q4_0 at 16,392 used / 7,733 free at 2 × 200,704).
+
+Any retune has to keep the seam's fit gate green — it is the only instrument
+that can see a boot that would die at `cudaMalloc`.
 
 ## Rollback
 

serverAppConfigs-docs/LLM/frank-zealot-llama-qwen35-9b-q6k-2x200704.md

@@ -18,7 +18,7 @@ timestamp: 2026-10-07
 [[frank-zealot-llama-prism-bonsai2-pq20]] (27B PQ2_0, 2 × 200,704 q8_0 KV, build
 10754), itself retired 2026-10-17 → 10-18 and now the rollback target: :7771
 today is llama.cpp PrismML build **10777** on
-`Ternary-Bonsai-2-9B-PQ2_0-MTP-Q8_0.gguf`, 3 × 262,144 q8_0 KV, MTP off by
+`Ternary-Bonsai-2-9B-PQ2_0-MTP-Q8_0.gguf`, 2 × 262,144 exact f16 KV, MTP off by
 measurement (AGENTS.md Runbook Index active row; `scripts/frank-zealot.env`).
 Transient 2026-10-18: :7771 is inside a bench window — the unit is `failed`
 since 03:14 and a hand-booted process answers the port; restore with

serverAppConfigs-docs/LLM/frank-zealot-llama-swift15-unc-iq3xxs-mtp-114688.md

@@ -22,7 +22,7 @@ timestamp: 2026-10-06
 > frank-small the same night). Superseded by
 > [[frank-zealot-llama-qwen35-9b-q6k-2x200704]]; the production shape on :7771
 > today is llama.cpp PrismML build **10777** on
-> `Ternary-Bonsai-2-9B-PQ2_0-MTP-Q8_0.gguf`, 3 × 262,144 q8_0 KV, MTP off by
+> `Ternary-Bonsai-2-9B-PQ2_0-MTP-Q8_0.gguf`, 2 × 262,144 exact f16 KV, MTP off by
 > measurement (AGENTS.md Runbook Index active row); the 27B PQ2_0 / 2 × 200,704
 > shape of [[frank-zealot-llama-prism-bonsai2-pq20]] is that era's rollback
 > target. Transient 2026-10-18 bench window on :7771 — the unit is `failed`

serverAppConfigs-docs/LLM/frank-zealot-sglang-mimo-v26.md

@@ -20,8 +20,9 @@ timestamp: 2026-10-01
 > **RETIRED 2026-10-01, hours after cutover** (AGENTS.md Runbook Index). Replaced by
 > [[frank-zealot-llama-mimo-q6k]] — llama.cpp CUDA on the MiMo Q6_K GGUF,
 > chosen for the asymmetric KV (f16 K + q8_0 V) SGLang cannot express. :7771
-> today runs [[frank-zealot-llama-prism-bonsai2-pq20]] (llama.cpp PrismML fork
-> build 10754, `Ternary-Bonsai-2-27B-PQ2_0.gguf`, 2 × 200,704 q8_0 KV, MTP off).
+> today runs [[frank-zealot-llama-prism-bonsai9-mtp]] (llama.cpp PrismML fork
+> build **10777**, `Ternary-Bonsai-2-9B-PQ2_0-MTP-Q8_0.gguf`, 2 × 262,144,
+> exact f16 K + f16 V, MTP off by measurement).
 > The venv (`/home/dank/GitPackages/sglang-cu128/`) is still on disk; the INT8
 > payload was staged to
 > `/home/dank/.AGENTTRASH/20261002-retired-llm-payloads/` on 2026-10-02 and
@@ -59,8 +60,8 @@ timestamp: 2026-10-01
   the two-way concurrency contract. **That compaction arithmetic is
   specific to a 262,144-token slot**: the shape that followed on 2026-10-02
   ran three slots of 180,224, which 183,501 tokens already exceeds — see *What
-  three slots cost* in [[frank-zealot-llama-mimo-q5km]]; :7771 runs two 200,704
-  slots today.
+  three slots cost* in [[frank-zealot-llama-mimo-q5km]]; :7771 today runs two
+  262,144-token conversations over one 524,288-position pool with exact f16 KV.
 - **KV:** `fp8_e4m3` — 16 KiB/token (8 attn layers x 2 x 4 heads x 256
   dim x 1 B), pool 9.31 GiB.
 - **The memory shape (the 4.5 GiB the naive math misses):** the DeltaNet

serverAppConfigs-docs/LLM/index.md

@@ -26,9 +26,10 @@ MTP spec decode always-on (HALOGEN_SPEC_ADAPT=0), TWO slots over ONE
 200704, vision ON)** and
 **llama.cpp on the PrismML fork (frank-zealot, port 7771: prism-ml
 Ternary-Bonsai-2-9B at **PQ2_0** — 9B qwen35 hybrid (8 full-attention + 24
-Gated DeltaNet layers + the blk.32 MTP block), THREE 262,144-token
-conversations, MTP present in the file but OFF by measurement,
-q8_0 K + q8_0 V (f16 KV does not fit the RTX 3090 at this window), vision via
+Gated DeltaNet layers + the blk.32 MTP block), TWO slots over ONE
+524,288-position pool (2 × the 262,144 window), MTP present in the file but
+OFF by measurement, **exact f16 K + f16 V** — 32,768 B/token = **16,384 MiB**
+of KV (three 262,144 windows at exact KV do not fit the RTX 3090), vision via
 the publisher's own Q8_0 mmproj, on the RTX 3090 — and the custom
 tensor type 141 + `prism.hadamard.*` metadata mean no other loader can open the
 file)**.
@@ -63,7 +64,7 @@ ONE 401408-position KV pool at ctx 200704 = 2 slots x ctx, MTP always-on, image
         G[llama.cpp PrismML fork CUDA build
 frank-zealot, port 7771]
         H[Ternary-Bonsai-2-9B PQ2_0 GGUF + Q8_0 mmproj
-3 x 262144 ctx, q8_0 K + q8_0 V, MTP off, mmproj vision]
+2 slots over ONE 524288-position pool at ctx 262144, exact f16 K + f16 V, MTP off, mmproj vision]
         E2 --> E --> F
         E2 --> G --> H
     end
@@ -132,19 +133,26 @@ frank-zealot, port 7771]
   custom PQ2_0 tensor type + `prism.hadamard.*` transform, and since this swap
   also the minimum build that pairs MTP with a quantized V cache) serving
   prism-ml/Ternary-Bonsai-2-9B-gguf **PQ2_0 with the MTP head IN the file** on
-  the RTX 3090 — **THREE 262,144-token conversations**
-  (`--ctx-size 786432 --parallel 3`, every slot at the window the model was
-  trained at), **q8_0 K + q8_0 V** (17 KiB/token over the 8 full layers =
-  13,056 MiB ledger-exact; the f16 pair needs 26,112 MiB and dies at
-  `cudaMalloc`), settled **17,876 used / 6,249 free**, vision via the
-  publisher's **Q8_0** mmproj (Q8_0 is the publisher's requirement for
-  concurrent image requests, and this runs three slots), **MTP OFF by
-  measurement** — the draft context bills its own f16 KV over the WHOLE pool
-  (3,072 MiB) and at `UBATCH_SIZE=2048` that squeeze halves decode
-  (167.2 → 109.2 t/s); `SPEC_TYPE=draft-mtp` + `UBATCH_SIZE=1024` is the
-  documented 213.5 t/s arm, declined for +17 % prefill and 6.2 GiB of headroom.
-  Measured: 167.2 t/s single-stream decode, 2,877 t/s prefill at 106,418,
-  280.2 t/s aggregate across three streams. `--metrics` rides (`METRICS=1`):
+  the RTX 3090 — **TWO 262,144-token conversations**
+  (`--ctx-size 524288 --parallel 2`, every slot at the window the model was
+  trained at), **unquantized f16 K + f16 V** (32,768 B/token over the 8 full
+  layers = **16,384 MiB** exact; the POOL halved because that rate over the
+  OLD 786,432 pool bills 24,576 MiB against the 24,123 the driver leaves
+  addressable, and the old "26,112 MiB" note was wrong — it doubled the
+  q8_0 figure (17,408 B/token = 13,056 MiB) *including* its 1/32 scale
+  overhead, so f16/q8_0 is **1.882×**, not 2×), the q8_0-era boot settled
+  **17,876 used / 6,249 free**, vision via the publisher's **Q8_0** mmproj
+  (Q8_0 is the publisher's requirement for concurrent image requests, and this
+  runs two slots), **MTP OFF by measurement** — the draft context bills its own
+  f16 KV over the WHOLE pool (4,096 B/position × 524,288 = 2,048 MiB) and at
+  `UBATCH_SIZE=2048` that squeeze halves decode (167.2 → 109.2 t/s);
+  `SPEC_TYPE=draft-mtp` + `UBATCH_SIZE=1024` is the documented 213.5 t/s arm,
+  declined for +17 % prefill and 6.2 GiB of headroom — and exact KV leaves an
+  f16-draft arm no room at all (a quantized draft, `--spec-draft-type-* q8_0`,
+  is the unmeasured door).
+  Measured at the q8_0-era shape: 167.2 t/s single-stream decode, 2,877 t/s
+  prefill at 106,418, 280.2 t/s aggregate across three streams. `--metrics`
+  rides (`METRICS=1`):
   llama.cpp answers 501 on `/metrics` without it, which is why Prometheus
   `up{job="frank-zealot"}` read 0 for its whole retained history until
   2026-10-18. `contextWindow: 262144` is the **widest in the fleet**, so this

serverAppConfigs-docs/Research/Local TTS and Voice Cloning.md

@@ -258,11 +258,17 @@ HTTP path at all — that is what the façade's CLI backend exists for.
 
 Four laws came out of the trial, each worth a line of configuration:
 
-- **Boot-warm every voice.** The first request for a registered voice decodes
-  the whole reference to snapshot codec state: 6.2–8.0 s, first audio byte at
-  5,530 ms. Later requests restore that state in 0.5 ms. An engine unit must
-  run one throwaway synthesis per voice at start, or the first request of the
-  day pays five seconds.
+- **Boot-warm every voice.** The trial measured the first request for a
+  registered voice at 6.2–8.0 s (first audio byte 5,530 ms) and later requests
+  restoring the snapshot in 0.5 ms. **That ladder did not survive deployment:**
+  measured 2026-10-18 on the built container against an empty registry — register,
+  then time — the first synthesis of a freshly registered voice cost **1,883 ms**
+  against **1,226–1,283 ms** for the requests after it, and a ~110-word request
+  cost **9.4 s** then **9.8 s**, so request time tracks the audio generated rather
+  than snapshot state. What still holds is the reason to warm at all: the registry
+  is memory-only and re-registering does not warm, so an engine unit must run one
+  throwaway synthesis per voice at start. It buys registration and about 0.6 s,
+  not five seconds.
 - **Speaker artifacts are reusable and exact.** `qwen-codec` turns a reference
   WAV into `.spk` (8,192 B x-vector) + `.rvq` (5,456–6,864 B, 16 codebooks × T,
   11-bit packed) in 1.8–2.1 s at 1.3–1.5 GiB peak; replaying them yields a
@@ -322,9 +328,11 @@ a live stream mid-sentence.
 **Chosen: arm A, 1.7 B talker, resident `tts-server` in a `frank-tts-engine`
 container, with `TTS_BACKEND=llama-tts-cli` kept in the repo as the rollback.**
 Three consequences are configuration, not opinion: the unit **boot-warms every
-voice** (5.5 s cold first byte otherwise), it **does not pin a cpuset** casually
-(threads are `hardware_concurrency()/2`, no flag), and every pack registers with
-the **WAV** because the engine rejects a lone embedding.
+voice** — the registry is memory-only, so an unwarm'd name is a 400 and the first
+synthesis otherwise costs about 0.6 s more than the ones after it, as corrected
+above —, it **does not pin a cpuset** casually (threads are
+`hardware_concurrency()/2`, no flag), and every pack registers with the **WAV**
+because the engine rejects a lone embedding.
 
 Two follow-ups stay open on purpose, and neither blocks the deploy:
 

serverAppConfigs-docs/index.md

@@ -80,6 +80,9 @@ macOS mini) as quadlets inside its podman machine — not on Dankserver.
 - [[Seerr]] — unified *arr request manager (guard-chained; fronts FrankBook-Pro's stack)
 - [[Marreta]] — content-cleaning proxy (guard-chained; shares SearXNG's Gluetun egress)
 - [[Open Notebook]] — podcast generator (scripts by frank-zealot, voices by frank-tts); repo-owned config, not deployed
+- [[Frank TTS Engine]] — the arm A TTS engine (`qwentts.cpp` resident `tts-server`, 1.7 B talker) behind frank-tts on a private bridge; deployed on Dankclaw, CPU-only, publishes no port by design
+- [[Frank TTS]] — the 7772 cloned-voice endpoint consumers address: voice naming, pack layout, why the upstream is a container name; deployed, and it is the harness `speech` role
+- [[Voice Packs]] — how a frank-tts voice is built: reference.wav + the pinned engine's speaker artifacts, cut past the 10-second source-material gate
 
 ## Infrastructure
 
@@ -406,10 +409,15 @@ The LLM inference fleet on the two hosts. Full index:
   loader for the custom PQ2_0 tensor type / `prism.hadamard.*`, and the floor
   for MTP beside a quantized V cache) serving
   prism-ml/Ternary-Bonsai-2-9B-gguf **PQ2_0 with the MTP head** on the RTX 3090
-  — THREE 262,144-token conversations, q8_0 K + q8_0 V (f16 OOMs at this pool:
-  26,112 vs 13,056 MiB over 8 full-attention layers), MTP **off by
-  measurement** (the draft context bills 3,072 MiB of f16 KV over the whole
-  pool), vision through the Q8_0 mmproj; boot 17,876 used / 6,249 free
+  — TWO 262,144-token conversations (`--ctx-size 524288 --parallel 2`), exact
+  f16 K + f16 V = **16,384 MiB** over 8 full-attention layers (32,768 B/token;
+  the per-slot window is UNCHANGED at 262,144 — what halved is the POOL,
+  because exact f16 over the OLD 786,432 pool bills **24,576 MiB** against the
+  **24,123** the driver leaves addressable; the old "26,112 vs 13,056 MiB" note
+  doubled the q8_0 figure with its 1/32 scale overhead included, so f16/q8_0 is
+  1.882×, not 2×), MTP **off by measurement** (the draft context bills 2,048
+  MiB of f16 KV over the whole pool, and exact KV leaves no room for one),
+  vision through the Q8_0 mmproj; boot 17,876 used / 6,249 free (the q8_0 era)
 - [[frank-zealot-llama-prism-bonsai2-pq20]] — RETIRED 2026-10-17 → 10-18
   (rollback target, payload + build 10754 on disk): Ternary-Bonsai-2-**27B**
   PQ2_0 at TWO 200,704-token conversations, q8_0 K + q8_0 V, MTP **impossible**

serverAppConfigs-docs/log.md

@@ -1,5 +1,32 @@
 # Bundle Change Log
 
+## 2026-10-18
+- **frank-zealot resliced to two windows of exact KV (Frank's call, PR #21).**
+  `--ctx-size 786432 --parallel 3` at q8_0 K+V → **`524288 / 2` at f16 K+V**, so
+  both remaining conversations keep the native 262,144 window and the
+  compaction hub reads exact K and V. Halving the pool is what funds it: the
+  f16 pair is 32,768 B/token over the 8 full-attention layers = 16,384.00 MiB,
+  while the old 786,432-position pool would have needed ~24,576 MiB of KV alone
+  on a card that leaves 24,576 addressable. Measured boot: KV **16,384.00**,
+  RS **100.50** (2 cells), compute 1,408.06 + 1,088.07, settled `nvidia-smi`
+  **21,176 used / 2,949 free**, `n_ctx_slot = 262144`, `DropInPaths` empty. The
+  doc's old "f16 needs 26,112 MiB and cannot boot" figure was the 27B's
+  34,816 B/token applied to the 9B — corrected in the runbook.
+- **Rates are floors, and that is recorded as such.** The endpoint had another
+  consumer for the whole measurement window (56 prompts on the other slot in
+  three minutes, 96 % GPU-util), so single-stream decode came back 134.1–141.5
+  (145.8/163.2 in a lighter minute) against the 3-slot record of 168.7,
+  two-stream aggregate 256.6–265.1 against ≈300 across three, and prefill
+  **3,159.5 at 106,282** beat the record's 2,877 while contended. Per-stream
+  concurrency improved (≈130 each vs 102.8); a clean re-measure needs the box
+  quiet.
+- **Instrument correction (fleet law).** On the PrismML fork build 10777 the raw
+  `/completion` path answers **500 "The model produced output that does not
+  match the expected Content-only format"** for a greedy `ignore_eos` run, so
+  the honest per-request `timings` for this endpoint must be read off
+  `/v1/chat/completions`. `AGENTS.md` said `/completion`; it now says the chat
+  path.
+
 ## 2026-10-13
 - **frank-archon outage: a kernel knob, not the model.** The 2026-10-12 23:17
   power failure on dankserver reset `/sys/module/ttm/parameters/pages_limit`
@@ -2441,3 +2468,383 @@ every restart since the cutover.
   `~/.harbor/compose.opennotebook.yml` pins the deprecated `-single` image,
   carries no encryption key and injects the whole harbor env — left untouched,
   read-only, as the record of what not to copy.
+
+## 2026-10-18 — frank-tts-engine: the arm A engine becomes deployable (nothing deployed)
+
+- Goal: turn the engine the day's A/B picked into a **repo-owned, boot-persistent,
+  self-healing container** — `frank-tts-engine`, `qwentts.cpp` commit
+  `5916bf7c79dbb4e66fc059cdc507a79a23a28bb4`, resident `tts-server`, 1.7 B base
+  talker Q4_K_M + Q8_0 tokenizer, container port 8880, and **not** a fleet
+  endpoint: the endpoint stays `frank-tts` on 7772. Runbook: [[Frank TTS Engine]].
+- **No `PublishPort` at all, which is the shape the merged A/B states as law.**
+  netavark DNATs published ports only, so a `127.0.0.1:8880` publish is not a path
+  to a peer container — the façade could never have used it (the trap that 502'd
+  hermes) — while being the one LAN-reachable surface of an unauthenticated
+  synthesiser. Both voice containers therefore sit on one committed quadlet
+  network, `frank-tts-engine.network` at **10.89.5.0/24** (the next free /24 after
+  open-notebook's 10.89.4.0/24), and the façade addresses the engine by container
+  name. Diagnostics moved to `podman exec`, including the deployer's health gate
+  (`wait_container_healthy`, not `wait_for_health`: there is no URL to dial).
+- **The boot warmer is a unit hook, not an operator habit.** Cold-voice law: the
+  first request for a registered voice decodes the whole reference to snapshot
+  codec state (6.2–8.0 s, first byte 5 530 ms), later ones restore in 0.5 ms; the
+  registry is memory-only and re-registering does not warm. So
+  `ExecStartPost=-/usr/bin/podman exec frank-tts-engine /app/warm-voices.sh` with
+  `TimeoutStartSec=900`, and the `-` prefix is what stops a failed warm from
+  crash-looping the endpoint under `Restart=always`. It logs `cold=` and `warm=`
+  per voice, so the under-a-second second request is proven on every boot.
+- **Thread law recorded before anyone tunes it away:** no `--threads` exists;
+  `src/backend.h` uses `hardware_concurrency()/2`, so a cpuset pin silently
+  changes the thread count. Nothing pins this container.
+- Image builds from the pinned commit with the **proven** line, verbatim —
+  `GGML_BLAS=OFF` is forced (this host has `libopenblas.so.0`, no dev headers),
+  every GPU backend off, `-j 8`, and no `-DGGML_NATIVE` because ggml's default is
+  `-march=native` for the building host: the image is built where it runs. Base
+  `ubuntu:24.04` pinned by index digest; two stages, because ggml builds shared
+  and the RPATH names the build tree.
+- Weights fetched by `scripts/download-frank-tts-engine-qwentts.sh` with byte and
+  LFS-oid checks (talker 1 219 245 248 B, tokenizer 291 150 624 B); the deployer
+  gates on `--verify-only` rather than pulling 1.4 GiB inside a deploy.
+- Registered in all five places the open-notebook entry just named as law, plus
+  the routing case above the `dankclaw/*.container` glob. New seam
+  `tests/frank_tts_engine.bats` (18 tests): the Quadlet **generator's own output**
+  for the network/publish/boot/warm shape, the entrypoint's argv driven from the
+  tracked env file, the warmer against a stub `tts-server` over a real socket
+  (registration keys, `ref_text` absent, late engine, hung synthesis, name
+  refusal), the fetcher's verifier, and both routing tables.
+- Deliberately NOT done: the deploy (no host touched, no container started, no
+  image built), any homepage card or Prometheus job for the engine — it publishes
+  nothing and exposes no metrics, so there is nothing to probe, which is said out
+  loud in the page rather than papered over. No ICL/`ref_text` work: the packs
+  keep `reference.spk`/`reference.rvq` so it stays a per-voice opt-in.
+
+## 2026-10-18 — frank-tts: the 7772 endpoint gets its deploy wiring, and voice naming is written down
+
+- Stage 2 of the voice stack: the **façade** in front of the engine is now a
+  deployable service too. Nothing deployed, no host touched. Runbook:
+  [[Frank TTS]].
+- **Two attached networks, in a meaningful order.** `dankclaw_default` first — it
+  owns the default route and is where consumers live (open-notebook dials
+  `http://frank-tts:7772/v1` by container name) — then the voice pair's private
+  bridge. `scripts/frank-tts.env`'s `TTS_UPSTREAM` moves from
+  `host.containers.internal:8880` to `http://frank-tts-engine:8880`, which is the
+  actual fix for a shape that could never have worked: a bridge container cannot
+  reach a host-loopback bind, and the engine publishes nothing.
+- **`Wants=` + `After=` on the engine, never `Requires=`:** the façade still
+  carries the `llama-tts-cli` rollback backend, which needs no upstream, so an
+  engine that will not boot must delay this endpoint, not take it down.
+- The façade handler installs the **engine's** quadlet pair as well. Not tidiness:
+  with a referenced `Network=` file absent, the v1 Quadlet generator produces no
+  container unit at all, and `--only frank-tts` has no other way to obtain it. It
+  also `mkdir -p /home/dank/voices` as the deploy user, because rootless podman
+  auto-creates a missing bind source **root-owned** and the endpoint then reports
+  "no voices" instead of an error.
+- **A voice is a lowercase directory name.** `^[a-z0-9][a-z0-9._-]*$`, ≤ 64 chars,
+  no slash/`..`/space. The shape is the intersection of two rules that do not
+  agree: `app.py` would accept mixed case, `tts-server` lowercases names — so a
+  pack named `Narrator1` resolves through the façade and not through the engine,
+  and the boot warmer refuses such a directory loudly. `narrator1/2/3` are
+  load-bearing for open-notebook, and `frank-tts-add-cloned-voice` is the skill
+  that walks the pack → register → warm → prove-a-second-request flow.
+- Registered everywhere the open-notebook entry named as law (planner order puts
+  the engine before the façade, so a warm registry precedes the first synthesis),
+  plus the homepage card — `wip: down` and hidden, because nothing listens on
+  7772 yet.
+- **No Prometheus job, on purpose.** The façade exports no `/metrics`, Prometheus 3
+  refuses HTML/JSON content types (the `comfyui` and `services` probes are
+  documented down for exactly that), and `LlmEndpointDown` is scoped
+  `up{job=~"frank-.*"}` — so a `/health` scrape would page on Signal every few
+  minutes for a healthy endpoint. That is the frank-archon never-green lesson
+  pointed the other way, and it is written in the page instead of being quietly
+  ignored.
+- Tests added to the voice seam: the generator's own rendering of the pair (both
+  attachments, first-network order, one publish, Wants-not-Requires), the
+  env-file upstream checked as a **network join** rather than a string
+  comparison, planner separation and order, the façade handler's steps, the
+  homepage card's gating, and routing that selects both seams for either
+  deployable's paths.
+
+## 2026-10-18 — voice-pack builder: the 10-second source-material gate becomes code
+
+- Third slice of the voice stack (after the façade and the engine decision):
+  `scripts/build-voice-pack.sh` turns a source recording plus a crop offset into
+  a deployable pack — `reference.wav` (24 kHz mono `pcm_s16le`, 18–25 s), the
+  engine's own `reference.spk` (8,192 B) + `reference.rvq` (5,456–6,864 B) made
+  from it, and `manifest.json` provenance. Tracked tunables in
+  `scripts/voice-packs.env`: pack list, per-voice source/offset/duration/pinned
+  source sha256, extractor path and engine commit, artifact arithmetic. New runbook
+  [[Voice Packs]].
+- **The gate is the product.** The project-wide invariant — no voice material
+  from the first 10 s of a sample file — had only ever been a sentence in
+  `scripts/frank-tts.env`. An offset inside it now exits 1 before a directory is
+  created, and the same assertion runs again against the manifest that was just
+  written, next to the recorded sha256, so a pack cannot carry a forbidden crop
+  even if the env file is edited into nonsense. `10` stays a constant in the
+  builder; the env file carries offsets, never the law.
+- **The extractor's contract was read, not guessed:** `qwen-codec` in qwentts.cpp
+  `5916bf7c` takes `--model <codec gguf> --talker <base talker gguf> -i <wav>`
+  with an optional `--device`, has **no `-o`** and names both artifacts next to
+  the input with the extension swapped. So the WAV is staged under its final stem
+  and `reference.wav` — the file the façade gates on — is moved into place
+  **last**, after the artifacts and the manifest: a failed extractor leaves a
+  directory that is not a voice. `--force` retires an existing pack whole to
+  `.AGENTTRASH/` instead of touching bytes; nothing in this script deletes.
+- Sizes are arithmetic, so they are checked: 16 codebooks × 11 bits = 22 B per
+  12.5 Hz frame (`22 × floor(samples/1920)`) and `enc_dim 2048 × f32` = 8,192 B.
+  That makes the **effective crop window 19.84–25 s**, narrower than the WAV
+  law's 18–25 s, and a too-short crop is refused before the extractor runs. An
+  engine bump that changes either number fails the build by design; the bump
+  procedure is in [[Voice Packs]].
+- Verified against reality, not against the model: the pinned `narrator1` crop
+  (98.739–118.636 s of `audiosample.mp3`, sha256 `2299510…`) comes out of a
+  `--dry-run` at 955,378 B / 19.897 s with 5,456 B of `.rvq` planned — byte-for-byte
+  the trial's hand-cut numbers — and all three pinned source digests match the
+  files on disk.
+- Seam: `tests/voice_pack_unit.bats` (13 tests) — refusal inside the forbidden
+  region creates nothing, a legal crop builds the whole pack, `ffprobe` on the
+  generated reference, manifest round-trip through `jq` with a sha that matches
+  the source, re-run-without-`--force` leaves every byte alone, `--force` retires
+  rather than deletes, `--dry-run` needs no extractor, a wrong-sized artifact
+  from a bumped engine cannot publish a voice, and every crop in the tracked pack
+  list clears the invariant. `qwen-codec` is stood in by a stub with the real
+  tool's I/O shape, so no engine, no GPU, no network, no fleet host. Suite green:
+  **416/416** (`./tests/run.sh`, wall 77 s) — 403 before this branch.
+- Deliberately NOT done: no transcript in the manifest (ICL wants a curated
+  `ref_text`; the trial's machine transcripts were wrong, and the engine
+  registers WAV-only voices anyway), no 16 kHz variant (arm A is native 24 kHz),
+  no loudness pass (not in the pack law), and no pack built on the host — the
+  three sources still live on the workstation and the engine GGUFs have not been
+  fetched to `/home/dank/models/Qwen3-TTS-GGUF` yet, so the first real run is a
+  host step.
+
+## 2026-10-18 — voice stack audit: three faults that no gate could see
+
+- The voice stack had never been run end to end — no image built, nothing on
+  7772 — so the whole path was audited as static code against the tools it
+  calls, and three faults came out of it. All three are the same species: a
+  step that **reports success while doing nothing**.
+- **The build would not have happened.** `Containerfile.engine` created its
+  unprivileged user with `adduser`; the pinned ubuntu:24.04 base has no
+  `adduser` at all. Proven in the base on Dankclaw rather than argued from
+  memory: `command -v adduser` prints nothing, and the replacement line
+  `useradd --system --uid 10000 --home-dir /app --shell /usr/sbin/nologin tts`
+  answers `uid=10000(tts) gid=999(tts)`. Its `SYS_UID_MAX` warning is cosmetic
+  and is the price of matching the façade's uid, so the comment says that
+  before someone "fixes" it by dropping `--system`.
+- **The warm pass would not have warmed.** The unit hands its env file to podman
+  via `--env-file`, which performs no shell parsing and takes the literal
+  remainder of the line, while `source` strips one quoting layer. `WARM_TEXT`
+  therefore reached the container with its quotes, the hook interpolated them
+  into the synthesis body, the JSON was invalid, and every voice would log
+  "registered, but the warm synthesis failed" beside an `active` unit. Fixed in
+  the hook — strip exactly one matched pair, only when the inner content also
+  carries a quote or backslash, then JSON-escape — and the seam now reads
+  `scripts/frank-tts-engine.env` **both** ways and asserts the engine gets the
+  same sentence in both shapes. The bug survived the first deploy precisely
+  because every existing test used `source`.
+- **A rebuilt image would not have been rebuilt.** `build_compose_image` skips
+  `podman build` on a matching `cfhash` label, and that hash covered the
+  `Containerfile` alone — so editing `app.py` or `tts-engine-warm.sh` (both
+  `COPY`'d) skipped the build, the deploy reported success, `/health` answered,
+  and the container served old code. Each case arm now names the files its
+  `Containerfile` copies and hashes them with it; comfyui/loki/alloy have no
+  extras, so their labels are byte-unchanged and they do not rebuild here.
+- Tests as behaviour, not as greps: the new seam extracts the real
+  `build_compose_image` from the deployer and drives it against a stub `podman`
+  that replays per-image label state, asserting the observable question — did
+  the deploy ask podman to build, or did it skip? — through build, skip,
+  engine-hook-edit-rebuilds-engine-only, and `app.py`-rebuilds-the-façade.
+  Reverting `scripts/deploy-remote.sh` turns it red at the warm-hook step, which
+  is the fault being prevented. Suite green: **443/443** (`./tests/run.sh`,
+  wall 110 s); each fix commit was left green on its own so the branch bisects.
+- Docs carry the lessons where an operator will hit them: a **Locally built
+  images** section in [[deployment]], two new troubleshooting lines in
+  [[Frank TTS Engine]] (all-voices-cold = quoted `WARM_TEXT`; façade 502 beside
+  200 = model loaded ≠ voices registered), and `Voice Packs.md` step 4
+  corrected — the warm hook re-registers **every** pack on every run, because
+  the engine replaces a name it already holds (`tools/tts-server.cpp:148` at
+  the pinned commit: *"Re-registering a name replaces the previous entry."*),
+  so a restart is what an engine bump needs and not what a rebuilt pack needs.
+- Opened as PR **#14** against `main`. Deliberately NOT done: no deploy (the
+  first `--service frank-tts-engine` run is a ~10-minute recursive source clone
+  and a new unit on a host that serves people — Frank's call), no voice pack
+  built on the host, no Playwright run (this branch publishes no host port and
+  touches no vhost), and Gitea **#2** phase 1 stays open until 7772 answers.
+
+## 2026-10-18 — frank-tts-engine deployed: it builds, it serves, and the warm hook died on the kernel's argument cap
+
+- Merged as **#14** (`747c665`) and deployed `--service frank-tts-engine`. The
+  payload took 18 s to fetch for the 1.4 GiB pair (byte count + Hub LFS sha256,
+  `--verify-only` OK), and the image built clean — the first real proof of the
+  `useradd` fix: `STEP 3/13: RUN useradd --system --uid 10000 …` passed with only
+  the documented cosmetic `SYS_UID_MAX` warning, and the unit was `healthy` after
+  31 s.
+- Then the deploy reported `0 voice(s) warm`:
+  `/app/warm-voices.sh: line 152: /usr/bin/curl: Argument list too long`. The hook
+  handed the registration body to curl as ONE argument; the kernel caps a single
+  argument at 131,072 bytes (`MAX_ARG_STRLEN`) and a shipped 955 KB
+  `reference.wav` base64's to about 1.27 MB, so curl never executed and the hook
+  logged that as "HTTP no response". Fourth silent fault of the voice stack, same
+  species as the other three: `/health` stayed green throughout.
+- Fix: the body goes to a `mktemp` file and curl gets `@file`. The regression test
+  is the honest shape — the seam's stub engine is a real listener, `curl` is the
+  real binary, the fixture pack is 300 KB — so it fails with the same kernel error
+  the host produced (proved red first, green after). Every shipped pack sits well
+  over the ~96 KB cliff, so no small fixture could ever have seen this.
+- Live proof on the deployed container with the three real packs:
+  `narrator1 cold=1175ms warm=1874ms`, `narrator2 1373/1892`, `narrator3
+  1816/1487`, exit 0, 15.2 s for the whole pass.
+- **A trial law did not survive deployment.** Against an empty registry —
+  register only, then time — the FIRST synthesis of a freshly registered voice
+  cost **1 883 ms**, the next two **1 283** and **1 226 ms**; a ~110-word request
+  cost **9.4 s** then **9.8 s**. The trial's 6.2–8.0 s cold / 0.5 ms restore
+  ladder, which the warmer's own header repeated, is retired: warming buys
+  registration — mandatory, because the registry is memory-only — plus about
+  **0.6 s**. Corrected in [[Frank TTS Engine]] law 1 and its troubleshooting
+  table, in [[Local TTS and Voice Cloning]], and in [[Voice Packs]].
+- Host state, honestly: the engine is `active` with three voices warm, but the hook
+  fix is not in the image yet, so the next restart re-breaks it until this branch
+  is merged and re-deployed. `frank-tts` (the 7772 façade) is still undeployed.
+- Deliberately NOT done in this window: the `frank-tts` deploy, any Prometheus
+  probe for the voice pair (neither container exposes `/metrics`; the blackbox
+  question is still open), and the podcast render — open-notebook is on `main` but
+  not installed.
+
+- Sweep afterwards: the retired ladder still lived in six places the first pass
+  missed — both quadlet files, `scripts/frank-tts-engine.env`,
+  `scripts/frank-tts.env`, the [[Frank TTS]] troubleshooting row, the research
+  brief's consequences paragraph, and one test comment. All re-keyed to the
+  measured claim: about **0.6 s**, and the 400-for-every-name reason the pages
+  should have led with. The trial entry above is left as written — a dated worklog
+  entry is a record — and this line is the correction that points at it.
+
+## 2026-10-18 — 7772 is live and the harness speaks through it
+
+- Merged **#15** (`0315a62`, the warmer's argument-cap fix) and **#16**
+  (`d2ce669`, the comment sweep), then deployed both voice services in order:
+  `--service frank-tts-engine` (image rebuilt from the fixed warmer, unit
+  `active`, zero drop-ins, warm pass in the unit's own start — `narrator1
+  cold=1542ms warm=1709ms`, `narrator2 1329/1405`, `narrator3 1451/1394`, `3
+  voice(s) registered and warm`) and `--service frank-tts`. The Playwright gate
+  ran at the end of each deploy: 33/33 twice.
+- Deployed-state proof from a LAN client: `/health` → `omni-http` with all three
+  voices; the same sentence in `narrator1` and `narrator2` came back with
+  **different sha256** and different RMS (4.24 s, 24 kHz mono PCM16), so the name
+  actually selects a voice. Engine-side ledger for the harness request:
+  `TTFA 67.5 ms`, `Total 2158.8 ms`, `audio 3.76 s, RTF 0.574`.
+- **The harness `speech` role moved off Kokoro**: `config.yml`
+  `modelRoles.speech: frank-tts (dankclaw)/frank-tts`. No voice key moves with it.
+  The bundle is unambiguous: the speech device forwards the call's `voice_id` and
+  nothing else, `tts.localVoice` belongs to the local backend (it is what answered
+  in the control test), and `speech.voice` is the TUI's speak-aloud enum.
+- Two harness laws learned by breaking it first (both now on [[Frank TTS]]): an
+  explicit speech role has **no fallback candidate**, so a dead endpoint errors
+  instead of degrading; and `models.yml` loads at process start while
+  `config.yml` is read live, so a session older than the `frank-tts` row fails
+  exactly like a dead endpoint. Fresh-process proof in the same minute:
+  `Saved 180524 bytes (model=frank-tts (dankclaw)/frank-tts, voice=narrator1)`
+  with the matching façade log line `speech voice=narrator1 format=wav chars=51
+  -> 180524 bytes`. This window's own session is that stale case and knows it.
+- Status sweep, because six pages still said the endpoint did not exist: both
+  vault descriptions, the two `index.md` bullets, the Open Notebook blocker (the
+  voice leg works; open-notebook itself is what is missing), the engine page's
+  "Deploy order — nothing below has been run" is now a **Deploy record**, and the
+  homepage card lost `wip: down` so the admin panel probes 7772 for real.
+- Corrected the same evening, by breaking it in a restarted session: a harness
+  call that names no voice reaches 7772 with **no `voice` key at all** — `400
+  unknown voice None; available voices: narrator1, narrator2, narrator3` —
+  because no setting feeds one. The earlier `Saved 180524 bytes
+  (voice=narrator1)` succeeded only because that run was *told* to pass
+  `voice_id`. The endpoint therefore grew `DEFAULT_VOICE` (its own PR): a
+  voice-less request speaks the declared pack and the journal line carries
+  `(default)`, while an unknown name still 400s with the list. Reverting the role
+  to Kokoro is one key, not two, and `speech.voice: narrator1` — briefly recorded
+  above as wiring — went back to `am_fenrir`: that key is the vocalizer's Kokoro
+  enum, so a pack name there breaks speak-aloud and does nothing for synthesis.
+
+## 2026-10-18 — the default voice shipped: a harness voiceover needs no voice
+
+- Merged **#17** (`b590695`) and **#18** (`7889a68`), then deployed both affected
+  services in one dispatch — `--service frank-tts --service homepage`, 159 s,
+  Playwright gate 33/33. The shim image rebuilt with the new handler; the
+  homepage checker took the card on its next timer tick: `frank-tts → up`,
+  probed for real rather than gated.
+- The call that had failed is the one that proves the fix. Same device, same
+  restarted session, **no** `voice_id`: `Saved 430124 bytes (model=frank-tts
+  (dankclaw)/frank-tts, voice=default, codec=wav)`. The façade journal says what
+  actually spoke — `speech voice=narrator1 (default) format=wav chars=148 ->
+  430124 bytes` — with the engine's ledger behind it (`audio 8.96 s, RTF 0.551`).
+  The harness prints `voice=default` because it never had a name to print; the
+  voice that answered is the operator's line in `scripts/frank-tts.env`, and the
+  journal keeps them distinguishable forever after.
+- The page gained a **Default voice** row in its contract table and
+  [[#Naming a voice]] now states that a call naming nothing is the harness's
+  normal shape, not a client bug — the misconception that produced the 400 in
+  the first place.
+
+## 2026-10-18 — OpenWebUI "voice narrator1 not found": the rejector is in the browser
+
+- Frank's toast — `Error: Voice "narrator1" not found. Should be one of:
+  af_heart, …, bm_fable` — looked like frank-tts refusing the name. It is
+  not: that 29-name enum is the voice pack of **Kokoro.js running in the
+  page**, and OpenWebUI 0.11.4 ships that implementation in its own front
+  end (frozen table `{af_heart:{name:"Heart",…}}`, `_validate_voice`, model
+  `onnx-community/Kokoro-82M-v1.0-ONNX`, a personal *Kokoro.js dtype*
+  setting, engine values `""`/`browser-kokoro`).
+- Instruments that separated the two paths, in order: the admin config DB is
+  correct (`audio.tts.engine=openai`,
+  `audio.tts.openai.api_base_url=http://host.containers.internal:7772/v1`,
+  `model=frank-tts`, `voice=narrator1`, `split_on=punctuation`); from inside
+  the container the exact OpenWebUI body
+  (`{"model":"frank-tts","input":…,"voice":"narrator1","response_format":"mp3","speed":1.0}`)
+  returns **200 `audio/mpeg` 7,629 B**; and `podman logs open-webui` holds
+  **zero** `audio/speech` requests for the failing click. A server-path
+  failure leaves a log line and a frank-tts error — a `browser-kokoro`
+  failure leaves neither. No container env carries an `AUDIO_*`/`TTS`
+  variable and no `user.settings` row (all four users) carries an audio
+  override, so the engine choice is per-browser storage, not fleet state.
+- Fix is a UI click, not a deploy: Settings → Audio → TTS Engine →
+  **Default** hands synthesis back to frank-tts and the cloned voices;
+  choosing `af_heart` keeps in-browser Kokoro, which cannot clone (fixed
+  pack). Recorded on [[OpenWebUI]] under *Text-to-speech (frank-tts)*;
+  suite green 384/384 (wall 65.9 s).
+- Also in the window: **PR #22 merged** (`0c7fe8b`, `dank/command-center`) so
+  `agent/extensions/dankvoice.ts` landed on the auto-load path — proven in a
+  plain `omp` session with no flags: `/say merged build check` → 1.20 s WAV
+  to the player, temp dir cleaned; the audible pass through the default
+  `pw-play` detection confirmed by Frank. Sessions open before the merge need
+  a restart to pick the command up.
+
+## 2026-10-18 — frank-zealot: 2 × 262,144 over unquantized f16 KV
+
+- Frank's instruction: **"shift frank-zealot to 2 parallels of unquantized
+  kv"**. The env delta is four lines: `CTX_SIZE=524288`, `PARALLEL=2`,
+  `CACHE_TYPE_K=f16`, `CACHE_TYPE_V=f16`. Everything else holds — batch
+  **4096** / ubatch **2048**, `--flash-attn on`, `--jinja`, `--metrics`,
+  `--presence-penalty 1.0`, `SPEC_TYPE=none`, the Q8_0 mmproj, port 7771, and
+  the per-slot window **262,144** — `models.yml` `contextWindow` untouched.
+- **Why the pool had to halve.** Exact KV bills **32,768 B/token** (8
+  full-attention layers × 4 KV heads × 256 dim × 2 B × 2 caches), so the old
+  786,432 pool asks **24,576 MiB** against the **24,123 MiB** the driver leaves
+  addressable — impossible, not tight. 524,288 positions ⇒ **16,384 MiB** and
+  exactly two windows of 262,144.
+- Arithmetic correction to the repo's long-standing figure: "the f16 pair would
+  need **26,112 MiB**" doubled the q8_0 number *including* its 1/32 scale
+  overhead — q8_0 is 17,408 B/token (1.0625 B/element), so f16/q8_0 is
+  **1.882×**, not 2×, and exact f16 over 786,432 is **24,576 MiB**. The
+  conclusion stands (three f16 windows cannot boot this card); the number was
+  wrong.
+- The cost: **concurrency 3 → 2 conversations**, and MTP is now **doubly** out.
+  The 13:16 measurement still says off, and exact KV adds a second reason — the
+  draft context bills its own f16 KV over the WHOLE pool (**4,096 B/position**
+  × 524,288 = **2,048 MiB**) on a trunk projecting ~21,200 used.
+- **Projection, explicitly not a measurement:** ~**21,200 MiB** used /
+  ~**2,920 free**, derived from the 13:19 ledger's 17,922 used because only two
+  terms move — the KV pool (**+3,328**) and one recurrent-state cell
+  (**−50.25**, 3 cells → 2). The measured boot ledger and the decode/prefill
+  re-measure land in the follow-up commit, after the first f16 boot.
+- New gate in `tests/frank_zealot_unit.bats`: dtype × pool plus the measured
+  non-KV terms must fit **24,123 MiB** with **≥ 1 GiB** of slack — and the same
+  gate proves it refuses the impossible arm (**f16 at 786,432**), not merely
+  passes the shipped one. Runbook re-keyed to the new shape:
+  `LLM/frank-zealot-llama-prism-bonsai9-mtp.md`.

shared/homepage/img/apps/mono-ft.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 96 96"><polygon points="48,6 86,27 86,69 48,90 10,69 10,27" fill="#101a12" stroke="#7ee787" stroke-width="3"/><text x="48" y="60" font-family="monospace" font-size="30" font-weight="bold" fill="#7ee787" text-anchor="middle">FT</text></svg>

shared/homepage/services.json

@@ -536,5 +536,18 @@
     "wip": false,
     "showLink": true,
     "art": "/img/apps/mono-cu.svg"
+  },
+  {
+    "name": "frank-tts",
+    "category": "admin",
+    "section": "AI",
+    "description": "The fleet's cloned-voice speech endpoint: POST /v1/audio/speech with voice=<name>, audio back in that voice. Published on 7772; the engine behind it (frank-tts-engine) is unpublished on purpose. It is also the harness speech role.",
+    "url": "",
+    "docs": "",
+    "probe": "127.0.0.1:7772",
+    "method": "http",
+    "wip": false,
+    "showLink": false,
+    "art": "/img/apps/mono-ft.svg"
   }
 ]

tests/frank_tts_engine.bats

@@ -0,0 +1,985 @@
+#!/usr/bin/env bats
+# Seam: frank-tts-engine — the arm A TTS engine (qwentts.cpp `tts-server`) that
+# sits behind frank-tts. What is pinned here is the shape the fleet depends on,
+# observed through the tools that act on it: the Quadlet generator's own output,
+# the image entrypoint driven with a stub binary, the boot warmer driven against
+# a stub engine over a real socket, and the fetcher's own verifier.
+#
+# Nothing in this file synthesizes audio, builds an image, starts a container or
+# touches a fleet host. The engine's real behaviour (TTFA, RTF, the cold-voice
+# cost) was measured on Dankclaw on 2026-10-18 and is documented in
+# serverAppConfigs-docs/Dankclaw/Frank TTS Engine.md; a test that re-derived it
+# would need the weights, the CPU and the time the endpoint is meant to serve.
+#
+# What this seam refuses to assert, on purpose: any comparison between streamed
+# (`pcm`) and buffered (`wav`) audio. At the same seed those two paths differ in
+# 92.2 % of samples (-41.6 dB RMS), so a fixture that pinned one against the
+# other would be a bug waiting to be "fixed".
+
+load helpers
+
+UNIT="$REPO_ROOT/dankclaw/voiceservice/quadlet/frank-tts-engine.container"
+NETF="$REPO_ROOT/dankclaw/voiceservice/quadlet/frank-tts-engine.network"
+# The façade this engine serves: its wiring is tested here because the bridge
+# both units attach to is what makes the pair one deployable shape.
+FACADE="$REPO_ROOT/dankclaw/voiceservice/quadlet/frank-tts.container"
+FACADE_ENV="$REPO_ROOT/scripts/frank-tts.env"
+CF="$REPO_ROOT/dankclaw/voiceservice/Containerfile.engine"
+START="$REPO_ROOT/dankclaw/voiceservice/tts-engine-start.sh"
+ENVF="$REPO_ROOT/scripts/frank-tts-engine.env"
+WARM="$REPO_ROOT/dankclaw/voiceservice/tts-engine-warm.sh"
+FETCH="$REPO_ROOT/scripts/download-frank-tts-engine-qwentts.sh"
+PLANNER="$REPO_ROOT/scripts/deploy-plan.py"
+REMOTE="$REPO_ROOT/scripts/deploy-remote.sh"
+
+# The decided artifacts, exactly as the 2026-10-18 Hub census recorded them.
+TALKER="qwen-talker-1.7b-base-Q4_K_M.gguf"
+TALKER_BYTES=1219245248
+TALKER_SHA="ea393ebaf2167ea23ce9fc18b093822851358a950d7075cd47ab4f6ce23e887d"
+CODEC="qwen-tokenizer-12hz-Q8_0.gguf"
+CODEC_BYTES=291150624
+CODEC_SHA="1883beeed99348fc35e23dd225e9082f93f6f8c109330a33d935baa8acdbfd94"
+
+setup() {
+    TEST_TMP="$(mktemp -d)"
+    PIDS="$TEST_TMP/pids"
+    : > "$PIDS"
+    : > "$TEST_TMP/journal.jsonl"
+
+    # One real pack, and one directory that LOOKS like a pack but has no
+    # reference.wav so must never be offered as a voice. A third case — a pack
+    # whose name the two halves of the voice stack would resolve differently —
+    # is created only by the test that asserts on it, because every other run
+    # of the warmer has to be able to report success.
+    VOICES="$TEST_TMP/voices"
+    mkdir -p "$VOICES/narrator1" "$VOICES/justamanifest"
+    python3 -c 'import sys; sys.stdout.buffer.write(b"RIFF" + bytes(range(128)) * 2)' \
+        > "$VOICES/narrator1/reference.wav"
+    printf 'a manifest is not a voice\n' > "$VOICES/justamanifest/manifest.json"
+}
+
+teardown() {
+    while IFS= read -r pid; do
+        [ -n "$pid" ] && kill "$pid" 2>/dev/null || true
+    done < "$PIDS"
+    wait 2>/dev/null || true
+    rm -rf "$TEST_TMP"
+}
+
+# write_engine_stub — a stand-in for tts-server's HTTP surface, route for
+# route: GET /health, GET /v1/models, POST /v1/audio/voices, POST
+# /v1/audio/speech, and a bare 404 for anything else (that last part is the
+# point of the stub: a warmer dialing a route the engine does not have must
+# fail here, not in production). Every request is appended to $STUB_JOURNAL in
+# the order it arrived, with the registration reduced to its key set, its name
+# and the sha256 of the decoded wav — so "exactly which bytes were registered"
+# is observable without shipping a 1 MB fixture around.
+write_engine_stub() {
+    cat > "$TEST_TMP/stub_engine.py" <<'PY'
+import base64, hashlib, json, os, time
+from http.server import BaseHTTPRequestHandler, HTTPServer
+
+JOURNAL = os.environ["STUB_JOURNAL"]
+HANG = float(os.environ.get("STUB_HANG_SPEECH") or 0)
+
+
+class Stub(BaseHTTPRequestHandler):
+    def _record(self, entry):
+        with open(JOURNAL, "a") as fh:
+            fh.write(json.dumps(entry) + "\n")
+
+    def _reply(self, status, body, ctype="application/json"):
+        self.send_response(status)
+        self.send_header("content-type", ctype)
+        self.send_header("content-length", str(len(body)))
+        self.end_headers()
+        self.wfile.write(body)
+
+    def do_GET(self):
+        self._record({"method": "GET", "path": self.path})
+        if self.path == "/health":
+            self._reply(200, b'{"status":"ok"}')
+        elif self.path == "/v1/models":
+            self._reply(200, b'{"object":"list","data":[{"id":"frank-tts-engine"}]}')
+        else:
+            self._reply(404, b'{"detail":"not found"}')
+
+    def do_POST(self):
+        length = int(self.headers.get("content-length") or 0)
+        raw = self.rfile.read(length) or b"{}"
+        try:
+            body = json.loads(raw)
+        except ValueError:
+            self._record({"method": "POST", "path": self.path, "invalid_json": True})
+            self._reply(400, b'{"error":{"message":"request body is not valid JSON"}}')
+            return
+        if self.path == "/v1/audio/voices":
+            wav = body.get("wav_b64") or ""
+            try:
+                digest = hashlib.sha256(base64.b64decode(wav)).hexdigest()
+            except Exception:
+                digest = "undecodable"
+            self._record({"method": "POST", "path": self.path,
+                          "keys": sorted(body), "name": body.get("name"),
+                          "wav_sha256": digest, "wav_b64_len": len(wav),
+                          "has_ref_text": "ref_text" in body})
+            self._reply(200, json.dumps({"name": body.get("name"),
+                                         "status": "registered"}).encode())
+        elif self.path == "/v1/audio/speech":
+            self._record({"method": "POST", "path": self.path,
+                          "voice": body.get("voice"),
+                          "response_format": body.get("response_format"),
+                          "input": body.get("input")})
+            # STUB_HANG_SPEECH stands in for an engine that takes the request
+            # and never answers it: the branch the warmer's ceiling guards.
+            if HANG:
+                time.sleep(HANG)
+            audio = b"RIFF" + b"\x00" * 64
+            self._reply(200, audio, "audio/wav")
+        else:
+            self._record({"method": "POST", "path": self.path})
+            self._reply(404, b'{"detail":"not found"}')
+
+    def log_message(self, *args):
+        pass
+
+
+server = HTTPServer(("127.0.0.1", int(os.environ.get("STUB_BOUND_PORT") or 0)), Stub)
+print(server.server_address[1], flush=True)
+server.serve_forever()
+PY
+}
+
+start_engine_stub() {
+    # start_engine_stub [port] — with a port the stub binds that exact one,
+    # which is what lets a test have a listener appear on an address the warmer
+    # is already dialing.
+    write_engine_stub
+    : > "$TEST_TMP/stub.log"
+    STUB_JOURNAL="$TEST_TMP/journal.jsonl" STUB_BOUND_PORT="${1:-}" \
+        STUB_HANG_SPEECH="${STUB_HANG_SPEECH:-}" \
+        python3 "$TEST_TMP/stub_engine.py" > "$TEST_TMP/stub.log" 2>&1 &
+    echo "$!" >> "$PIDS"
+    local waited=0
+    while [ "$waited" -lt 200 ]; do
+        STUB_PORT="$(head -n1 "$TEST_TMP/stub.log")"
+        [ -n "$STUB_PORT" ] && return 0
+        sleep 0.05
+        waited=$((waited + 1))
+    done
+    echo "the stub engine never bound a port:"
+    cat "$TEST_TMP/stub.log"
+    return 1
+}
+
+# quadlet_generator — locate the Quadlet generator the target host also has.
+# podman moved it over the releases the fleet runs, so try every known home and
+# skip the test if this box has none: the assertions below are only meaningful
+# against a real generator, not a guess at one.
+quadlet_generator() {
+    local candidate
+    for candidate in \
+        /usr/lib/systemd/system-generators/podman-system-generator \
+        /usr/libexec/podman/quadlet-generator \
+        /usr/lib/podman/quadlet-generator \
+        /usr/lib/podman/quadlet; do
+        [ -x "$candidate" ] && { printf '%s' "$candidate"; return 0; }
+    done
+    return 1
+}
+
+# render_units — run the generator in a throwaway HOME over a copy of the voice
+# stack's source files and print everything it emits. Both units are rendered
+# together on purpose: the façade references the engine's .network, and a
+# referenced file that is not in the directory makes the generator drop that
+# container unit outright — which is the failure this seam must be able to see.
+# --dryrun prints instead of writing, so this neither contacts the podman daemon
+# nor creates a network.
+render_units() {
+    local gen home
+    gen="$(quadlet_generator)" || { echo "no Quadlet generator on this box"; return 1; }
+    home="$TEST_TMP/fakehome"
+    mkdir -p "$home/.config/containers/systemd"
+    cp "$NETF" "$UNIT" "$FACADE" "$home/.config/containers/systemd/"
+    HOME="$home" "$gen" --user --dryrun > "$TEST_TMP/generated.txt" 2> "$TEST_TMP/generated.err"
+    cat "$TEST_TMP/generated.txt"
+}
+
+# unit_block <name> — one unit's block from the last render_units output. The
+# end of the block is the next `---` marker: two units are rendered now, and a
+# slice that ran to the end of the output would read the façade's RestartSec
+# into the engine's assertions, which is exactly how a generator test starts
+# asserting the wrong container.
+unit_block() {
+    awk -v u="$1" 'index($0, "---" u "---") == 1 { f = 1; next }
+                  /^---/ { f = 0 }
+                  f' "$TEST_TMP/generated.txt"
+}
+
+# free_port — an address with nothing bound to it, for the tests that need the
+# warmer to be dialing before a listener exists.
+free_port() {
+    python3 -c 'import socket
+s = socket.socket()
+s.bind(("127.0.0.1", 0))
+print(s.getsockname()[1])
+s.close()'
+}
+
+@test "the voice bridge is the next free pinned subnet and no two committed networks share one" {
+    # Two networks claiming one subnet is a boot-time collision that shows up as
+    # the later container failing to start, on the host, weeks from now. The
+    # registry lives in the network files' comments, so the subnets themselves
+    # are the only honest thing to compare.
+    mine="$(sed -nE 's/^Subnet=([0-9./]+)$/\1/p' "$NETF")"
+    [ "$mine" = "10.89.5.0/24" ] || { echo "expected 10.89.5.0/24, the next free /24, got: $mine"; false; }
+    run grep -hoE '^Subnet=[0-9./]+' "$REPO_ROOT"/dankclaw/*/quadlet/*.network "$REPO_ROOT"/dankserver/*/quadlet/*.network
+    dupes="$(printf '%s\n' "$output" | sort | uniq -d)"
+    [ -z "$dupes" ] || { echo "subnets claimed by more than one network file: $dupes"; false; }
+    printf '%s\n' "$output" | grep -qxF "Subnet=$mine"
+}
+
+@test "the Quadlet generator renders the engine on its private bridge, publishing nothing" {
+    rendered="$(render_units)" || { echo "$rendered"; skip "no Quadlet generator here"; }
+    line="$(printf '%s\n' "$rendered" | grep -E '^ExecStart=/usr/bin/podman run .*--name frank-tts-engine ')"
+    [ -n "$line" ] || { printf '%s\n' "$rendered"; false; }
+
+    # The data path: container DNS on the network the engine owns. One network
+    # and nothing else attached — the façade joins this one rather than the
+    # engine moving onto the fleet-wide bridge.
+    printf '%s' "$line" | grep -qE -- '--network systemd-frank-tts-engine( |$)'
+    [ "$(printf '%s' "$line" | grep -oE -- '--network [^ ]+' | wc -l)" = "1" ]
+
+    # NO publish of any kind, not even 127.0.0.1:8880. netavark DNATs published
+    # ports only, so a host-loopback publish is not a path to a peer container —
+    # the façade could never have used it (the trap that 502'd hermes), and it
+    # would be the one LAN-reachable surface of an unauthenticated synthesiser.
+    ! printf '%s' "$line" | grep -qE -- '--publish'
+
+    # Repo-owned config: the tracked env file, the read-only weights mount, the
+    # read-only voice packs the in-container warmer reads, and a health probe
+    # that survives the generator's CMD-SHELL wrapping because the image ships
+    # curl.
+    printf '%s' "$line" | grep -qF -- '--env-file /home/dank/serverAppConfigs/scripts/frank-tts-engine.env'
+    printf '%s' "$line" | grep -qF -- '-v /home/dank/models/Qwen3-TTS-GGUF:/models:ro'
+    printf '%s' "$line" | grep -qF -- '-v /home/dank/voices:/voices:ro'
+    printf '%s' "$line" | grep -qF -- '--health-cmd'
+    printf '%s' "$line" | grep -qF 'curl'
+
+
+    # Boot persistence and self-healing, as the generator actually emits them —
+    # and the warm hook: ExecStartPost must carry the `-` prefix, because
+    # Restart=always plus a failing warmer is a crash loop on the endpoint.
+    unit="$(unit_block frank-tts-engine.service)"
+    printf '%s' "$unit" | grep -qE '^Restart=always$'
+    restart_sec="$(printf '%s' "$unit" | sed -nE 's/^RestartSec=([0-9]+)s?$/\1/p')"
+    [ -n "$restart_sec" ] && [ "$restart_sec" -le 30 ]
+    printf '%s' "$unit" | grep -qE '^WantedBy=default\.target$'
+    # The warm hook is an exec, because there is no host-visible address to run
+    # a host script against (see the publish assertions above).
+    printf '%s' "$unit" | grep -qE '^ExecStartPost=-/usr/bin/podman exec frank-tts-engine /app/warm-voices\.sh$'
+    # Warming a library is serialised: it must not fit inside the default 90 s.
+    start_deadline="$(printf '%s' "$unit" | sed -nE 's/^TimeoutStartSec=([0-9]+)$/\1/p')"
+    [ -n "$start_deadline" ] && [ "$start_deadline" -gt 90 ]
+}
+
+@test "the generator renders the bridge creation command with the pinned subnet" {
+    rendered="$(render_units)" || { echo "$rendered"; skip "no Quadlet generator here"; }
+    net="$(unit_block frank-tts-engine-network.service)"
+    printf '%s' "$net" | grep -qE '^ExecStart=/usr/bin/podman network create --ignore --driver bridge --subnet 10\.89\.5\.0/24 --gateway 10\.89\.5\.1 systemd-frank-tts-engine$'
+    # The container unit must be tied to the network unit, not merely mention it:
+    # a referenced .network that the generator cannot find kills the container
+    # unit outright, and an untied one starts the container before the bridge.
+    unit="$(unit_block frank-tts-engine.service)"
+    printf '%s' "$unit" | grep -qE '^Requires=frank-tts-engine-network\.service$'
+    printf '%s' "$unit" | grep -qE '^After=frank-tts-engine-network\.service$'
+}
+
+@test "the entrypoint turns the tracked env file into the engine's own flags" {
+    # Not a grep of the env file: source it the way podman's --env-file feeds
+    # it to the container, then require the stub binary to be handed the flags
+    # those values mean. A key the entrypoint forgot to translate shows up here
+    # as a missing argument, which is what "the knob does nothing" looks like.
+    cat > "$TEST_TMP/fake-tts-server" <<'FAKE'
+#!/usr/bin/env bash
+printf '%s\n' "$@" > "$ARGS_FILE"
+FAKE
+    chmod +x "$TEST_TMP/fake-tts-server"
+    mkdir -p "$TEST_TMP/models"
+    : > "$TEST_TMP/models/$TALKER"
+    : > "$TEST_TMP/models/$CODEC"
+
+    set -a
+    # shellcheck disable=SC1090
+    source "$ENVF"
+    set +a
+    # The env file names CONTAINER paths; the stub stands in for the mount.
+    export QWENTTS_MODEL="$TEST_TMP/models/$TALKER"
+    export QWENTTS_CODEC="$TEST_TMP/models/$CODEC"
+    export QWENTTS_BIN="$TEST_TMP/fake-tts-server"
+    export ARGS_FILE="$TEST_TMP/argv.txt"
+
+    run bash "$START"
+    [ "$status" -eq 0 ] || { echo "$output"; false; }
+    argv() { awk -v flag="$1" 'p { print; exit } $0 == flag { p = 1 }' "$ARGS_FILE"; }
+    [ "$(argv --model)" = "$TEST_TMP/models/$TALKER" ]
+    [ "$(argv --codec)" = "$TEST_TMP/models/$CODEC" ]
+    [ "$(argv --alias)" = "frank-tts-engine" ]
+    # 0.0.0.0 is the one value that makes the container reachable at all from
+    # the bridge; tts-server's own default (127.0.0.1) is unreachable in a netns.
+    [ "$(argv --host)" = "0.0.0.0" ]
+    [ "$(argv --port)" = "8880" ]
+    [ "$(argv --lang)" = "auto" ]
+    [ "$(argv --max-batch)" = "1" ]
+    # The two flags that must never appear: there is no thread count to set (it
+    # comes from hardware_concurrency()/2), and naming a device on an image with
+    # every GPU backend compiled out is only a new way to be wrong.
+    ! grep -qx -- '--device' "$ARGS_FILE"
+    ! grep -qE -- '^--?t$|^--threads$' "$ARGS_FILE"
+}
+
+@test "missing weights are a refusal that names the fetcher, before the port is bound" {
+    cat > "$TEST_TMP/fake-tts-server" <<'FAKE'
+#!/usr/bin/env bash
+echo "the engine binary must not run when its weights are absent" > "$RAN_FILE"
+FAKE
+    chmod +x "$TEST_TMP/fake-tts-server"
+    export RAN_FILE="$TEST_TMP/ran.txt"
+    export QWENTTS_MODEL="$TEST_TMP/nope/$TALKER"
+    export QWENTTS_CODEC="$TEST_TMP/nope/$CODEC"
+    export QWENTTS_BIN="$TEST_TMP/fake-tts-server"
+    run bash "$START"
+    [ "$status" -eq 1 ] || { echo "$output"; false; }
+    [ ! -e "$RAN_FILE" ] || { echo "the engine was started without its weights"; false; }
+    [[ "$output" == *"$TEST_TMP/nope/$TALKER"* ]] || { echo "$output"; false; }
+    [[ "$output" == *"download-frank-tts-engine-qwentts.sh"* ]]
+}
+
+@test "the boot warmer registers each pack from its reference.wav, embedding-only" {
+    start_engine_stub
+    run env ENGINE_URL="http://127.0.0.1:$STUB_PORT" VOICES_DIR="$VOICES" \
+        bash "$WARM"
+    [ "$status" -eq 0 ] || { echo "$output"; false; }
+    [[ "$output" == *"voice narrator1 cold="*"ms warm="*"ms"* ]] || { echo "$output"; false; }
+
+    # The registration is the whole product: name + wav_b64, and NOTHING else.
+    # ref_text present would flip the voice into in-context-learning mode (the
+    # slower voice) — so its absence is the shipped-default assertion.
+    python3 - "$TEST_TMP/journal.jsonl" "$VOICES/narrator1/reference.wav" <<'PY'
+import hashlib, json, sys
+entries = [json.loads(l) for l in open(sys.argv[1])]
+regs = [e for e in entries if e["path"] == "/v1/audio/voices"]
+assert len(regs) == 1, entries
+reg = regs[0]
+assert reg["name"] == "narrator1", reg
+assert reg["keys"] == ["name", "wav_b64"], reg
+assert reg["has_ref_text"] is False, reg
+want = hashlib.sha256(open(sys.argv[2], "rb").read()).hexdigest()
+assert reg["wav_sha256"] == want, (reg, want)
+PY
+
+    # Two speech calls for the one voice: the cold pass that creates the codec
+    # snapshot, then the warm pass whose number is the fleet's real experience.
+    # Both ask for `wav`, which is what frank-tts asks for too.
+    python3 - "$TEST_TMP/journal.jsonl" <<'PY'
+import json, sys
+entries = [json.loads(l) for l in open(sys.argv[1])]
+paths = [e["path"] for e in entries]
+assert paths[0] == "/health", paths
+assert paths[1] == "/v1/audio/voices", paths
+speech = [e for e in entries if e["path"] == "/v1/audio/speech"]
+assert len(speech) == 2, entries
+assert {s["voice"] for s in speech} == {"narrator1"}, speech
+assert {s["response_format"] for s in speech} == {"wav"}, speech
+PY
+}
+
+@test "a reference clip too big for one argument still registers" {
+    # The kernel caps a SINGLE command-line string at 32 pages = 131,072 bytes
+    # (MAX_ARG_STRLEN), and a shipped reference clip base64's to about 1.27 MB —
+    # so a warmer that hands the registration body to curl as an argument dies
+    # before curl runs. That is exactly what the first real boot of 2026-10-18
+    # hit with the real packs: `/usr/bin/curl: Argument list too long`, then the
+    # misleading "registration failed (HTTP no response)" for all three voices.
+    # The stub engine is a real listener and curl is the real binary, so this
+    # test fails for the same kernel reason the host did.
+    start_engine_stub
+    local big="$TEST_TMP/bigvoices/bigvoice"
+    mkdir -p "$big"
+    head -c 300000 /dev/zero | tr '\0' 'A' > "$big/reference.wav"
+
+    run env ENGINE_URL="http://127.0.0.1:$STUB_PORT" VOICES_DIR="$TEST_TMP/bigvoices" \
+        bash "$WARM"
+    [ "$status" -eq 0 ] || { echo "$output"; false; }
+    [[ "$output" == *"voice bigvoice cold="*"ms warm="*"ms"* ]] || { echo "$output"; false; }
+
+    # And the audio that arrived is the audio that was on disk, whole.
+    python3 - "$TEST_TMP/journal.jsonl" "$big/reference.wav" <<'PY'
+import hashlib, json, sys
+entries = [json.loads(l) for l in open(sys.argv[1])]
+regs = [e for e in entries if e["path"] == "/v1/audio/voices"]
+assert len(regs) == 1, entries
+assert regs[0]["name"] == "bigvoice", regs[0]
+want = hashlib.sha256(open(sys.argv[2], "rb").read()).hexdigest()
+assert regs[0]["wav_sha256"] == want, (len(regs[0]["wav_sha256"]), want)
+PY
+}
+
+@test "the warm sentence survives both readers of the env file intact" {
+    # scripts/frank-tts-engine.env is read two ways and they disagree about
+    # quotes. bash (`set -a; source`, what the seams and a human do) strips the
+    # quotes around a value with spaces. podman's --env-file — how the unit really
+    # reads it — does NOT: measured 2026-10-18 against the image's pinned base,
+    # the value lands in the container WITH its quotes. Interpolated raw into the
+    # hook's JSON body that is `""Warm up…"",` — the engine answers 400, no voice
+    # warms, and the boot still reads healthy. So the hook unwraps one
+    # shell-style layer and then escapes, and BOTH shapes must arrive as the
+    # sentence the operator wrote.
+    start_engine_stub
+
+    # Shape A: what podman delivers for `WARM_TEXT="Warm up, one two three."`.
+    run env ENGINE_URL="http://127.0.0.1:$STUB_PORT" VOICES_DIR="$VOICES" \
+        WARM_TEXT='"Warm up, one two three."' bash "$WARM"
+    [ "$status" -eq 0 ] || { echo "$output"; false; }
+    [[ "$output" == *"voice narrator1 cold="*"ms warm="*"ms"* ]] || { echo "$output"; false; }
+    python3 - "$TEST_TMP/journal.jsonl" <<'PY'
+import json, sys
+entries = [json.loads(l) for l in open(sys.argv[1])]
+assert not [e for e in entries if e.get("invalid_json")], entries
+speech = [e for e in entries if e["path"] == "/v1/audio/speech"]
+assert len(speech) == 2, entries
+assert {s["input"] for s in speech} == {"Warm up, one two three."}, speech
+PY
+
+    # Shape B: a value that starts AND ends with a quote but carries more quotes
+    # INSIDE — exactly the shape an unwrap rule must refuse, because peeling the
+    # outer pair would delete characters the operator wrote. It must arrive
+    # character for character (trailing quote included), which also proves the
+    # escaping does not mangle what it is protecting.
+    : > "$TEST_TMP/journal.jsonl"
+    run env ENGINE_URL="http://127.0.0.1:$STUB_PORT" VOICES_DIR="$VOICES" \
+        WARM_TEXT='"He said "hi"\ once"' bash "$WARM"
+    [ "$status" -eq 0 ] || { echo "$output"; false; }
+    python3 - "$TEST_TMP/journal.jsonl" <<'PY'
+import json, sys
+entries = [json.loads(l) for l in open(sys.argv[1])]
+assert not [e for e in entries if e.get("invalid_json")], entries
+speech = [e for e in entries if e["path"] == "/v1/audio/speech"]
+assert len(speech) == 2, entries
+assert {s["input"] for s in speech} == {'"He said "hi"\\ once"'}, speech
+PY
+}
+
+@test "a directory without reference.wav is not a voice, and a mixed-case name is refused" {
+    # `justamanifest` must be invisible; `Narrator2` must be loud. The engine
+    # lowercases every voice name (tts_voice_name) while frank-tts matches the
+    # directory name exactly, so a mixed-case pack is a voice that works on one
+    # side of the pair and not the other. Silence here is how a wrong-voice pack
+    # survives for weeks.
+    mkdir -p "$VOICES/Narrator2"
+    printf 'RIFFwrongcase' > "$VOICES/Narrator2/reference.wav"
+    start_engine_stub
+    run env ENGINE_URL="http://127.0.0.1:$STUB_PORT" VOICES_DIR="$VOICES" \
+        bash "$WARM"
+    [ "$status" -eq 1 ] || { echo "$output"; false; }
+    [[ "$output" == *"Narrator2"* ]]
+    [[ "$output" == *"lowercase"* ]]
+    run cat "$TEST_TMP/journal.jsonl"
+    [[ "$output" != *"justamanifest"* ]]
+    [[ "$output" != *"Narrator2"* ]]
+    # The refusal is a journal line plus a non-zero exit — not a crash: the
+    # narrator1 pack still got registered and warmed above the failure.
+    grep -q 'narrator1' "$TEST_TMP/journal.jsonl"
+}
+
+@test "an engine that never answers /health is reported, and nothing is registered" {
+    # HEALTH_WAIT is a deadline, not a retry-forever: an engine that dies on
+    # boot must produce one clear journal line and a non-zero exit (which the
+    # unit's `-` prefix turns into "nothing happened", not a crash loop).
+    port="$(free_port)"
+    run env ENGINE_URL="http://127.0.0.1:$port" VOICES_DIR="$VOICES" HEALTH_WAIT=1 \
+        bash "$WARM"
+    [ "$status" -eq 1 ] || { echo "$output"; false; }
+    [[ "$output" == *"/health"* ]] || { echo "$output"; false; }
+    [[ "$output" == *"did not answer"* ]]
+    [ ! -s "$TEST_TMP/journal.jsonl" ]
+}
+
+@test "the warmer waits for a late engine instead of racing model load" {
+    # Boot order: ExecStartPost fires the moment the container starts, while the
+    # two GGUFs (1.2 GiB + 291 MB) are still being read and the HTTP thread has
+    # not bound yet. The warmer is launched against an address with nothing on
+    # it, the listener appears a beat later, and the requirement is that the
+    # warmer notices and does the work — an early exit leaves every voice
+    # unregistered, and the façade then answers 400 for all of them.
+    port="$(free_port)"
+    ( ENGINE_URL="http://127.0.0.1:$port" VOICES_DIR="$VOICES" HEALTH_WAIT=60 \
+        bash "$WARM" > "$TEST_TMP/race.log" 2>&1; echo "$?" > "$TEST_TMP/race.rc" ) &
+    echo "$!" >> "$PIDS"
+    sleep 0.7
+    start_engine_stub "$port"
+    local waited=0
+    while [ ! -f "$TEST_TMP/race.rc" ] && [ "$waited" -lt 200 ]; do
+        sleep 0.05
+        waited=$((waited + 1))
+    done
+    [ -f "$TEST_TMP/race.rc" ] || { echo "warmer never finished:"; cat "$TEST_TMP/race.log"; false; }
+    [ "$(cat "$TEST_TMP/race.rc")" = "0" ] || { cat "$TEST_TMP/race.log"; false; }
+    grep -q '/v1/audio/voices' "$TEST_TMP/journal.jsonl"
+    grep -q '/v1/audio/speech' "$TEST_TMP/journal.jsonl"
+}
+
+@test "a synthesis that never returns is abandoned at REQUEST_TIMEOUT, not waited out" {
+    # systemd counts the WHOLE warm pass against TimeoutStartSec, so the price
+    # of a hung engine is paid by the unit: the endpoint stays "activating" and
+    # never reaches started. The warmer therefore puts a ceiling on every
+    # request. Here the engine registers the voice and then never answers the
+    # synthesis — the failure mode a wedged GEMM loop actually produces.
+    STUB_HANG_SPEECH=30
+    export STUB_HANG_SPEECH
+    start_engine_stub
+    run env ENGINE_URL="http://127.0.0.1:$STUB_PORT" VOICES_DIR="$VOICES" \
+        REQUEST_TIMEOUT=1 bash "$WARM"
+    [ "$status" -eq 1 ] || { echo "$output"; false; }
+    [[ "$output" == *"warm synthesis failed"* ]] || { echo "$output"; false; }
+    # It got as far as registering, so the stall — not a missing route — is
+    # what ended the pass.
+    grep -q '/v1/audio/voices' "$TEST_TMP/journal.jsonl"
+}
+
+@test "an empty voice root is an explanation, not a failure" {
+    # No packs yet is the state right after this unit is deployed and before the
+    # pack builder runs. Failing there would mark the engine deploy incomplete
+    # and, worse, read as a broken warmer to whoever is debugging a real one.
+    start_engine_stub
+    run env ENGINE_URL="http://127.0.0.1:$STUB_PORT" VOICES_DIR="$TEST_TMP/nodir" \
+        bash "$WARM"
+    [ "$status" -eq 0 ] || { echo "$output"; false; }
+    [[ "$output" == *"no voice directory"* ]]
+    # No registration, no synthesis. Health polls are expected — the stub
+    # journals them, and this is about what the warmer must NOT send.
+    run grep -c '/v1/audio' "$TEST_TMP/journal.jsonl"
+    [ "$output" = "0" ]
+}
+
+@test "the warmer's knobs come from the same env file the engine reads" {
+    # The warm hook is exec-ed into the container, so systemd hands it the unit's
+    # EnvironmentFile — one file for both. Sourcing it here is how that is
+    # reproduced without a container: if a key were renamed on one side only, the
+    # hook would silently fall back to its built-in default and the knob would do
+    # nothing, which no grep of either file alone can catch.
+    start_engine_stub
+    set -a
+    # shellcheck disable=SC1090
+    source "$ENVF"
+    set +a
+    [ -n "${WARM_TEXT:-}" ] || { echo "scripts/frank-tts-engine.env defines no WARM_TEXT"; false; }
+    run env ENGINE_URL="http://127.0.0.1:$STUB_PORT" VOICES_DIR="$VOICES" \
+        bash "$WARM"
+    [ "$status" -eq 0 ] || { echo "$output"; false; }
+    python3 - "$TEST_TMP/journal.jsonl" "$WARM_TEXT" <<'PY'
+import json, sys
+texts = {json.loads(l).get("input") for l in open(sys.argv[1])
+         if json.loads(l)["path"] == "/v1/audio/speech"}
+assert texts == {sys.argv[2]}, (texts, sys.argv[2])
+PY
+    # The engine-side keys are in the same file and must not collide with the
+    # warmer's: QWENTTS_PORT is what the server binds, ENGINE_URL is where the
+    # hook dials, and they are different values by design (container bind address
+    # versus in-namespace loopback).
+    grep -qE '^QWENTTS_PORT=8880$' "$ENVF"
+    grep -qE '^VOICES_DIR=/voices$' "$ENVF"
+}
+
+@test "the fetcher pins the decided weights and puts no credential on the wire" {
+    # The byte counts and the Hub pointer oids ARE the contract for the payload,
+    # the same way an image digest is: they came off the Hub on 2026-10-18 and a
+    # silent change means someone moved a file upstream.
+    run grep -h '^  "Serveurperso/Qwen3-TTS-GGUF|' "$FETCH"
+    [ "$(printf '%s\n' "$output" | grep -c .)" = "2" ]
+    printf '%s\n' "$output" | grep -qF "|$TALKER|$TALKER|$TALKER_BYTES|$TALKER_SHA"
+    printf '%s\n' "$output" | grep -qF "|$CODEC|$CODEC|$CODEC_BYTES|$CODEC_SHA"
+    # sha256 oids, not the 40-char git blob ids the same API also returns.
+    run grep -oE '\|[0-9a-f]{64}"$' "$FETCH"
+    [ "$(printf '%s\n' "$output" | grep -c .)" = "2" ]
+    # Public repo: no auth header, and no token in the invocation.
+    ! grep -qE 'HF_TOKEN|Authorization|--header' "$FETCH"
+    grep -qE 'curl -fsSL --fail-with-body' "$FETCH"
+}
+
+@test "the fetcher reports absent and wrong-sized weights as MISSING, non-zero" {
+    run bash "$FETCH" "$TEST_TMP/payload" --verify-only
+    [ "$status" -eq 1 ] || { echo "$output"; false; }
+    [[ "$output" == *"MISSING   $TALKER"* ]]
+    [[ "$output" == *"MISSING   $CODEC"* ]]
+    [[ "$output" == *"DOWNLOAD_FAILED"* ]]
+    # A partial download of the right NAME is still missing: the byte count is
+    # what gates, and a truncated GGUF would mmap fine and then produce noise.
+    mkdir -p "$TEST_TMP/payload"
+    head -c 4096 /dev/zero > "$TEST_TMP/payload/$TALKER"
+    : > "$TEST_TMP/payload/$CODEC"
+    run bash "$FETCH" "$TEST_TMP/payload" --verify-only
+    [ "$status" -eq 1 ]
+    [[ "$output" == *"MISSING   $TALKER"* ]]
+    [[ "$output" == *"MISSING   $CODEC"* ]]
+}
+
+@test "the image build is the pinned commit with the proven cmake line" {
+    # GGML_BLAS=OFF is forced by the host (libopenblas.so.0 present, no dev
+    # headers) and upstream's own Dockerfile passes it ON, so this file is not a
+    # copy of upstream on purpose. -j 8 and the OFF-for-every-GPU-backend list
+    # are what the 2026-10-18 trial ran.
+    grep -qE '^ARG QWENTTS_COMMIT=[0-9a-f]{40}$' "$CF"
+    grep -qF '5916bf7c79dbb4e66fc059cdc507a79a23a28bb4' "$CF"
+    grep -qE 'git -C /src checkout --detach' "$CF"
+    grep -qE 'submodule update --init' "$CF"   # ggml is a submodule; without it the build cannot configure
+    for flag in -DGGML_CCACHE=OFF -DGGML_BACKEND_DL=OFF -DGGML_CPU_ALL_VARIANTS=OFF \
+                -DGGML_OPENMP=ON -DGGML_BLAS=OFF -DGGML_CUDA=OFF -DGGML_HIP=OFF \
+                -DGGML_VULKAN=OFF -DGGML_METAL=OFF -DGGML_SYCL=OFF -DGGML_RPC=OFF; do
+        grep -qF -- "$flag" "$CF" || { echo "build line lost $flag"; false; }
+    done
+    grep -qE 'cmake --build build -j 8' "$CF"
+    # OpenMP on means the runtime stage needs the OpenMP runtime, and the probe
+    # runs as /bin/sh -c, so the runtime stage needs curl.
+    grep -qE 'libgomp1' "$CF"
+    grep -qE '^\s+ca-certificates curl libgomp1' "$CF"
+    # Both scripts ship in the image: the server's entrypoint, and the warmer the
+    # unit execs. A warmer that is not in the image makes the unit's
+    # ExecStartPost fail on every boot, silently (`-` prefix by design).
+    grep -qF 'COPY dankclaw/voiceservice/tts-engine-start.sh /app/start.sh' "$CF"
+    grep -qF 'COPY dankclaw/voiceservice/tts-engine-warm.sh /app/warm-voices.sh' "$CF"
+    grep -qE 'chmod 755 /app/start.sh /app/warm-voices.sh' "$CF"
+    ! grep -qE '^HEALTHCHECK' "$CF"            # the probe lives in the Quadlet unit
+    grep -qE '^USER tts$' "$CF"
+    # Base pinned by digest, both stages from one image.
+    grep -qE '^ARG BASE_IMAGE=docker\.io/library/ubuntu:24\.04@sha256:[0-9a-f]{64}$' "$CF"
+    [ "$(grep -cE '^FROM \$\{BASE_IMAGE\}' "$CF")" = "2" ]
+}
+
+@test "the planner maps every engine path to frank-tts-engine, and nothing to dankserver" {
+    # Everything named after the engine, EXCEPT the bridge file: both units
+    # attach to it, so a subnet change is a change to two deployables and that
+    # pairing is asserted in the façade's planner test below.
+    run python3 "$PLANNER" --target dankclaw --paths \
+        dankclaw/voiceservice/quadlet/frank-tts-engine.container \
+        dankclaw/voiceservice/Containerfile.engine \
+        dankclaw/voiceservice/tts-engine-start.sh \
+        scripts/frank-tts-engine.env \
+        dankclaw/voiceservice/tts-engine-warm.sh
+    [ "$status" -eq 0 ]
+    [ "$output" = "frank-tts-engine" ]
+
+    # Host-side payload and repo tooling restart nothing: the weights are host
+    # state, exactly like every other download script.
+    run python3 "$PLANNER" --target dankclaw --paths \
+        scripts/download-frank-tts-engine-qwentts.sh
+    [ "$status" -eq 0 ]
+    [ -z "$output" ]
+
+    # The engine is a Dankclaw container. On Dankserver these paths must plan
+    # nothing rather than queue a service that does not exist there.
+    run python3 "$PLANNER" --target dankserver --paths \
+        dankclaw/voiceservice/quadlet/frank-tts-engine.container \
+        scripts/frank-tts-engine.env
+    [ "$status" -eq 0 ]
+    [ -z "$output" ]
+}
+
+@test "changed-path routing selects this seam" {
+    # The regression this guards is real and was hit next door: the generic
+    # dankclaw/*.container case matches across `/`, so a quadlet path placed
+    # below it never reaches its own seam.
+    run "$REPO_ROOT/scripts/test-changed.sh" --list --paths \
+        dankclaw/voiceservice/quadlet/frank-tts-engine.container
+    [ "$status" -eq 0 ]
+    printf '%s\n' "$output" | grep -qx "tests/frank_tts_engine.bats"
+
+    run "$REPO_ROOT/scripts/test-changed.sh" --list --paths \
+        dankclaw/voiceservice/quadlet/frank-tts-engine.network
+    [ "$status" -eq 0 ]
+    printf '%s\n' "$output" | grep -qx "tests/frank_tts_engine.bats"
+
+    run "$REPO_ROOT/scripts/test-changed.sh" --list --paths scripts/frank-tts-engine.env
+    [ "$status" -eq 0 ]
+    printf '%s\n' "$output" | grep -qx "tests/frank_tts_engine.bats"
+    printf '%s\n' "$output" | grep -qx "tests/scripts_syntax.bats"
+}
+
+@test "both deployer entry points know the engine and its handler gates on health, then warm" {
+    grep -qF 'dankclaw:frank-tts-engine|' "$REMOTE"
+    grep -qF 'dankclaw:frank-tts-engine|' "$REPO_ROOT/scripts/deploy.sh"
+    grep -qF 'frank-tts-engine) deploy_frank_tts_engine ;;' "$REMOTE"
+    grep -qF 'containerfile=dankclaw/voiceservice/Containerfile.engine' "$REMOTE"
+
+    handler="$(sed -n '/^deploy_frank_tts_engine()/,/^}/p' "$REMOTE")"
+    [ -n "$handler" ] || { echo "no deploy_frank_tts_engine handler"; false; }
+    # Weights before build, build before start, health before warm: in that
+    # order, because each step's failure message is only true in that order.
+    local weights build quadlet start health warm pos_prev=-1 pos
+    weights="$(printf '%s' "$handler" | grep -n 'download-frank-tts-engine-qwentts.sh --verify-only' | head -1 | cut -d: -f1)"
+    build="$(printf '%s' "$handler" | grep -n 'build_compose_image frank-tts-engine' | head -1 | cut -d: -f1)"
+    quadlet="$(printf '%s' "$handler" | grep -n 'install_quadlet frank-tts-engine' | head -1 | cut -d: -f1)"
+    start="$(printf '%s' "$handler" | grep -n 'systemctl --user restart frank-tts-engine.service' | head -1 | cut -d: -f1)"
+    health="$(printf '%s' "$handler" | grep -n 'wait_container_healthy frank-tts-engine' | head -1 | cut -d: -f1)"
+    warm="$(printf '%s' "$handler" | grep -n 'podman exec frank-tts-engine /app/warm-voices.sh' | head -1 | cut -d: -f1)"
+    for pos in "$weights" "$build" "$quadlet" "$start" "$health" "$warm"; do
+        [ -n "$pos" ] || { echo "handler is missing a step (weights/build/quadlet/start/health/warm)"; false; }
+        [ "$pos" -gt "$pos_prev" ] || { echo "handler steps are out of order"; false; }
+        pos_prev="$pos"
+    done
+    # The gate is podman's recorded health, not a URL: this container publishes
+    # nothing, so the host has no address to dial.
+    printf '%s' "$handler" | grep -qE 'wait_container_healthy frank-tts-engine [0-9]+'
+    ! printf '%s' "$handler" | grep -qE 'wait_for_health frank-tts-engine'
+    # Generated Quadlet units cannot be enabled on this host: the handler must
+    # not try, and the unit carries [Install] instead.
+    ! printf '%s' "$handler" | grep -qE '^[[:space:]]*systemctl --user enable'
+}
+
+@test "the two scripts that ship in the image pass the repo's shell gates" {
+    # scripts_syntax.bats walks scripts/ only, and these two no longer live
+    # there: the entrypoint is the container's only way to read the env file,
+    # and the warmer is exec-ed by the unit. A syntax error in either is a
+    # container that never starts, or a deploy that reports an engine nobody
+    # told it to talk to, so they get the same gates as scripts/*.sh.
+    local s
+    for s in "$START" "$WARM"; do
+        bash -n "$s" || { echo "syntax error in $s"; false; }
+        [ -x "$s" ] || { echo "$s is not executable — git must record the mode"; false; }
+        if command -v shellcheck >/dev/null 2>&1; then
+            shellcheck -S error "$s" || { echo "shellcheck errors in $s"; false; }
+        fi
+    done
+}
+
+@test "the generator puts the façade on both bridges and behind the engine" {
+    rendered="$(render_units)" || { echo "$rendered"; skip "no Quadlet generator here"; }
+    line="$(printf '%s\n' "$rendered" | grep -E '^ExecStart=/usr/bin/podman run .*--name frank-tts ')"
+    [ -n "$line" ] || { printf '%s\n' "$rendered"; false; }
+
+    # Two attachments, and the fleet-wide bridge FIRST: that is the network
+    # consumers address (open-notebook dials `http://frank-tts:7772/v1` by
+    # container name), so it owns the default route. The engine's private bridge
+    # is second and exists so the shim can resolve the engine at all.
+    [ "$(printf '%s' "$line" | grep -oE -- '--network [^ ]+' | head -1)" = "--network dankclaw_default" ]
+    printf '%s' "$line" | grep -qE -- '--network systemd-frank-tts-engine( |$)'
+    # Published exactly once, on the fleet port — and this is the only publish in
+    # the voice stack.
+    [ "$(printf '%s' "$line" | grep -oE -- '--publish [^ ]+' | wc -l)" = "1" ]
+    printf '%s' "$line" | grep -qE -- '--publish (\[::\]:)?7772:7772( |$)'
+
+    unit="$(unit_block frank-tts.service)"
+    printf '%s' "$unit" | grep -qE '^Wants=frank-tts-engine\.service$'
+    printf '%s' "$unit" | grep -qE '^After=.*frank-tts-engine\.service'
+    # Wants, never Requires: the CLI rollback backend needs no upstream, and an
+    # engine that will not start must not take this endpoint's unit down.
+    ! printf '%s' "$unit" | grep -qE '^Requires=frank-tts-engine\.service$'
+    # And it is tied to the bridge as well, or the container would be started
+    # before netavark had created the network it dials over.
+    printf '%s' "$unit" | grep -qE '^Requires=frank-tts-engine-network\.service$'
+}
+
+@test "the upstream the env file names is only resolvable on a network the unit joins" {
+    # The pair's one real wiring contract, checked as a join rather than as a
+    # string: take the hostname out of TTS_UPSTREAM the way the container will
+    # get it, and require the façade unit to attach to the Quadlet network file
+    # named after that hostname. A revert to host.containers.internal, or a unit
+    # that drops the second Network= line, breaks here — both mistakes leave the
+    # endpoint answering and every synthesis failing.
+    set -a
+    # shellcheck disable=SC1090
+    source "$FACADE_ENV"
+    set +a
+    host="${TTS_UPSTREAM#*://}"
+    host="${host%%:*}"
+    host="${host%%/*}"
+    [ -n "$host" ] || { echo "TTS_UPSTREAM names no host: $TTS_UPSTREAM"; false; }
+    [ "$host" != localhost ] || { echo "localhost is not reachable across netns"; false; }
+    if ! grep -qE "^Network=${host}\.network$" "$FACADE"; then
+        echo "frank-tts.container does not attach to ${host}.network"
+        false
+    fi
+    if ! [ -f "$REPO_ROOT/dankclaw/voiceservice/quadlet/${host}.network" ]; then
+        echo "no Quadlet network file for $host — the generator would drop the unit"
+        false
+    fi
+}
+
+@test "the planner keeps the two voice deployables separate and ordered" {
+    # `--only` on the façade must not drag the engine's rebuild along, and a
+    # bridge change must restart both: the network file is named after the engine
+    # unit only because install_quadlet copies `$unit.network` beside the unit.
+    run python3 "$PLANNER" --target dankclaw --paths dankclaw/voiceservice/app.py
+    [ "$output" = "frank-tts" ]
+    run python3 "$PLANNER" --target dankclaw --paths dankclaw/voiceservice/Containerfile
+    [ "$output" = "frank-tts" ]
+    run python3 "$PLANNER" --target dankclaw --paths \
+        dankclaw/voiceservice/quadlet/frank-tts.container
+    [ "$output" = "frank-tts" ]
+    run python3 "$PLANNER" --target dankclaw --paths \
+        dankclaw/voiceservice/quadlet/frank-tts-engine.container
+    [ "$output" = "frank-tts-engine" ]
+    run python3 "$PLANNER" --target dankclaw --paths \
+        dankclaw/voiceservice/quadlet/frank-tts-engine.network
+    printf '%s\n' "$output" | grep -qx frank-tts
+    printf '%s\n' "$output" | grep -qx frank-tts-engine
+
+    # Order: dependency before consumer, so a full dankclaw deploy starts a warm
+    # engine and then the endpoint that forwards into it.
+    run python3 "$PLANNER" --target dankclaw --paths \
+        dankclaw/voiceservice/quadlet/frank-tts.container \
+        dankclaw/voiceservice/quadlet/frank-tts-engine.container
+    local e f
+    e="$(printf '%s\n' "$output" | grep -n '^frank-tts-engine$' | cut -d: -f1)"
+    f="$(printf '%s\n' "$output" | grep -n '^frank-tts$' | cut -d: -f1)"
+    [ -n "$e" ] && [ -n "$f" ] && [ "$e" -lt "$f" ]
+}
+
+@test "the façade handler builds its image, installs the bridge file, and gates on recorded health" {
+    grep -qF 'dankclaw:frank-tts|' "$REMOTE"
+    grep -qF 'dankclaw:frank-tts|' "$REPO_ROOT/scripts/deploy.sh"
+    grep -qF 'frank-tts) deploy_frank_tts ;;' "$REMOTE"
+    # build_compose_image's default arm returns 0 without building: an unlisted
+    # service means a unit whose Pull=never image was never made.
+    grep -qE '^\s+containerfile=dankclaw/voiceservice/Containerfile$' "$REMOTE"
+
+    handler="$(sed -n '/^deploy_frank_tts()/,/^}/p' "$REMOTE")"
+    [ -n "$handler" ] || { echo "no deploy_frank_tts handler"; false; }
+    printf '%s' "$handler" | grep -qF 'build_compose_image frank-tts'
+    printf '%s' "$handler" | grep -qF 'install_quadlet frank-tts dankclaw/voiceservice/quadlet frank-tts'
+    # The engine's quadlet pair is installed by this handler too: with the
+    # referenced .network file missing the generator produces no façade unit at
+    # all, and `--only frank-tts` has no other way to get it onto the host.
+    printf '%s' "$handler" | grep -qF 'install_quadlet frank-tts-engine dankclaw/voiceservice/quadlet frank-tts-engine'
+    printf '%s' "$handler" | grep -qE 'mkdir -p /home/dank/voices'
+    printf '%s' "$handler" | grep -qE 'systemctl --user restart frank-tts\.service'
+    printf '%s' "$handler" | grep -qE 'wait_container_healthy frank-tts [0-9]+'
+    ! printf '%s' "$handler" | grep -qE '^[[:space:]]*systemctl --user enable'
+}
+
+@test "an image rebuild is triggered by every file the image bakes in" {
+    # build_compose_image skips `podman build` when the image's cfhash label
+    # matches a hash — the thing that keeps the engine's 10-minute source clone
+    # from running on every re-deploy. If that hash covers only the Containerfile,
+    # then editing app.py (COPY'd into the façade) or the warm hook (COPY'd into
+    # the engine) rebuilds NOTHING: the deploy reports success, /health answers,
+    # and the container is still running last week's code. Observable output, not
+    # a grep of the handler: did the deploy ask podman to build, or did it skip?
+    awk '/^build_compose_image\(\) \{/,/^\}/' "$REMOTE" > "$TEST_TMP/bci.sh"
+    [ -s "$TEST_TMP/bci.sh" ] || { echo "build_compose_image not extractable from $REMOTE"; false; }
+
+    repo="$TEST_TMP/repo"
+    mkdir -p "$repo/dankclaw/voiceservice"
+    : > "$repo/dankclaw/voiceservice/Containerfile"
+    : > "$repo/dankclaw/voiceservice/Containerfile.engine"
+    : > "$repo/dankclaw/voiceservice/app.py"
+    : > "$repo/dankclaw/voiceservice/tts-engine-start.sh"
+    : > "$repo/dankclaw/voiceservice/tts-engine-warm.sh"
+
+    # Stub podman: `image inspect` replays the label this stub stored on the last
+    # build of THAT image (nothing the first time), `build` records the tag and
+    # writes the label it was given. One state file per image, so the pair's two
+    # images cannot borrow each other's freshness.
+    mkdir -p "$TEST_TMP/bin" "$TEST_TMP/labels"
+    cat > "$TEST_TMP/bin/podman" <<'STUB'
+#!/usr/bin/env bash
+# Image tags contain a slash (`franksdank/foo:latest`), so the state file name
+# flattens it — otherwise the write lands in a directory that does not exist and
+# every image looks permanently unbuilt.
+case "$1" in
+    image)      # invoked as `podman image inspect <image> --format …`, so $3 is the tag
+        f="$LABEL_DIR/${3//\//_}"
+        [[ -s "$f" ]] && { cat "$f"; exit 0; }
+        exit 1
+        ;;
+    build)
+        # Two passes: `podman build` puts `--label cfhash=…` BEFORE `-t <tag>`, so
+        # the tag is not known when the label argument goes by.
+        tag=""
+        label=""
+        for a in "$@"; do
+            case "$a" in
+                *:*) tag="$a" ;;
+                cfhash=*) label="${a#cfhash=}" ;;
+            esac
+        done
+        [[ -n "$label" ]] && printf '%s' "$label" > "$LABEL_DIR/${tag//\//_}"
+        printf 'BUILD %s\n' "$tag" >> "$BUILD_LOG"
+        ;;
+esac
+STUB
+    chmod +x "$TEST_TMP/bin/podman"
+    cat > "$TEST_TMP/drive.sh" <<'DRV'
+#!/usr/bin/env bash
+set -euo pipefail
+source "$BCI"
+build_compose_image "$1"
+DRV
+    : > "$TEST_TMP/builds"
+    builds() { grep -cF "BUILD $1" "$TEST_TMP/builds"; }
+    drive() {
+        ( cd "$repo" && BCI="$TEST_TMP/bci.sh" PATH="$TEST_TMP/bin:$PATH" \
+            LABEL_DIR="$TEST_TMP/labels" BUILD_LOG="$TEST_TMP/builds" \
+            bash "$TEST_TMP/drive.sh" "$1" )
+    }
+
+    drive frank-tts-engine
+    [ "$(builds franksdank/frank-tts-engine:latest)" -eq 1 ] \
+        || { echo "the first deploy of an unbuilt image must build"; false; }
+    drive frank-tts-engine
+    [ "$(builds franksdank/frank-tts-engine:latest)" -eq 1 ] \
+        || { echo "an unchanged tree must not rebuild — that is the 10-minute clone"; false; }
+
+    printf '# the boot warmer grew a line\n' >> "$repo/dankclaw/voiceservice/tts-engine-warm.sh"
+    drive frank-tts-engine
+    [ "$(builds franksdank/frank-tts-engine:latest)" -eq 2 ] \
+        || { echo "editing a script the image COPYs must rebuild it"; false; }
+
+    drive frank-tts
+    [ "$(builds franksdank/frank-tts:latest)" -eq 1 ] || { echo "the façade must build once"; false; }
+    printf '# the shim grew a route\n' >> "$repo/dankclaw/voiceservice/app.py"
+    drive frank-tts
+    [ "$(builds franksdank/frank-tts:latest)" -eq 2 ] \
+        || { echo "editing app.py must rebuild the façade image"; false; }
+}
+
+@test "the voice stack's homepage state: one probed card for the pair, and no link" {
+    # The engine is not on the homepage and must not be: it publishes no port, so
+    # there is no address the checker could dial, and a card that can never be
+    # green is worse than no card. The façade carries the pair's signal — and
+    # since the 2026-10-18 deploy that signal is a real probe (`wip: false`), not
+    # a placeholder. It stays `showLink: false` and admin-only: an HTTP API has no
+    # page to open, and the checker counts ANY HTTP response as up, so the card is
+    # honest without a link and without a `/health` path in the probe.
+    python3 - "$REPO_ROOT" <<'PY'
+import json, os, sys
+root = sys.argv[1]
+cards = {c["name"]: c for c in json.load(open(f"{root}/shared/homepage/services.json"))}
+assert "frank-tts-engine" not in cards, \
+    "the engine publishes no port: a card for it could never be probed green"
+fts = cards["frank-tts"]
+assert fts["probe"] == "127.0.0.1:7772", fts["probe"]
+assert fts["wip"] is False, \
+    "the endpoint is deployed; a wip card would hide its real state: " + repr(fts.get("wip"))
+assert fts["showLink"] is False and fts["url"] == "", \
+    "an API endpoint has no UI to link to — it is a status card, not a tile"
+assert fts["category"] == "admin", \
+    "consumers dial this; it is not an app the user homepage should advertise"
+assert os.path.exists(f"{root}/shared/homepage{fts['art']}"), f"missing art {fts['art']}"
+PY
+}
+
+@test "either deployable's paths select both voice seams" {
+    # A change to the bridge or the env file can break the other half of the
+    # pair, and the seams are cheap; routing them together is what keeps a
+    # façade-only commit from landing without the engine's wiring tests.
+    run "$REPO_ROOT/scripts/test-changed.sh" --list --paths \
+        dankclaw/voiceservice/quadlet/frank-tts.container
+    [ "$status" -eq 0 ]
+    printf '%s\n' "$output" | grep -qx "tests/frank_tts_unit.bats"
+    printf '%s\n' "$output" | grep -qx "tests/frank_tts_engine.bats"
+
+    run "$REPO_ROOT/scripts/test-changed.sh" --list --paths dankclaw/voiceservice/app.py
+    [ "$status" -eq 0 ]
+    printf '%s\n' "$output" | grep -qx "tests/frank_tts_unit.bats"
+}

tests/frank_tts_unit.bats

@@ -183,6 +183,37 @@ assert 'voice_id' not in body, body
 PY
 }
 
+@test "a voice-less request speaks the declared default and marks the log" {
+    # The omp harness has no setting that feeds a voice to its speech device, so
+    # a voice-less call is its NORMAL shape rather than a client bug. With the
+    # operator's default armed the call must produce that pack's audio, and the
+    # journal line must say (default) — otherwise an unrequested voice reads,
+    # weeks later, exactly like one somebody asked for.
+    arm_omni
+    export DEFAULT_VOICE=narrator1
+    start_app
+    speech '{"model":"tts-1","input":"hello"}'
+    [ "$output" = "200" ] || { cat "$TEST_TMP/app.log"; false; }
+    cmp "$TEST_TMP/out.bin" "$TEST_TMP/upstream.wav"
+    python3 - "$TEST_TMP/capture.json" <<'PY'
+import json, sys
+body = json.load(open(sys.argv[1]))
+assert body['voice'] == 'narrator1', 'the declared default never reached the engine'
+PY
+    grep -q 'speech voice=narrator1 (default) format=wav' "$TEST_TMP/app.log" \
+        || { cat "$TEST_TMP/app.log"; false; }
+}
+
+@test "with no default declared a voice-less request stays a 400" {
+    # Strictness is still the code default: an endpoint that invents a voice
+    # nobody configured is exactly how a wrong-voice deployment stays wrong.
+    arm_omni
+    start_app
+    speech '{"model":"tts-1","input":"hello"}'
+    [ "$output" = "400" ] || { cat "$TEST_TMP/app.log"; false; }
+    grep -q 'narrator1' "$TEST_TMP/out.bin"
+}
+
 @test "an unknown voice is a 400 naming the voices that exist" {
     arm_omni
     start_app

tests/frank_zealot_unit.bats

@@ -3,15 +3,16 @@
 # prism-ml/Ternary-Bonsai-2-9B-gguf at PQ2_0 — the ternary Bonsai-2-9B, a
 # qwen35 hybrid with 32 layers (8 full-attention + 24 Gated DeltaNet) and the
 # MTP draft head INSIDE the file — via the PrismML fork build of llama.cpp
-# (vendor build 10777, the minimum that pairs MTP with a quantized V cache),
-# the ONLY loader that registers the payload's custom tensor type 142 and
-# honours its prism.hadamard.* metadata: THREE 262,144-token conversations
-# (--ctx-size 786432 --parallel 3), q8_0 K + q8_0 V under flash attention (f16
-# KV would bill 26,112 MiB of a 24,123 MiB card), the publisher's own Q8_0
-# vision projector (the BF16 one can crash on concurrent images), and MTP OFF
-# — measured, not because the head is missing: the draft context bills f16 KV
-# over the whole pool and halves decode at this shape. Log verbosity 4 ships so
-# the VRAM-fit forensics land in the journal.
+# (vendor build 10777), the ONLY loader that registers the payload's custom
+# tensor type 142 and honours its prism.hadamard.* metadata: TWO 262,144-token
+# conversations (--ctx-size 524288 --parallel 2) over an UNQUANTIZED f16 KV
+# cache. Exact KV bills 32,768 B/token here, so the pool is what pays for it —
+# the same dtype at the old 786,432 pool is 24,576 MiB against the 24,123 MiB
+# the driver leaves addressable, and the slot count is the term that moved. The
+# publisher's own Q8_0 vision projector rides along (the BF16 one can crash on
+# concurrent images), and MTP stays OFF: the head is present, but exact KV
+# leaves no room for a draft context that bills f16 KV over the whole pool. Log
+# verbosity 4 ships so the VRAM-fit forensics land in the journal.
 # This seam runs the serve script against a stub engine and asserts on the
 # argv it actually execs, so what is pinned is the command the operator gets.
 
@@ -76,6 +77,22 @@ argv_value() {
     grep -A1 -xF -- "$1" <<<"$output" | tail -1
 }
 
+# kv_bytes_per_token DTYPE — bytes ONE cache costs per token at this payload's
+# geometry: 8 full-attention layers × 4 KV heads × 256 dim = 8,192 elements
+# (measured from the GGUF header: n_embd_k_gqa = n_embd_v_gqa = 1024). f16 is
+# 2 B/element; q8_0 is 1.0625 (32 codes plus one 2-byte scale per 32-block);
+# q4_0 is 0.625 (codes + scale + min per 32-block). Unknown dtype is a FAILURE,
+# never a silent zero — the fit gate below is only honest if it cannot be
+# satisfied by a rung it does not understand.
+kv_bytes_per_token() {
+    case "$1" in
+        f16|bf16) echo 16384 ;;
+        q8_0) echo 8704 ;;
+        q4_0) echo 5120 ;;
+        *) return 1 ;;
+    esac
+}
+
 # run_stage — exec the CURRENT $STAGE/test.env as-is. serve_argv REWRITES
 # that file from the shipped env, so any test that mutates it (drop a line,
 # append a drafter) must exec through this, not serve_argv — which silently
@@ -126,7 +143,7 @@ run_stage() {
     done
 }
 
-@test "three conversations share the pool at a 262144 window each" {
+@test "two conversations share the pool at a 262144 window each" {
     serve_argv
     [ "$status" -eq 0 ]
     [ "$(argv_value --alias)" = "frank-zealot" ]
@@ -134,15 +151,13 @@ run_stage() {
     [ "$(argv_value --host)" = "0.0.0.0" ]
     [ "$(argv_value --model)" = "$MODEL_DIR/$MODEL_STUB" ]
     [ "$(argv_value --n-gpu-layers)" -gt 0 ]
-    # llama.cpp divides --ctx-size across slots, so the observable contract
-    # is the per-slot window. The 9B swap exists precisely so every
-    # conversation gets the model's TRAINED 262,144 (the 27B had to be cut to
-    # 200,704 to fund two), and the harness contextWindow must quote 262144 —
-    # the pool and the slot count are neither, and a longer prompt is a 400.
-    # Three is also the ceiling: a fourth slot would push each window under the
-    # fleet's worst-case compaction input, which is this endpoint's job.
-    [ "$(argv_value --parallel)" -eq 3 ]
-    [ "$(argv_value --ctx-size)" -eq 786432 ]
+    # llama.cpp divides --ctx-size across slots, so the observable contract is
+    # the per-slot window. Exact KV costs the SLOT COUNT, not the window: every
+    # conversation still gets the model's TRAINED 262,144, and the harness
+    # contextWindow must quote that number — the pool and the slot count are
+    # neither, and a longer prompt is a 400, never a truncation.
+    [ "$(argv_value --parallel)" -eq 2 ]
+    [ "$(argv_value --ctx-size)" -eq 524288 ]
     local pool slots
     pool="$(argv_value --ctx-size)"; slots="$(argv_value --parallel)"
     [ $((pool % slots)) -eq 0 ]
@@ -151,15 +166,16 @@ run_stage() {
 
 @test "the KV dtype pair follows the env file and flash-attn stays pinned on" {
     # Asserted against the env rather than a literal so a retune moves one
-    # file, not two. The shipped pair is q8_0/q8_0: this payload bills
-    # 8 full-attention layers × 4 KV heads × 256 dim = 8,192 elements per token
-    # per cache, so f16/f16 would need 26,112 MiB of the 24,123 MiB card while
-    # q8_0 bills 17,408 B/token = 13,056.00 MiB at the 786,432 pool — the
-    # ledger said exactly that, and it is the referee. The 24 DeltaNet layers
-    # bill a fixed recurrent state per slot (452.25 MiB for three cells), which
-    # is why pool arithmetic alone under-prices the shape. flash-attn is not
-    # decoration: quantized V is only legal with it, and it must stay explicit
-    # so a future quant swap cannot silently fall back.
+    # file, not two. The shipped pair is f16/f16: exact attention state, and the
+    # slot count is what makes it affordable — this payload bills 8,192 elements
+    # per token per cache (8 full-attention layers × 4 KV heads × 256 dim), so
+    # exact KV is 32,768 B/token = 16,384.00 MiB at the 524,288 pool, where the
+    # q8_0 pair this file used to ship billed 17,408 B/token = 13,056.00 MiB at
+    # the old 786,432 pool (ledger-exact both times). The 24 DeltaNet layers
+    # bill a fixed recurrent state per slot (~50.25 MiB a cell), which is why
+    # pool arithmetic alone under-prices the shape. flash-attn is not
+    # decoration: the quantized-V fallback is only legal with it, so it stays
+    # explicit and a dtype retune cannot silently fall back.
     local env_k env_v
     env_k="$(sed -nE 's/^CACHE_TYPE_K=(.+)$/\1/p' "$ENV_FILE")"
     env_v="$(sed -nE 's/^CACHE_TYPE_V=(.+)$/\1/p' "$ENV_FILE")"
@@ -170,6 +186,38 @@ run_stage() {
     [ "$(argv_value --flash-attn)" = "on" ]
 }
 
+@test "the shipped KV dtype and pool actually fit the card this boots on" {
+    # No health gate can see this mistake: llama.cpp sizes the KV pool as
+    # rate × pool-positions and cudaMalloc fails at boot ON THE LIVE ENDPOINT.
+    # The fit is arithmetic off the payload geometry plus the non-KV terms
+    # measured off the boot ledger (weights 2,036.71 + compute buffers 1,409.02
+    # + projector 595 + 248.10 + CUDA context ≈ 460 = 4,749 MiB, dtype- and
+    # slot-independent at this ubatch), plus one ~51 MiB recurrent-state cell
+    # per slot. 24,123 MiB is what the driver leaves addressable (nvidia-smi
+    # reports it as used + free; its total column reads 24,576).
+    local env_k env_v pool slots rate_k rate_v kv total
+    env_k="$(sed -nE 's/^CACHE_TYPE_K=(.+)$/\1/p' "$ENV_FILE")"
+    env_v="$(sed -nE 's/^CACHE_TYPE_V=(.+)$/\1/p' "$ENV_FILE")"
+    pool="$(sed -nE 's/^CTX_SIZE=([0-9]+)$/\1/p' "$ENV_FILE")"
+    slots="$(sed -nE 's/^PARALLEL=([0-9]+)$/\1/p' "$ENV_FILE")"
+    rate_k="$(kv_bytes_per_token "$env_k")"
+    rate_v="$(kv_bytes_per_token "$env_v")"
+    kv="$(( pool * (rate_k + rate_v) / 1048576 ))"
+    total="$(( kv + 4749 + 51 * slots ))"
+    # The shipped arm has to leave real room: the projector's worst case is
+    # charged AFTER the engine's own fit check, so a projection that lands on
+    # the ceiling is a crash waiting for the first image request.
+    [ "$total" -le $(( 24123 - 1024 )) ]
+
+    # And the gate must be able to REFUSE: the same exact KV at the pool this
+    # shape left behind is 24,576 MiB of cache alone — a boot that dies before
+    # /health ever answers. Proving the gate bites is what makes passing one
+    # meaningful.
+    local over
+    over="$(( 786432 * (rate_k + rate_v) / 1048576 + 4749 + 51 * 3 ))"
+    [ "$over" -gt 24123 ]
+}
+
 @test "log verbosity follows the env file" {
     serve_argv
     [ "$status" -eq 0 ]
@@ -233,10 +281,11 @@ run_stage() {
     # Frank, 2026-10-18: this file DOES carry the MTP head (the boot arms prove
     # it loads and drafts, acceptance 0.798/0.617 per position, mean accepted
     # length 2.41) and it is still off, because the draft context bills its own
-    # f16 KV over the WHOLE pool — 4,096 B/position × 786,432 = 3,072 MiB plus
-    # buffers — and at --ubatch-size 2048 that squeeze halves decode: 167.2 →
-    # 109.2 t/s. The MTP arm is SPEC_TYPE=draft-mtp + UBATCH_SIZE=1024 (213.5
-    # t/s), documented in frank-zealot.env. The flags move as a set:
+    # f16 KV over the WHOLE pool — 4,096 B/position × 524,288 = 2,048 MiB plus
+    # buffers — on a trunk that already projects 21,234 MiB with exact KV. The
+    # MTP arms in frank-zealot.env are all q8_0-era measurements; the doors back
+    # to the drafter are one window per conversation, or KV back to q8_0 with
+    # UBATCH_SIZE=1024 (213.5 t/s). The flags move as a set:
     # SPEC_TYPE=none strips --spec-type, --spec-draft-n-max AND
     # --spec-draft-model together, so a no-spec boot cannot carry half a spec
     # pair (the ROCmFPX-era baseline arm segfaulted at load doing that).
@@ -276,7 +325,7 @@ run_stage() {
     # The Bonsai-2 text file carries no vision tensors — the publisher's Q8_0
     # projector argument IS the vision capability: no flag, no eyes. Q8_0 (not
     # BF16) is the publisher's own requirement for concurrent image requests,
-    # which is what --parallel 3 means in practice.
+    # which is what --parallel 2 means in practice.
     serve_argv
     [ "$status" -eq 0 ]
     [ "$(argv_value --mmproj)" = "$MODEL_DIR/$MM_STUB" ]

tests/voice_pack_unit.bats

@@ -0,0 +1,268 @@
+#!/usr/bin/env bats
+# Seam: the voice-pack builder (scripts/build-voice-pack.sh).
+#
+# The contract this pins is the one frank-tts's packs live or die by. A crop is
+# only usable voice material if it starts PAST the first 10 seconds of the
+# source file — the project-wide source-material invariant — and this builder is
+# the thing that enforces it, because nothing downstream looks at offsets again.
+# A pack is three files plus provenance: reference.wav at 24 kHz mono inside the
+# 18-25 s window, the engine's own speaker artifacts beside it, and a
+# manifest.json whose sha256 still matches the bytes the crop came from. Builds
+# refuse to clobber what is already on disk, and --force retires rather than
+# deletes.
+#
+# No engine binary, no model, no GPU, no network and no fleet host: the crop is
+# cut from a locally generated tone and the pinned extractor is stood in by a
+# stub that mirrors the real tool's I/O shape (no -o flag: outputs named next to
+# the input with the extension swapped, at the sizes the codec's config
+# implies), which is how frank_tts_unit.bats drives its backends too.
+
+load helpers
+
+setup() {
+    BUILDER="$REPO_ROOT/scripts/build-voice-pack.sh"
+    ENV_FILE="$REPO_ROOT/scripts/voice-packs.env"
+    TEST_TMP="$(mktemp -d)"
+    PACKS="$TEST_TMP/packs"
+    mkdir -p "$PACKS"
+    STUB_ARGV="$TEST_TMP/stub-argv.tsv"
+    export STUB_ARGV
+
+    # Forty seconds of "recording": stereo 44.1 kHz, so a legal build has to
+    # downmix and resample just as it does on a real audiobook. Every crop this
+    # file takes starts at or past 12 s, well out of the forbidden region.
+    ffmpeg -v error -y -f lavfi -i "sine=frequency=330:sample_rate=44100:duration=40" \
+        -ac 2 -c:a pcm_s16le "$TEST_TMP/source.wav"
+    SOURCE_SHA="$(sha256sum "$TEST_TMP/source.wav" | awk '{ print $1 }')"
+
+    write_stub_tool
+    # The shipped tunables file, then the three machine-local overrides that
+    # point the engine at the stub: the real env stays under test.
+    cat "$ENV_FILE" > "$TEST_TMP/env"
+    {
+        printf 'VOICE_PACK_DIR=%s\n' "$PACKS"
+        printf 'VOICE_PACK_TOOL=%s\n' "$TEST_TMP/qwen-codec"
+        printf 'VOICE_PACK_CODEC_MODEL=%s\n' "$TEST_TMP/codec.gguf"
+        printf 'VOICE_PACK_TALKER_MODEL=%s\n' "$TEST_TMP/talker.gguf"
+    } >> "$TEST_TMP/env"
+    printf 'stub-codec-weights\n' > "$TEST_TMP/codec.gguf"
+    printf 'stub-talker-weights\n' > "$TEST_TMP/talker.gguf"
+}
+
+teardown() {
+    rm -rf "$TEST_TMP"
+}
+
+# write_stub_tool — stand-in for qwen-codec. Records what it was handed and
+# writes <input-stem>.spk / <input-stem>.rvq, exactly where the real tool would.
+# STUB_SPK_BYTES lets one test be an engine that changed its x-vector size.
+write_stub_tool() {
+    cat > "$TEST_TMP/qwen-codec" <<'STUB'
+#!/usr/bin/env bash
+set -euo pipefail
+input="" model="" talker=""
+while [ "$#" -gt 0 ]; do
+    case "$1" in
+        --model)  model="$2"; shift 2 ;;
+        --talker) talker="$2"; shift 2 ;;
+        --device) shift 2 ;;
+        -i)       input="$2"; shift 2 ;;
+        *)        shift ;;
+    esac
+done
+printf 'model=%s\ttalker=%s\tinput=%s\n' "$model" "$talker" "$input" >> "$STUB_ARGV"
+[ -n "$input" ] || exit 2
+[ -s "$model" ] || exit 3
+[ -s "$talker" ] || exit 4
+dur="$(ffprobe -v error -select_streams a:0 -show_entries stream=duration -of default=nw=1:nk=1 "$input")"
+frames="$(awk -v d="$dur" 'BEGIN { printf "%d\n", int(int(d * 24000 + 0.5) / 1920) }')"
+head -c "${STUB_SPK_BYTES:-8192}" /dev/zero > "${input%.wav}.spk"
+head -c "$((22 * frames))" /dev/zero > "${input%.wav}.rvq"
+printf '[Stub] Wrote %s.rvq: %d packed bytes\n' "${input%.wav}" "$((22 * frames))" >&2
+STUB
+    chmod +x "$TEST_TMP/qwen-codec"
+}
+
+# build — a real (non-dry) run against the stub tool with the tone as source.
+build() {
+    local voice="$1"
+    shift
+    run "$BUILDER" --env "$TEST_TMP/env" \
+        --source "$TEST_TMP/source.wav" --sha256 "$SOURCE_SHA" "$@" "$voice" "$PACKS"
+}
+
+pack_files() {
+    ls "$PACKS/$1" 2>/dev/null | sort | tr '\n' ' '
+}
+
+@test "a crop offset inside the first ten seconds is refused and names the invariant" {
+    build narrator1 --offset 4.5 --duration 20
+    [ "$status" -ne 0 ] || { echo "$output"; false; }
+    [[ "$output" == *"source-material invariant"* ]]
+    [[ "$output" == *"first 10 s"* ]]
+    # Refused before anything was created, not cleaned up afterwards.
+    [ ! -e "$PACKS/narrator1" ]
+    [ ! -s "$STUB_ARGV" ]
+}
+
+@test "the identical crop at a legal offset builds the whole pack" {
+    build narrator1 --offset 12 --duration 20
+    [ "$status" -eq 0 ] || { echo "$output"; false; }
+    [[ "$output" == *"CROP       12 s .. 32 s"* ]]
+    [[ "$output" == *"VOICE_PACK_BUILT narrator1 $PACKS/narrator1"* ]]
+    [ -f "$PACKS/narrator1/reference.wav" ]
+    [ -f "$PACKS/narrator1/reference.spk" ]
+    [ -f "$PACKS/narrator1/reference.rvq" ]
+    [ -f "$PACKS/narrator1/manifest.json" ]
+}
+
+@test "reference.wav comes out 24 kHz mono pcm inside the 18-25 s window" {
+    build narrator1 --offset 12 --duration 20
+    [ "$status" -eq 0 ] || { echo "$output"; false; }
+    local wav="$PACKS/narrator1/reference.wav"
+    [ "$(ffprobe -v error -select_streams a:0 -show_entries stream=codec_name -of default=nw=1:nk=1 "$wav")" = "pcm_s16le" ]
+    [ "$(ffprobe -v error -select_streams a:0 -show_entries stream=sample_rate -of default=nw=1:nk=1 "$wav")" = "24000" ]
+    [ "$(ffprobe -v error -select_streams a:0 -show_entries stream=channels -of default=nw=1:nk=1 "$wav")" = "1" ]
+    local dur
+    dur="$(ffprobe -v error -show_entries format=duration -of default=nw=1:nk=1 "$wav")"
+    awk -v d="$dur" 'BEGIN { exit !(d >= 18 && d <= 25) }'
+}
+
+@test "the manifest round-trips through jq with offsets and a sha that matches the source" {
+    build narrator2 --offset 15 --duration 22.5
+    [ "$status" -eq 0 ] || { echo "$output"; false; }
+    local manifest="$PACKS/narrator2/manifest.json"
+    jq -e '
+        .voice == "narrator2"
+        and (.crop.offset_seconds == 15)
+        and (.crop.end_seconds == 37.5)
+        and (.reference.sample_rate == 24000)
+        and (.reference.channels == 1)
+        and (.reference.duration_seconds >= 18 and .reference.duration_seconds <= 25)
+        and (.artifacts.engine_commit | test("^[0-9a-f]{40}$"))
+        and (.artifacts.produced == true)
+        and (.invariant.forbidden_source_seconds == 10)
+    ' "$manifest"
+    # The recorded hash is the source's hash, not a hash of something else.
+    [ "$(jq -r .source.sha256 "$manifest")" = "$(sha256sum "$TEST_TMP/source.wav" | awk '{ print $1 }')" ]
+    # The pack's provenance names the tool that made the artifacts and the files
+    # it wrote beside the WAV.
+    [ "$(jq -r .artifacts.tool "$manifest")" = "$TEST_TMP/qwen-codec" ]
+    grep -q "input=$PACKS/narrator2/staging-reference.wav" "$STUB_ARGV"
+}
+
+@test "a wrong pinned sha stops the build before a crop is cut" {
+    run "$BUILDER" --env "$TEST_TMP/env" --source "$TEST_TMP/source.wav" \
+        --sha256 "$(printf '0%.0s' {1..64})" --offset 12 --duration 20 narrator1 "$PACKS"
+    [ "$status" -ne 0 ]
+    [[ "$output" == *"sha256"* ]]
+    [ ! -e "$PACKS/narrator1" ]
+}
+
+@test "a crop that runs off the end of the source is refused" {
+    build narrator1 --offset 30 --duration 20
+    [ "$status" -ne 0 ]
+    [[ "$output" == *"crop would come out short"* ]]
+    [ ! -e "$PACKS/narrator1" ]
+}
+
+@test "a crop under the engine's artifact window is refused before the extractor runs" {
+    # 18.5 s is inside the reference window but packs to 22 * 231 = 5,082 B of
+    # .rvq, under the 5,456 B the pinned codec config produces — the builder
+    # says so rather than running an extractor that would emit it anyway.
+    build narrator1 --offset 12 --duration 18.5
+    [ "$status" -ne 0 ] || { echo "$output"; false; }
+    [[ "$output" == *"5456"* ]]
+    [ ! -e "$PACKS/narrator1" ]
+    [ ! -s "$STUB_ARGV" ]
+}
+
+@test "an extractor whose artifact size changed does not get a published voice" {
+    # The engine-bump case: a 4,096 B x-vector is not the 8,192 B the pinned
+    # encoder emits, so the pack must not reach the state the shim reads.
+    export STUB_SPK_BYTES=4096
+    build narrator1 --offset 12 --duration 20
+    [ "$status" -ne 0 ]
+    [[ "$output" == *"reference.spk"* ]]
+    [ ! -e "$PACKS/narrator1/reference.wav" ]
+    [ ! -e "$PACKS/narrator1/manifest.json" ]
+}
+
+@test "re-running without --force refuses and leaves every byte alone" {
+    build narrator1 --offset 12 --duration 20
+    [ "$status" -eq 0 ] || { echo "$output"; false; }
+    sha256sum "$PACKS"/narrator1/* > "$TEST_TMP/before.sha"
+
+    build narrator1 --offset 12 --duration 20
+    [ "$status" -ne 0 ] || { echo "$output"; false; }
+    [[ "$output" == *"--force"* ]]
+    sha256sum -c --quiet "$TEST_TMP/before.sha"
+    [ "$(find "$PACKS" -name .AGENTTRASH -prune -o -type f -newer "$TEST_TMP/before.sha" -print | wc -l)" -eq 0 ]
+}
+
+@test "--force retires the previous pack instead of deleting anything" {
+    build narrator1 --offset 12 --duration 20
+    [ "$status" -eq 0 ] || { echo "$output"; false; }
+    cp "$PACKS/narrator1/reference.wav" "$TEST_TMP/first-reference.wav"
+
+    build narrator1 --offset 12 --duration 20 --force
+    [ "$status" -eq 0 ] || { echo "$output"; false; }
+    [[ "$output" == *"RETIRED"* ]]
+    # The old bytes survive, whole, under the trash directory beside the pack.
+    local retired
+    retired="$(find "$PACKS/.AGENTTRASH" -name reference.wav | head -n1)"
+    [ -n "$retired" ]
+    cmp "$retired" "$TEST_TMP/first-reference.wav"
+    [ -f "$PACKS/narrator1/reference.wav" ]
+}
+
+@test "--dry-run needs no extractor at all" {
+    # Everything up to the engine: the gate, the crop, the probe, the plan and
+    # the manifest it would write — with the tool path pointed at nothing.
+    run "$BUILDER" --env "$TEST_TMP/env" --tool "$TEST_TMP/no-such-tool" \
+        --source "$TEST_TMP/source.wav" --sha256 "$SOURCE_SHA" \
+        --offset 12 --duration 20 --dry-run narrator1 "$PACKS"
+    [ "$status" -eq 0 ] || { echo "$output"; false; }
+    [[ "$output" == *"not present"* ]]
+    [ ! -e "$PACKS/narrator1" ]
+    [ ! -s "$STUB_ARGV" ]
+    printf '%s\n' "$output" | awk '/^MANIFEST_BEGIN$/{p=1;next} /^MANIFEST_END$/{p=0} p' \
+        | jq -e '.voice == "narrator1" and .crop.offset_seconds == 12 and .artifacts.produced == false'
+}
+
+@test "a name the façade could not resolve is refused" {
+    # app.py matches the directory name verbatim while the engine lowercases
+    # names, and a slash would escape $VOICES_DIR: both are refused here, at the
+    # only moment anyone can still fix them.
+    for bad in 'Narrator1' '../evil' 'voice name'; do
+        run "$BUILDER" --env "$TEST_TMP/env" --source "$TEST_TMP/source.wav" \
+            --offset 12 --duration 20 "$bad" "$PACKS"
+        [ "$status" -ne 0 ] || { echo "accepted '$bad': $output"; false; }
+        [[ "$output" == *"voice name"* ]]
+    done
+    [ ! -e "$PACKS/Narrator1" ]
+    [ ! -e "$PACKS/evil" ]
+}
+
+@test "every crop in the tracked pack list clears the invariant" {
+    # The law applied to the values the repo actually ships: no pack may be
+    # described by an offset inside the forbidden region, a length outside the
+    # reference window, or a source with no digest to verify it against.
+    set -a
+    # shellcheck disable=SC1090
+    source "$ENV_FILE"
+    set +a
+    local checked=0 pack upper
+    read -r -a packs <<<"$VOICE_PACKS"
+    for pack in "${packs[@]}"; do
+        upper="$(printf '%s' "$pack" | tr '[:lower:]' '[:upper:]')"
+        local offset_var="VOICE_PACK_${upper}_OFFSET" duration_var="VOICE_PACK_${upper}_DURATION"
+        local sha_var="VOICE_PACK_${upper}_SHA256" source_var="VOICE_PACK_${upper}_SOURCE"
+        [ -n "${!source_var:-}" ] || { echo "$pack has no source path"; false; }
+        printf '%s' "${!sha_var}" | grep -Eq '^[0-9a-f]{64}$' || { echo "$pack has no pinned sha256"; false; }
+        awk -v o="${!offset_var}" 'BEGIN { exit !(o >= 10) }' || { echo "$pack crops at ${!offset_var} s, inside the forbidden first 10 s"; false; }
+        awk -v d="${!duration_var}" 'BEGIN { exit !(d >= 18 && d <= 25) }' || { echo "$pack crops ${!duration_var} s, outside 18-25 s"; false; }
+        checked=$((checked + 1))
+    done
+    [ "$checked" -gt 0 ]
+}