docs(frank-tts): the worklog wikilink must not straddle a line break

The vault link check reads [[Frank TTS Engine]] literally, so wrapping it made the target "Frank\nTTS Engine" and the unresolved-link seam failed. Rewrapped, not reworded.
docs(frank-tts): worklog entry for the voice-stack audit
2026-10-18 18:10:25 -07:00 · 2026-10-18 18:10:02 -07:00 · 2026-10-18 18:07:19 -07:00 · 2026-10-18 18:06:43 -07:00 · 2026-10-18 18:06:06 -07:00 · 2026-10-18 18:05:07 -07:00
22 changed files with 2500 additions and 27 deletions
@@ -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"]
@@ -0,0 +1,112 @@
+# 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.
+#
+# COLD-VOICE LAW, THE REASON EXECSTARTPOST EXISTS. The FIRST speech request for
+# a registered voice decodes the whole reference clip to snapshot codec state:
+# 6.2-8.0 s, first audio byte at 5,530 ms. Every later request restores the
+# snapshot in 0.5 ms. So the unit warms every voice at boot, serially (~6-8 s
+# each), and `TimeoutStartSec=900` is what keeps a growing voice 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 one cold decode per registered voice.
+TimeoutStartSec=900
+ExecStartPost=-/usr/bin/podman exec frank-tts-engine /app/warm-voices.sh
+
+[Install]
+WantedBy=default.target
@@ -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
@@ -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,26 @@
 # 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 warm voice
+# registry instead of paying the 5.5 s cold decode.
 #
 # 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 +51,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
@@ -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"
@@ -0,0 +1,201 @@
+#!/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 cold-voice law). The FIRST speech request for a
+# registered voice decodes the whole reference clip to snapshot its codec state:
+# 6.2-8.0 s, first audio byte at 5,530 ms. Every later request for that voice
+# restores the snapshot in 0.5 ms. Two facts make that a boot problem rather than
+# a curiosity: the voice registry is MEMORY ONLY (a restart forgets every voice),
+# and re-registering a voice does not warm it — only synthesizing does. So a boot
+# that registers the voices and stops leaves the first caller of the day paying
+# 5.5 s of silence. This script speaks one short sentence per voice instead, then
+# speaks a second one so the journal carries the warm number too: the line
+# `voice <name> cold=…ms warm=…ms` is the repo's standing proof that the second
+# request of a voice answers well under a second.
+#
+# 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 straight into the request body without ever being echoed.
+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//\"/\\\"}"
+
+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
+
+    body="$(printf '{"name":"%s","wav_b64":"%s"}' "$name" "$(base64 -w0 "${dir}reference.wav")")"
+    if ! code="$(curl -sS --max-time "$REQUEST_TIMEOUT" -o /dev/null -w '%{http_code}' \
+            -H 'Content-Type: application/json' --data-binary "$body" \
+            "${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"
@@ -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
@@ -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.
@@ -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 ;;
@@ -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|\
@@ -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"
@@ -0,0 +1,148 @@
+# 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 COLD-VOICE LAW (why the unit has an ExecStartPost at all). The first
+# speech request for a registered voice decodes the ENTIRE reference clip to
+# snapshot its codec state: 6.2-8.0 s total, first audio byte at 5,530 ms. Every
+# later request for that voice restores the snapshot in 0.5 ms. Registrations
+# live in memory only, so a restart loses them and re-registration alone does
+# NOT warm the voice — the warm pass has to synthesize something. So
+# dankclaw/voiceservice/tts-engine-warm.sh (in the image at
+# /app/warm-voices.sh) runs on every start and speaks one short sentence per
+# voice. Skip it and the first person to ask for audio that day waits 5.5 s in
+# silence. It 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 — one cold decode per voice, 6-8 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
@@ -30,21 +30,30 @@
 #
 # 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 why an
+#                  unwarmed voice costs the first caller 5.5 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

 # CLI-backend knobs, inert while TTS_BACKEND=omni-http. Empty means "not
@@ -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
@@ -0,0 +1,131 @@
+---
+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 — repo-owned, not yet deployed."
+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.
+
+**Nothing here is deployed.** This page documents repo-owned configuration — the Quadlet unit and network, the image build, the weight fetcher, the boot warmer, the deployer path — and the measured facts those files were written against. No container, image, weight file or network exists on Dankclaw yet, and the engine publishes no port at all, so there is nothing for the homepage checker or a browser to reach. Deploying it is a deliberate next step, in the order at the bottom of this page.
+
+**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 cold-voice law → the unit warms at boot.** The **first** speech request for a registered voice decodes the whole reference clip to snapshot its codec state: **6.2–8.0 s, first audio byte at 5 530 ms**. Every later request for that voice restores the snapshot in **0.5 ms**. Registrations live in memory only — a restart forgets every voice — and re-registering does **not** warm a voice, only synthesizing does. So `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. Without it, whoever asks for audio first that day pays 5.5 s of silence. 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=6821ms warm=412ms
+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`, speak one sentence, 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 cold-voice 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 order (host steps, in order)
+
+Nothing below has been run. Steps 1–5 are this service; 6–7 are what unblocks the podcast pipeline.
+
+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). Builds the image (needs github.com once), installs the unit and the network file, restarts, 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 must name every pack; 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. **Prove the cold-voice law is paid at boot, not by a listener** — two identical synthesis requests for one voice, back to back, from inside the engine's namespace; the **second** must answer well under a second (`warm=` in the journal is already that number; the manual pair is the confirmation on the real artifact).
+6. Then the façade on **7772** (its own page): nothing may be published there until the engine answers, because open-notebook's render fails the moment the façade is up and the engine is not.
+7. Nothing on 7772 exists yet — that is why open-notebook's podcast render cannot run. See [[Open Notebook]].
+
+## 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` |
+| First request of the day is slow, the rest are fast | the warm pass did not run (the hook carries `-`, so it cannot fail the unit) | look for `did not answer` in the journal — the warmer gave up while the model was still loading |
+| 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 |
@@ -0,0 +1,152 @@
+---
+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; repo-owned, not yet deployed."
+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.
+
+**Nothing here is deployed.** No host was touched while this was written: no
+image built, no container started, nothing listening on 7772. That is also why
+[[Open Notebook]] cannot render a podcast episode yet — its pipeline calls 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`) |
+| 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.
+
+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 — 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 is
+gated `wip: down` until the deploy and probes `127.0.0.1:7772`.
+
+## 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 takes ~5.5 s | the warm pass did not run — cold-voice law in [[Frank TTS Engine]] |
+| The unit never appears after a deploy | the generator dropped it: `frank-tts-engine.network` is missing from `~/.config/containers/systemd/` |
@@ -197,10 +197,16 @@ loud, not a bug. Work through it in order:
   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
-   restart the engine rather than using the warm hook: the hook only registers
-   packs it has **not** seen, and every voice here is already registered against
-   the old artifacts. `systemctl --user restart frank-tts-engine.service`
-   re-warms them all from the new bytes.
+   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
@@ -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:
@@ -80,6 +80,8 @@ 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; repo-owned config, not deployed
+- [[Frank TTS]] — the 7772 cloned-voice endpoint consumers address: voice naming, pack layout, why the upstream is a container name; repo-owned config, not deployed
 - [[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
@@ -2442,6 +2442,101 @@ every restart since the cutover.
  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):
@@ -2494,3 +2589,57 @@ every restart since the cutover.
  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.
@@ -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>
@@ -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. Public on 7772; the engine behind it (frank-tts-engine) is unpublished on purpose. Hidden until deployed.",
+    "url": "",
+    "docs": "",
+    "probe": "127.0.0.1:7772",
+    "method": "http",
+    "wip": "down",
+    "showLink": false,
+    "art": "/img/apps/mono-ft.svg"
  }
 ]
@@ -0,0 +1,946 @@
+#!/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 "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 here is the day's first
+    # caller paying 5.5 s of silence for a voice nobody warmed.
+    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 card for the pair, and it is hidden while undeployed" {
+    # 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.
+    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"] == "down" and fts["showLink"] is False, \
+    "nothing listens on 7772 until the deploy, so a visible card reads as down forever"
+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"
+}
Author	SHA1	Message	Date
Frank	6956189bb6	docs(frank-tts): the worklog wikilink must not straddle a line break The vault link check reads [[Frank TTS Engine]] literally, so wrapping it made the target "Frank\nTTS Engine" and the unresolved-link seam failed. Rewrapped, not reworded.	2026-10-18 18:10:25 -07:00
Frank	3380b7da10	docs(frank-tts): worklog entry for the voice-stack audit Three faults, all of the reporting-success-while-doing-nothing species: the build that could not start (no adduser in the base), the warm pass that could not warm (podman's --env-file keeps the quotes), and the image that would never rebuild (cfhash over the Containerfile alone). Records the proofs, the two behaviour seams, and what stays undone: nothing is deployed, #2 phase 1 stays open until 7772 answers.	2026-10-18 18:10:02 -07:00
Frank	7178e1c789	docs(frank-tts): what makes a locally built voice image stale, and what the warm text must survive Three pages, all from faults found this session: - `LLM/deployment.md` gains "Locally built images": which images have no registry digest, what the `cfhash` skip is for, why it must cover every COPY'd file (the silent shape: build skipped, /health green, old code serving), and the base-image half of the law — the engine's `useradd`, because the pinned ubuntu:24.04 has no `adduser`. - `Dankclaw/Frank TTS Engine.md` troubleshooting gains the two lines an operator actually needs: every voice cold on a fresh boot with a hand-run hook succeeding (= `WARM_TEXT` arrived quoted, `podman exec … env \| grep WARM_TEXT` proves it), and a 502 from the façade beside a 200 `/health` from the engine (model loaded ≠ voices registered). The stale-warmer row is re-keyed to the new rebuild rule. - `Dankclaw/Voice Packs.md` step 4 was wrong: it told the next agent to restart the engine instead of the warm hook because the hook "only registers packs it has not seen". It registers every pack on every run and 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." A restart is what an engine bump needs (the registry is memory-only), never worse, only slower. - `Dankclaw/Frank TTS.md` deploy command re-keyed to `./scripts/deploy.sh dankclaw --service frank-tts`, the way it is actually deployed; the raw `deploy-remote.sh` form is plumbing.	2026-10-18 18:07:19 -07:00
Frank	59e021da2c	fix(deploy): hash every file a locally built image COPYs, not just its Containerfile build_compose_image skips `podman build` when the installed image's `cfhash` label matches a hash taken from the checkout now — the skip is what keeps frank-tts-engine's ten-minute recursive source clone off every re-deploy. The hash covered the Containerfile ALONE, so any change to a file the image COPYs was invisible: edit dankclaw/voiceservice/app.py or tts-engine-warm.sh, re-run the deploy, and podman reports the existing image is fine. The redeployed container runs the previous code, /health answers 200, and the e2e gate has no way to see it. It bit the boot warmer twice this week. Each case arm now names its own extra=(…) — the paths its Containerfile COPYs — and the label hashes the Containerfile plus those. The two arms are kept apart deliberately: the façade bakes app.py and tts-start.sh, the engine bakes tts-engine-start.sh and tts-engine-warm.sh, and comfyui/loki/alloy have no extra files, so their hash is unchanged and they do not rebuild on this commit. Hashing rather than word-splitting because these are repo-relative paths under a fixed checkout root. The seam drives the real function against a stub podman and asserts observable output — did the deploy ask podman to build, or did it skip? — in five steps: first deploy builds, unchanged tree does not, editing the engine's COPY'd warm hook rebuilds the ENGINE image and not the façade, editing app.py rebuilds the façade. Reverted scripts/deploy-remote.sh to prove it red on the old hash: the warm-hook step is exactly where it fails.	2026-10-18 18:06:43 -07:00
Frank	d336bdaa66	fix(frank-tts): make the boot warm pass survive both readers of its env `WARM_TEXT` reaches the container with its quotes. The unit reads the env file through podman's `--env-file`, which takes the literal remainder of the line — no shell parsing — while bash `source` strips one layer. The hook interpolated the raw value into the synthesis body, so with the quotes intact the JSON was invalid and every voice logged "registered, but the warm synthesis failed" while a hand-run hook (bash shape) succeeded. Reproduced both ways against a real `podman run --env-file`, not by reading the man page. The hook now strips exactly one matched pair — only when both ends are the same quote AND the inner content carries another quote or a backslash, so a value that legitimately contains quotes is never mangled — and then JSON-escapes what is left, which is what makes a sentence like `He said "hi\" once"` arrive as itself instead of corrupting the body. The seam gains a test that reads `scripts/frank-tts-engine.env` BOTH ways — `source` and the way `podman --env-file` does — and asserts the engine receives the same sentence either way, in both shapes. A test that only sources the file cannot see this bug, which is how it survived the first deploy.	2026-10-18 18:06:06 -07:00
Frank	d135ae7f02	fix(frank-tts): create the engine user with useradd — the base has no adduser The runtime stage of Containerfile.engine ran `adduser --system …`. The pinned ubuntu:24.04 base ships no adduser, so the build died at that RUN line with crun's "executable file not found in $PATH". Verified in the base itself on Dankclaw, 2026-10-18: `command -v adduser` prints nothing, and the exact replacement line — `useradd --system --uid 10000 --home-dir /app --shell /usr/sbin/nologin tts` — answers `uid=10000(tts) gid=999(tts)`. Same account as before: numeric uid/gid 10000, non-login shell, no password entry. Its one warning ("uid 10000 is greater than SYS_UID_MAX 999") is cosmetic and is what keeps the uid equal to the façade's, so the comment says so before someone "fixes" it by dropping --system.	2026-10-18 18:05:07 -07:00
Frank	c1087f214e	docs(frank-tts): plain wikilink to the merged voice-pack page	2026-10-18 17:44:43 -07:00
Frank	1312c29fe2	Merge remote-tracking branch 'origin/main' into feat/frank-tts-engine # Conflicts: # serverAppConfigs-docs/index.md # serverAppConfigs-docs/log.md	2026-10-18 17:44:31 -07:00
Frank	8fefe6e1a9	feat(frank-tts): deploy wiring for the 7772 voice endpoint, and voice naming written down Stage 2 of the voice stack. Repo state only: nothing deployed, no host touched, no container started. - `frank-tts` is now registered everywhere a dankclaw service has to be: `SERVICE_ORDER` (after `frank-tts-engine`, before the consumers), the planner's dankclaw set, `deploy-remote.sh`'s allowlist + dispatch + a `deploy_frank_tts` handler, and `deploy.sh`'s dispatch regex — plus the `build_compose_image` arm naming `dankclaw/voiceservice/Containerfile`, without which the build silently returns 0 and the unit's `Pull=never` tag never exists. - The unit joins TWO networks, in order: `dankclaw_default` first (default route, where consumers and open-notebook live), then the voice bridge. `TTS_UPSTREAM` moves from `host.containers.internal:8880` to `http://frank-tts-engine:8880` — the actual fix for a shape that could never work, since a bridge container cannot reach a host-loopback bind and the engine publishes nothing at all. - `Wants=`/`After=` on the engine, never `Requires=`: the `llama-tts-cli` rollback backend needs no upstream, so a broken engine may delay this endpoint but must not take its unit down. - The handler installs the engine's quadlet pair too, because a referenced `Network=` file the generator cannot find means no façade unit is produced at all, and `--only frank-tts` has no other way to get it. It creates `/home/dank/voices` as the deploy user (rootless podman would auto-create a missing bind source root-owned, which reads as "no voices"), and gates on podman's recorded health. - Voice naming is now written down where it can be found: a voice is a lowercase directory name matching `^[a-z0-9][a-z0-9._-]$`, at most 64 chars. That shape is the intersection of two rules that disagree — the shim would accept mixed case, the engine lowercases names — so a mixed-case pack resolves on one side only, and the boot warmer refuses it loudly. `narrator1/2/3` are load-bearing for open-notebook. - Homepage card for the pair, `wip: down` and hidden, probing `127.0.0.1:7772`; the engine gets no card because it publishes nothing and could never be probed. - No Prometheus job, deliberately.* No `/metrics` exists on the shim, this Prometheus 3 refuses HTML/JSON bodies (the existing `comfyui` and `services` probes are documented down for exactly that), and `LlmEndpointDown` is scoped `up{job=~"frank-.*"}` — so a `/health` job would page on Signal for a healthy endpoint. Recorded in the page instead of quietly skipped. - Vault: new [[Frank TTS]] page linked from the index; [[Frank TTS Engine]] now points at it for the pair's public signal; log entry for the day. - Seam grows to 25 tests: the generator's rendering of the pair (both attachments, first-network order, one publish, Wants-not-Requires, bounded per-unit blocks), the env file's upstream checked as a network JOIN rather than a string, planner separation and order, the handler's steps, the card's gating, routing that selects both seams for either deployable.	2026-10-18 17:43:08 -07:00
dank	d421cb69cf	Merge pull request 'feat(voice-packs): the builder that turns a crop into a deployable voice pack' (#13 ) from feat/voice-pack-builder into main	2026-10-18 17:41:11 -07:00
Frank	8d76854a1e	feat(frank-tts-engine): the arm A engine as a boot-persistent quadlet unit Repo state only: nothing deployed, no host touched, no container started. - `frank-tts-engine` on Dankclaw: `qwentts.cpp` commit 5916bf7c79dbb4e66fc059cdc507a79a23a28bb4, resident `tts-server`, 1.7 B base talker Q4_K_M + Q8_0 tokenizer, container port 8880. It is deliberately NOT a fleet endpoint — `frank-tts` on 7772 is the endpoint consumers address. - Publishes NOTHING. A host-loopback publish would have been useless to the façade (netavark DNATs published ports only, so a bridge container cannot reach a host loopback bind — the shape that 502'd hermes) and would have been the one LAN-reachable surface of an unauthenticated synthesiser. Both voice containers sit on one committed quadlet network, `frank-tts-engine.network` pinned to 10.89.5.0/24 (next free /24 after open-notebook's 10.89.4.0/24), and peers address the engine by container name. Diagnostics and the deployer's health gate run inside the netns (`podman exec`, `wait_container_healthy`). - Cold-voice law honoured in the unit: the first request for a registered voice decodes its whole reference to snapshot codec state (6.2-8.0 s, first audio byte 5 530 ms), later ones restore in 0.5 ms, and the registry is memory-only. `ExecStartPost=-/usr/bin/podman exec frank-tts-engine /app/warm-voices.sh` with `TimeoutStartSec=900`; the `-` prefix keeps a failed warm from crash-looping the endpoint under `Restart=always`. It logs cold=/warm= per voice, so the under-a-second second request is proven on every boot. - Thread law recorded: `tts-server` has no `--threads`; src/backend.h uses hardware_concurrency()/2, so a cpuset pin silently changes the thread count. - Image builds from the pinned commit with the proven line (GGML_BLAS=OFF forced by this host, every GPU backend off, -j 8, no -DGGML_NATIVE because ggml defaults to -march=native for the building host). Two stages; the runtime stage COPYs both the entrypoint and the warmer, because a container that publishes nothing is reached with `podman exec`, not a port. - `scripts/download-frank-tts-engine-qwentts.sh` fetches the two GGUFs with byte and LFS-oid checks (talker 1 219 245 248 B, tokenizer 291 150 624 B); the deployer gates on --verify-only instead of pulling 1.4 GiB mid-deploy. - Registered in SERVICE_ORDER, DANKCLAW_SERVICES, the deploy-remote.sh dispatch, its pre-deploy requirement, deploy.sh's regex, the planner's path map (the whole `dankclaw/voiceservice/` tree mapped to nothing before this), and test-changed.sh ABOVE the `dankclaw/.container` case whose `` crosses `/`. - New seam tests/frank_tts_engine.bats (19): the Quadlet generator's own output for network/publish/boot/warm shape, entrypoint 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, the pinned cmake line, and both routing tables. Suite: 422 passed. - Vault: [[Frank TTS Engine]] linked from the index; log.md entry for the day.	2026-10-18 17:26:50 -07:00
				`@@ -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>`