refactor(quant): one corpus plumbing module, and the builders out of main()

The three corpus tools now share scripts/qwen38_common.py: tokenizer load with the
venv guidance, one n_tokens (so a KLD count cannot drift from the corpus it scores),
JSONL read/write, an atomic writer, and refuse(). make-calib-corpus.py's 170-line
main() with three nested closures became classify / split_pools / fragment_text /
build_frags / pack_class / emit_calib / emit_kld / manifest; its magic numbers are
named constants. rechunk-kld-corpus.py's main became validate / cut / rechunk around
a Window record, so the round-trip proof sits in one function that can be tested
without a tokenizer. calib-push.py grew parse_args / load_prompts / push_round, and
a malformed corpus now refuses with a line number instead of raising KeyError.

Parity, measured on dankserver against the pre-refactor scripts at the same seed:
calib.jsonl and kld.jsonl carry identical records in identical order, the manifest
is identical, and the re-chunked corpus is byte-identical (md5 e824e67d...). The one
byte-level change is JSON escaping — write_jsonl emits literal UTF-8, which is what
the re-chunker already wrote; the parsed records do not move.

AGENTS.md

@@ -27,7 +27,7 @@ merge absorbed the former `vllmScripts` repo, history preserved).
 |--------|---------|---------|---------|------|
 | Dankserver | `frank-archon` | radiance, digest-pinned, root unit, TP=2 | publisher `qwen3.8-next-flash-fp8-iq4r-moe.rad` | 7770 |
 | Dankclaw | `frank-dragoon` | halogen-flash-server 0.16.2, digest-pinned, root unit | `qwen38-flash-next-v2-abliterated.hgn` + n-gram + vision tower | 7770 |
-| Dankclaw | `frank-zealot` | llama.cpp PrismML fork build 10777, root unit — the only loader for this payload | Ternary-Bonsai-2-9B PQ2_0 + Q8_0 mmproj | 7771 |
+| Dankclaw | `frank-zealot` | llama.cpp PrismML fork build 10777, root unit — the only loader for this payload | Ternary-Bonsai-2-9B PQ2_0 + Q8_0 mmproj + rank-1 refusal adapter | 7771 |
 
 Payload identity, shape, eras, laws and rollback live in ONE page each:
 [[frank-archon]], [[frank-dragoon]], [[frank-zealot]]. `scripts/<service>.env`
@@ -166,19 +166,22 @@ bare compose container never returned; 2026-09-11: five observability
 services had no units). The observability services now have units under
 `dankclaw/observability/quadlet/` and their compose definitions were removed —
 one owner per container name. The stack is **configured and delivering as of
-2026-09-17**: a Grafana datasource and the `llm-fleet` dashboard are
-provisioned from `shared/grafana/provisioning/`, `shared/prometheus/rules/
-llm-fleet.yml` loads 5 alert rules + 1 recording rule, and firing rules are
+2026-09-17**: Grafana datasources (Prometheus and Loki) and the `llm-fleet`
+dashboard are provisioned from `shared/grafana/provisioning/`, and
+`shared/prometheus/rules/llm-fleet.yml` loads two rule groups — `llm-fleet`
+(llama.cpp/halogen, `llamacpp:*`) and `vllm-fleet` (radiance, `vllm:*`) — alert
++ recording rules, and firing rules are
 delivered: Prometheus → Alertmanager (`dankclaw/observability/quadlet/
 alertmanager.container`, loopback :9093) → host-side Signal relay
 (`scripts/signal-relay.py`, user unit, 192.168.0.143:18093 — the host LAN
 IP, the one bind a container can reach as `host.containers.internal`;
 iptables admits loopback, the host and the podman bridge subnet only) → signal-cli account 318311.
-Prometheus targets read down for structural reasons (HTML-scraped "probes",
-Gitea metrics off); the remedy is a blackbox exporter. `frank-zealot` was down for
-a different reason until 2026-10-18: llama.cpp will not serve `/metrics` at all
-without `--metrics`. See
-`serverAppConfigs-docs/Infrastructure/Observability.md`.
+The former structural target downs (HTML-scraped "probes", Gitea metrics off)
+are retired as of 2026-10-21: HTTP liveness rides a blackbox exporter
+(`shared/blackbox/blackbox.yml`), Gitea serves `/metrics` from its quadlet, and
+every Prometheus job reports up. `frank-zealot` was down for a different reason
+until 2026-10-18: llama.cpp will not serve `/metrics` at all without
+`--metrics`. See `serverAppConfigs-docs/Infrastructure/Observability.md`.
 
 ## Testing
 
@@ -417,16 +420,17 @@ disagrees with it is the bug.
   digest-pinned `ghcr.io/peonist-ai/halogen-flash-server@sha256:0c61bf84…`.
   Engine stdout (the boot ledger: weights, KV pool, clamp) goes to
   `/home/dank/logs/frank_dragoon.log`, NOT the journal.
-- Shape: `HALOGEN_CTX=200704` is the **per-request ceiling** (a longer prompt
-  is a 400, never a truncation); `HALOGEN_KV_SLOTS=2` over ONE
-  `HALOGEN_KV_POOL_POSITIONS=401408` pool — pool positions buy concurrency,
-  the per-request window never moves; `HALOGEN_SPEC_ADAPT=0` keeps the MTP
-  drafter always armed (the adaptive default disarms it and halves decode);
-  server sampler 1.0/0.95/20.
-- Harness contract: `models.yml` `contextWindow: 155648` = ceiling − 45,056.
-  The clamp is `min(45056, window − est − 4096)` and the chars/4 estimate
-  under-counts, so a harness window equal to the ceiling makes every long
-  request a guaranteed 400. Reasoning arrives in `reasoning_content`; the
+- Shape: `HALOGEN_CTX=262144` (the checkpoint's native window) is the
+  **per-request ceiling** (a longer prompt is a 400, never a truncation);
+  `HALOGEN_KV_SLOTS=2` over ONE `HALOGEN_KV_POOL_POSITIONS=401408` pool —
+  pool positions buy concurrency, the per-request window never moves;
+  `HALOGEN_SPEC_ADAPT=0` keeps the MTP drafter always armed (the adaptive
+  default disarms it and halves decode); server sampler 1.0/0.95/20.
+- Harness contract: `models.yml` `contextWindow: 200000` — ~45k+ under the
+  ceiling. The clamp is `min(45056, window − est − 4096)` and the chars/4
+  estimate under-counts (trigger is 95 %), so a harness window at the ceiling
+  makes every long request a guaranteed 400.
+  Reasoning arrives in `reasoning_content`; the
   template rejects `reasoning_effort` outside `xhigh|medium|low`; images are
   OpenAI `image_url` parts (probe ≥256 px); `response_format` unsupported;
   `/completion`, `/ping`, `/props`, `/tokenize` are 404.
@@ -440,7 +444,11 @@ disagrees with it is the bug.
   `prism.hadamard.*` dequant metadata — stock llama.cpp refuses it, and a
   loader ignoring that metadata dequantizes wrong); payload
   `Bonsai2-9B-MTP/…PQ2_0.gguf` + the publisher's **Q8_0** mmproj (the BF16
-  tower can crash the server with concurrent image requests).
+  tower can crash the server with concurrent image requests) + the rank-1
+  refusal-direction adapter applied at load by `--lora-scaled …:1`. The
+  adapter's rollback is `LORA_FILE=` (empty) in the env — one line, no rebuild
+  — and build 10777 is also the gate that lets it load: older forks refuse it
+  with `unsupported prism.hadamard.version: 2`.
 - Shape: `--ctx-size 602112 --parallel 3` = **three conversations at
   200,704 each**, `CACHE_TYPE_K=f16` + `CACHE_TYPE_V=q8_0` (asymmetric: 25,088
   B/token, 14,406 MiB of pool), batch 6144 / ubatch 1024,
@@ -458,12 +466,15 @@ disagrees with it is the bug.
 - Owns: `scripts/frank-archon.env`, `scripts/serve-frank-archon.sh`,
   `scripts/frank-archon.service`, `scripts/ttm-preflight.sh`, template
   `scripts/qwen38-froggeric-v22.5.jinja`; image digest-pinned
-  `stilldeadcode/radiance@sha256:4c3f4845…`; container name = unit name.
-- Shape: TP=2 over `wht6`, `--max-num-seqs 3`, `--max-model-len 200000`,
-  `expert_tiered` placement, 44,928 MiB pinned host pool per rank, VRAM pair
-  `--vram-weights-mib 25600 --vram-kv-mib 5120` (ONE budget: weights + kv ≤
-  30,969 MiB/card), `fp8` KV, MTP depth 2, MNBT 2048, prefix cache 8 GiB host
-  + 64 GiB disk, n-gram table pinned to RAM.
+  `stilldeadcode/radiance@sha256:d590e300…` (radiance 1.8.1); container name = unit name.
+- Shape: TP=2 over `wht6`, `--max-num-seqs 2`, `--max-model-len 200000`,
+  `expert_tiered` placement, 44,928 MiB pinned host pool per rank, `fp8` KV,
+  MTP depth 2, MNBT 2048, `--busy-prefill-chunk auto`, prefix cache 8 GiB host
+  tier only, n-gram table pinned to RAM. The per-card weights/KV split is derived
+  by the engine's budget resolver from `--gpu-headroom-mib`, the cache bound and
+  the host pool; the `--vram-weights-mib`/`--vram-kv-mib` pair and the prefix disk
+  tier are gone (removed at 1.3.0 / 1.8.1) and naming either is a boot refusal,
+  not a no-op.
 - Harness/gate contract: `models.yml` `contextWindow` MUST quote 200,000
   (over-length is refused, never truncated); the ~147 GiB pinned-RAM ledger
   is why this is a root unit, and `ttm-preflight.sh` raises
@@ -796,6 +807,20 @@ dies, its page is destroyed. Rollback is a commit, not a document.
 `serverAppConfigs-docs/index.md` is the locator for every page that survives;
 retired scripts live in `old/` and `.AGENTTRASH/`.
 
+## Agent skills
+
+### Issue tracker
+
+Issues live in Gitea (`dank/serverAppConfigs` on Dankclaw), via its REST API with the stored credential. See `serverAppConfigs-docs/Agent/Issue Tracker.md`.
+
+### Triage labels
+
+The five canonical roles keep their default strings (`needs-triage`, `needs-info`, `ready-for-agent`, `ready-for-human`, `wontfix`). See `serverAppConfigs-docs/Agent/Triage Labels.md`.
+
+### Domain docs
+
+Single-context: root `GLOSSARY.md` + `docs/adr/`, created lazily; this vault stays the owner of operational facts. See `serverAppConfigs-docs/Agent/Domain Docs.md`.
+
 ## Why
 
 Direct edits on the remote drift from version control, and future agents

dankclaw/Caddyfile

@@ -162,6 +162,25 @@ marreta.franksdank.cloud {
 	}
 }
 
+# --- Open Notebook (guarded: Anubis → Authentik; notebook-proxy provider, internal_host caddy:8017) ---
+# The podcast generator. ONE upstream carries the whole app: the image's own
+# Next.js layer rewrites /api/* to the FastAPI beside it (INTERNAL_API_URL,
+# default http://localhost:5055 inside the container), so a browser on this
+# vhost never needs the API port. That is why scripts/open-notebook.env sets
+# API_URL to exactly this origin — left unset, the app auto-detects
+# `<host-you-opened>:5055`, and 5055 on this host belongs to seerr — and why
+# the published API port sits on loopback. App-level login
+# (OPEN_NOTEBOOK_PASSWORD) stays on behind the chain: two owners, edge identity
+# and the app's own session.
+# Dialled by published LAN port, not container name: open-notebook is a
+# rootless quadlet and this Caddy lives in root's storage, so root's DNS does
+# not see the container (the same reason marreta and SearXNG are dialled by IP).
+notebook.franksdank.cloud {
+	reverse_proxy anubis:8923 {
+		header_up X-Real-Ip {remote_host}
+	}
+}
+
 # --- Pi-hole (quadlet on slirp4netns; published 8083) ---
 pihole.franksdank.cloud {
 	basicauth {
@@ -420,6 +439,16 @@ http://:8017 {
 	handle @marreta {
 		reverse_proxy 192.168.0.143:8082
 	}
+
+	@notebook host notebook.franksdank.cloud
+	handle @notebook {
+		# Bare proxy, like ai.franksdank.cloud: the app's SSE answers
+		# (/api/search/ask, chat sessions) stream for minutes through this
+		# same listener with no flush or timeout tuning, so nothing here
+		# needs it — a read/write timeout on the route would be the thing
+		# that cuts them.
+		reverse_proxy 192.168.0.143:8502
+	}
 }
 
 # --- Optional: Jackett ---

dankclaw/authentik/quadlet/authentik-outpost.container

@@ -20,7 +20,7 @@ Wants=authentik-server.service
 
 [Container]
 ContainerName=authentik-outpost
-Image=ghcr.io/goauthentik/server:2026.8.3
+Image=ghcr.io/goauthentik/server:2026.8.3@sha256:ab9b4e8cc4ab3f8d1198d2db6aeea66bafea1963b3f2843589e0d163f97d9849
 Exec=worker
 Network=dankclaw_default
 EnvironmentFile=/home/dank/serverAppConfigs/dankclaw/.env

dankclaw/authentik/quadlet/authentik-postgres.container

@@ -14,7 +14,7 @@ After=network.target
 
 [Container]
 ContainerName=authentik-postgres
-Image=docker.io/library/postgres:16-alpine
+Image=docker.io/library/postgres:16-alpine@sha256:721873c34ceb9f8d8fc265984940dc982404c105f19ad51be9fdc5970a6080ea
 Network=dankclaw_default
 EnvironmentFile=/home/dank/serverAppConfigs/dankclaw/.env
 Environment=POSTGRES_DB=authentik

dankclaw/authentik/quadlet/authentik-server.container

@@ -19,7 +19,7 @@ Wants=authentik-postgres.service
 
 [Container]
 ContainerName=authentik-server
-Image=ghcr.io/goauthentik/server:2026.8.3
+Image=ghcr.io/goauthentik/server:2026.8.3@sha256:ab9b4e8cc4ab3f8d1198d2db6aeea66bafea1963b3f2843589e0d163f97d9849
 Exec=server
 Network=dankclaw_default
 EnvironmentFile=/home/dank/serverAppConfigs/dankclaw/.env

dankclaw/authentik/quadlet/authentik-worker.container

@@ -16,7 +16,7 @@ Wants=authentik-server.service
 
 [Container]
 ContainerName=authentik-worker
-Image=ghcr.io/goauthentik/server:2026.8.3
+Image=ghcr.io/goauthentik/server:2026.8.3@sha256:ab9b4e8cc4ab3f8d1198d2db6aeea66bafea1963b3f2843589e0d163f97d9849
 Exec=worker
 Network=dankclaw_default
 EnvironmentFile=/home/dank/serverAppConfigs/dankclaw/.env

dankclaw/gitea/quadlet/gitea-postgres.container

@@ -15,7 +15,7 @@ After=network.target
 [Container]
 ContainerName=gitea-postgres
 Network=gitea.network
-Image=docker.io/library/postgres:16-alpine
+Image=docker.io/library/postgres:16-alpine@sha256:721873c34ceb9f8d8fc265984940dc982404c105f19ad51be9fdc5970a6080ea
 EnvironmentFile=/home/dank/Containers/gitea/env
 Environment=POSTGRES_USER=gitea
 Environment=POSTGRES_PASSWORD=${GITEA_DB_PASSWORD}

dankclaw/gitea/quadlet/gitea-server.container

@@ -19,7 +19,7 @@ After=gitea-postgres.service network.target
 [Container]
 ContainerName=gitea-server
 Network=gitea.network
-Image=docker.io/gitea/gitea:latest
+Image=docker.io/gitea/gitea:latest@sha256:30777c91280d973fa02be48b1ade735bd6859e8f6f7af3b4444d519437852504
 EnvironmentFile=/home/dank/Containers/gitea/env
 Environment=DATABASE_TYPE=postgres
 Environment=DATABASE_HOST=gitea-postgres
@@ -29,6 +29,13 @@ Environment=DATABASE_PASSWD=${GITEA_DB_PASSWORD}
 Environment=DATABASE_PORT=5432
 Environment=USER_UID=1000
 Environment=USER_GID=1000
+# Prometheus scrapes /metrics over the published LAN port (job "gitea" in
+# shared/prometheus/prometheus.yml). Off, /metrics is a 404 and the target is
+# permanently red (the audit's "disabled metrics" class). 0.0.0.0 binds inside
+# the container; the only route in is this host's published 3000, and the
+# exposed surface is counters only — same posture as the LLM /metrics.
+Environment=GITEA__metrics__ENABLED=true
+Environment=GITEA__metrics__ENABLED_HOST=0.0.0.0
 PublishPort=0.0.0.0:3000:3000
 PublishPort=2222:22
 Volume=/home/dank/Containers/gitea/data:/data

dankclaw/host/halogen-fabric-clock

@@ -0,0 +1,65 @@
+#!/bin/sh
+# halogen-fabric-clock hold | release | status: the AMD GPU's fabric clock (FCLK), held at its top level.
+#
+# On Strix Halo the GPU and the NPU working at the same time can hang the machine, and corrupt the NPU's results,
+# while the GPU's fabric clock changes speed; held at its top level, the two run together cleanly. halogen-flash-server
+# with HALOGEN_NPU_MODELS refuses to start until the clock is held. This holds it: the performance level `manual` and
+# only the top pp_dpm_fclk level, on every amdgpu device that has the control (the GPU and SoC clocks stay automatic).
+# Cost: about 1 W at idle. Run as root; halogen-fabric-clock.service runs `hold` at every boot and after a resume.
+#
+#   hold     hold it (waits up to 60 s for the GPU driver to come up)
+#   release  give it back to the driver (the performance level `auto`)
+#   status   print each device's state; exit 0 when every device is held
+set -u
+SYS="${HALOGEN_SYSFS:-/sys}"
+
+devices() {
+  for d in "$SYS"/class/drm/card*/device; do
+    [ -w "$d/pp_dpm_fclk" ] || [ -r "$d/pp_dpm_fclk" ] || continue
+    [ -e "$d/power_dpm_force_performance_level" ] || continue
+    echo "$d"
+  done | sort -u
+}
+
+held() {   # held DEVICE_DIR: the performance level high, or manual with only the top fclk level selected
+  perf=$(cat "$1/power_dpm_force_performance_level" 2>/dev/null)
+  [ "$perf" = high ] && return 0
+  [ "$perf" = manual ] || return 1
+  top=$(grep . "$1/pp_dpm_fclk" | tail -n 1)
+  [ "$(grep -c '\*' "$1/pp_dpm_fclk")" = 1 ] && [ "${top%\*}" != "$top" ]
+}
+
+cmd="${1:-status}"
+case "$cmd" in
+  hold)
+    n=0
+    while [ -z "$(devices)" ] && [ "$n" -lt 60 ]; do sleep 1; n=$((n + 1)); done
+    [ -n "$(devices)" ] || { echo "halogen-fabric-clock: no amdgpu device with a fabric clock control (pp_dpm_fclk) under $SYS/class/drm" >&2; exit 1; }
+    rc=0
+    for d in $(devices); do
+      lvl=$(grep . "$d/pp_dpm_fclk" | tail -n 1 | cut -d: -f1)
+      # the driver applies the level several seconds after the write, so the read-back waits up to 30 s
+      ok=0
+      if echo manual > "$d/power_dpm_force_performance_level" && echo "$lvl" > "$d/pp_dpm_fclk"; then
+        t=0; until held "$d" || [ "$t" -ge 300 ]; do sleep 0.1; t=$((t + 1)); done
+        held "$d" && ok=1
+      fi
+      if [ "$ok" = 1 ]; then
+        echo "halogen-fabric-clock: $d: held at level $lvl ($(grep . "$d/pp_dpm_fclk" | tail -n 1 | awk '{print $2}'))"
+      else
+        echo "halogen-fabric-clock: $d: could not hold it (level $lvl)" >&2; rc=1
+      fi
+    done
+    exit "$rc" ;;
+  release)
+    for d in $(devices); do echo auto > "$d/power_dpm_force_performance_level" && echo "halogen-fabric-clock: $d: released (auto)"; done ;;
+  status)
+    [ -n "$(devices)" ] || { echo "halogen-fabric-clock: no amdgpu device with a fabric clock control"; exit 1; }
+    rc=0
+    for d in $(devices); do
+      if held "$d"; then echo "$d: held ($(cat "$d/power_dpm_force_performance_level"))"
+      else echo "$d: NOT held ($(cat "$d/power_dpm_force_performance_level"))"; rc=1; fi
+    done
+    exit "$rc" ;;
+  *) echo "usage: halogen-fabric-clock hold | release | status" >&2; exit 2 ;;
+esac

dankclaw/host/halogen-fabric-clock.service

@@ -0,0 +1,19 @@
+# Holds the AMD GPU's fabric clock at its top level at boot and after every resume, for halogen-flash-server with
+# the NPU (HALOGEN_NPU_MODELS): on Strix Halo the GPU and the NPU at once are safe only with that clock held.
+# Install (as root), from this directory:
+#   install -m 755 halogen-fabric-clock /usr/local/sbin/
+#   install -m 644 halogen-fabric-clock.service /etc/systemd/system/
+#   systemctl daemon-reload && systemctl enable --now halogen-fabric-clock.service
+# Check: halogen-fabric-clock status. Undo: systemctl disable halogen-fabric-clock.service, then
+#   halogen-fabric-clock release (or reboot). The unit runs once at boot and once after each resume (a resume can hand
+#   the clock back to the driver); it holds nothing open, so it shows inactive between runs.
+[Unit]
+Description=Hold the AMD GPU fabric clock at its top level (GPU and NPU together)
+After=systemd-modules-load.service suspend.target hibernate.target hybrid-sleep.target suspend-then-hibernate.target
+
+[Service]
+Type=oneshot
+ExecStart=/usr/local/sbin/halogen-fabric-clock hold
+
+[Install]
+WantedBy=multi-user.target suspend.target hibernate.target hybrid-sleep.target suspend-then-hibernate.target

dankclaw/marreta/quadlet/marreta-browser.container

@@ -23,7 +23,7 @@ After=gluetun.service network.target
 [Container]
 ContainerName=marreta_browser
 Network=gluetun.container
-Image=docker.io/lightpanda/browser:nightly
+Image=docker.io/lightpanda/browser:nightly@sha256:979c36ed869f1016b8dcf22939a0633c262f2c30e892a03a9f720eba2ff1931e
 
 [Service]
 TimeoutStartSec=300

dankclaw/marreta/quadlet/marreta.container

@@ -32,7 +32,7 @@ After=gluetun.service marreta-browser.service network.target
 [Container]
 ContainerName=marreta
 Network=gluetun.container
-Image=ghcr.io/manualdousuario/marreta:latest
+Image=ghcr.io/manualdousuario/marreta:latest@sha256:30f2a34567b79b66da794b4b9423751bbbcd07ceff600d9f6a2d219e7e439362
 # Relocate off SearXNG's 8080 inside the shared netns.
 Environment=NGINX_HTTP_PORT=8085
 Environment=APP_NAME=Marreta

dankclaw/observability/quadlet/alertmanager.container

@@ -33,7 +33,7 @@ Wants=network-online.target
 
 [Container]
 ContainerName=alertmanager
-Image=docker.io/prom/alertmanager:latest
+Image=docker.io/prom/alertmanager:latest@sha256:e9733bafb1bdef9b00e25a21f8f99dc26a22224bf16641ad754d1649f4c3357a
 Network=dankclaw_default
 User=0:0
 Exec=--config.file=/etc/alertmanager/alertmanager.yml --storage.path=/alertmanager

dankclaw/observability/quadlet/alloy.container

@@ -1,55 +1,51 @@
-# Quadlet unit: alloy (rootless, boot-persistent).
+# Quadlet unit: alloy (ROOT system service, boot-persistent).
 #
-# Install path on dankclaw: ~/.config/containers/systemd/alloy.container
-# Unit name: alloy.service (container name: alloy)
+# Install path on dankclaw: /etc/containers/systemd/alloy.container
+# Unit name: alloy.service (container name: alloy) — SYSTEM manager, root.
 #
-# Log shipper. This replaces the compose service of the same name in
-# dankclaw/compose.yaml ("Observability" block).
+# WHY ROOT (not rootless, unlike its observability siblings). Alloy reads the
+# host journal. The journal files are root:systemd-journal 0640 (other::---);
+# a rootless container carries no supplementary groups and cannot open them —
+# a rootless read of system.journal returns DENIED (see the Alloy page in the
+# vault). Running as root, one loki.source.journal reads system.journal AND
+# user-1000.journal, so it carries both host logs and the rootless Quadlet
+# containers' logs. Validated 2026-10-20: a root probe read 31,825 journal
+# lines and pushed 26,966 into Loki in 20 s, zero drops.
 #
-# IMAGE. franksdank/alloy is built locally by deploy-remote.sh
-# (build_compose_image) from dankclaw/alloy/Containerfile: upstream
-# grafana/alloy plus a static busybox for the healthcheck. Pull=never keeps a
-# boot from reaching for that local tag at a registry.
+# NETWORK=host. Loki publishes 127.0.0.1:3100 (loopback only) on the host, and
+# no bridge container — rootless or root — can reach the host's loopback, so
+# this unit runs on the host network and pushes to 127.0.0.1:3100. The side
+# effect: the UI must bind loopback too, so Exec sets the listen-addr to
+# 127.0.0.1 (the old rootless unit used 0.0.0.0 only because container loopback
+# was not host loopback; under Network=host they are the same address, so the
+# unauthenticated UI stays loopback-only — nothing off-host reaches it).
 #
-# NETWORK. It joins dankclaw_default so its config's loki.write endpoint
-# resolves the container name loki:3100.
+# THE /etc/machine-id MOUNT IS LOAD-BEARING. sd_journal locates the journal
+# directory by the local machine id; without it the container opens nothing and
+# the journal source reads exactly 0 lines — silently, no error, health green.
+# This mount is the entire reason the pipeline carries data. Never remove it.
 #
-# THE UI PORT EXISTS ON PURPOSE. Alloy's UI listens on the container's own
-# 127.0.0.1 by default and cannot be moved from the config file (alloy 1.x
-# refuses the ui block), so the compose service had no reachable health
-# endpoint at all: the homepage status card for alloy reported "down"
-# continuously and there was nothing for a deploy to wait on. The command
-# below therefore moves the UI to the container's wildcard address and the
-# port is published on host loopback only, which puts alloy in the same class
-# as the other three: reachable from the host, by Caddy over the private
-# network, and by nothing off-host. Alloy has no authentication, which is
-# exactly why it is not published wider.
-#
-# SOURCES. The host journald socket and the host log/container-storage trees
-# are bind-mounted read-only; Alloy tails them and pushes to Loki. The config
-# lives at /opt/alloy/config/config.alloy, installed from
-# shared/alloy/config.alloy on every deploy.
-#
-# ORDERING. Wants/After loki.service: without a reachable Loki, Alloy's write
-# client fails and its log pipeline backs up.
+# IMAGE. Built rootless by build_compose_image alloy, then mirrored into the
+# root image store by the deployer (a root build runs in the build container's
+# own resolver and fails on DNS here). Pull=never: boot must not reach for the
+# local tag at a registry.
 
 [Unit]
 Description=Alloy log shipper (Dankclaw)
-After=network-online.target loki.service
-Wants=network-online.target loki.service
+After=network-online.target
 
 [Container]
 ContainerName=alloy
 Image=localhost/franksdank/alloy:latest
 Pull=never
-Network=dankclaw_default
-Exec=run --server.http.listen-addr=0.0.0.0:12345 /etc/alloy/config.alloy
-PublishPort=127.0.0.1:12345:12345
-Volume=/opt/alloy/config:/etc/alloy
+Network=host
+Exec=run --server.http.listen-addr=127.0.0.1:12345 /etc/alloy/config.alloy
+Volume=/opt/alloy/config:/etc/alloy:ro
+Volume=/etc/machine-id:/etc/machine-id:ro
 Volume=/run/systemd/journal/socket:/run/systemd/journal/socket:ro
-Volume=/var/log:/var/log:ro
-Volume=/var/lib/containers:/var/lib/containers:ro
-HealthCmd=/usr/local/bin/busybox wget --spider -q http://localhost:12345/-/healthy
+Volume=/var/log/journal:/var/log/journal:ro
+Volume=/run/log/journal:/run/log/journal:ro
+HealthCmd=/usr/local/bin/busybox wget --spider -q http://127.0.0.1:12345/-/healthy
 HealthInterval=30s
 HealthTimeout=10s
 HealthRetries=3
@@ -60,4 +56,4 @@ Restart=always
 RestartSec=10
 
 [Install]
-WantedBy=default.target
+WantedBy=multi-user.target

dankclaw/observability/quadlet/blackbox-exporter.container

@@ -0,0 +1,56 @@
+# Quadlet unit: blackbox exporter (rootless, host network, boot-persistent).
+#
+# Install path on dankclaw:
+#   ~/.config/containers/systemd/blackbox-exporter.container
+#
+# WHY Network=host. The probes it runs are (a) the host's own LAN IP
+# (192.168.0.143:8081 SearXNG, :3005 OpenWebUI — host-process/portmap binds a
+# bridge container cannot reach; netavark DNATs published ports only, see
+# Container Host Reachability in the vault) and (b) ComfyUI's published port
+# via 127.0.0.1 (rootless --network=host shares the real host netns, so the
+# 0.0.0.0:8188 publish answers on loopback). A bridge-networked prober could
+# reach neither class reliably.
+#
+# WHY the listener binds 127.0.0.1 + LAN. A bridge container CANNOT dial
+# its own host's LAN IP (netavark hairpin gap, measured 2026-10-21), but a
+# bridge container dialing the podman gateway 169.254.1.2 lands on the host
+# LOOPBACK — that is the scrape path, and it needs this exporter to be
+# LISTENING ON LOOPBACK (proved: 200 from the prometheus container to
+# http://169.254.1.2:9115/-/healthy with a loopback bind). The gateway
+# address itself is NOT bindable from the host netns — it exists only
+# inside each rootless netns; binding it dies "bind: cannot assign
+# requested address" (live 2026-10-21). The LAN bind stays for diagnostics.
+# No public DNS name, no guard chain: internal net only, per the exposure
+# policy. The listen flag is --web.listen-address and it is REPEATABLE, one
+# flag per bind; plain --listen-address does not exist and the exporter
+# exits in 100 ms with "unknown long flag" (live 2026-10-21).
+
+[Unit]
+Description=Blackbox exporter (HTTP probe prober)
+After=network-online.target
+
+[Container]
+Image=docker.io/prom/blackbox-exporter@sha256:ea1c7aa3ef3f307cd03e85f34abb604478ccb90b567fc690da0cd9776da76b13
+ContainerName=blackbox-exporter
+Network=host
+# The image's ENTRYPOINT is /bin/blackbox_exporter itself (proved live
+# 2026-10-21: `podman run IMAGE sh` dies "unexpected sh"), so Exec= carries
+# FLAGS ONLY — repeating the binary makes it a positional arg and kingpin
+# exits "unexpected /bin/blackbox_exporter".
+Exec=--config.file=/etc/blackbox_exporter/config.yml --web.listen-address=127.0.0.1:9115 --web.listen-address=192.168.0.143:9115
+Volume=/opt/blackbox/blackbox.yml:/etc/blackbox_exporter/config.yml:ro
+# Plain exec form like every sibling unit. Shell form (`/bin/sh -c "…"`)
+# is passed as one quoted token and quadlet then folds the following
+# --health-interval/--health-retries (and the image name) into the command
+# string — unit died twice that way, live 2026-10-21. wget only; this
+# busybox variant has no curl, and host-network wget answers on loopback.
+HealthCmd=wget -q -O /dev/null http://127.0.0.1:9115/-/healthy
+HealthInterval=30s
+HealthRetries=3
+
+[Service]
+Restart=always
+RestartSec=5
+
+[Install]
+WantedBy=default.target

dankclaw/observability/quadlet/cadvisor.container

@@ -0,0 +1,56 @@
+# Quadlet unit: cadvisor (rootless, boot-persistent) — DANKCLAW.
+#
+# Install path on dankclaw: ~/.config/containers/systemd/cadvisor.container
+# Unit name: cadvisor.service (container name: cadvisor)
+#
+# WHY THIS EXISTS. The app stack is ~34 rootless Podman containers and until
+# now nothing reported per-container CPU/memory — Grafana could only see the
+# host (node_exporter) and the LLM engines. cadvisor reads the host cgroup
+# tree and exports container_cpu_* / container_memory_* per container.
+#
+# THE LOAD-BEARING FLAG IS --cgroupns=host. Podman starts every container in a
+# PRIVATE cgroup namespace, so an exporter container sees only its OWN cgroup
+# subtree: cadvisor exported a single root series until this flag was added,
+# then it walked the whole tree (996 per-container series measured 2026-10-20).
+# The quadlet unit name is carried in the cgroup path — app.slice/<name>.service/
+# libpod-payload-<hex> — so Prometheus relabels that path into a `container`
+# label (shared/prometheus/prometheus.yml, cadvisor-dankclaw job) and no
+# libpod/podman socket is needed to name containers.
+#
+# BINDING. cadvisor has no per-interface listen flag (unlike node_exporter's
+# --web.listen-address), so it binds 0.0.0.0 INSIDE its own network namespace.
+# The bridge PublishPort is what keeps the unauthenticated endpoint off the
+# host's other interfaces: it publishes exactly loopback (host-local probes and
+# the deployer's health gate) and this host's LAN address (Prometheus, a bridge
+# container, reaches a host-published port at its LAN address — the same netavark
+# rule node-exporter relies on, only here the port really is published).
+#
+# It is rootless on purpose: dank owns the app containers' cgroups, so a
+# rootless cadvisor reads every one of them; root would buy nothing here.
+
+[Unit]
+Description=cAdvisor container metrics (Dankclaw)
+After=network-online.target
+Wants=network-online.target
+
+[Container]
+ContainerName=cadvisor
+Image=gcr.io/cadvisor/cadvisor:v0.49.1@sha256:3cde6faf0791ebf7b41d6f8ae7145466fed712ea6f252c935294d2608b1af388
+PodmanArgs=--pid=host --cgroupns=host
+PublishPort=127.0.0.1:8080:8080
+PublishPort=192.168.0.143:8080:8080
+Volume=/sys:/sys:ro
+Volume=/:/rootfs:ro
+Exec=--housekeeping_interval=30s
+HealthCmd=wget --spider -q http://localhost:8080/healthz
+HealthInterval=30s
+HealthTimeout=10s
+HealthRetries=3
+HealthStartPeriod=40s
+
+[Service]
+Restart=always
+RestartSec=10
+
+[Install]
+WantedBy=default.target

dankclaw/observability/quadlet/grafana.container

@@ -34,7 +34,7 @@ Wants=network-online.target prometheus.service
 
 [Container]
 ContainerName=grafana
-Image=docker.io/grafana/grafana:latest
+Image=docker.io/grafana/grafana:latest@sha256:dbbc38ea21103cefb50396340cd88afec779c7e070b0a7bf5a75b4ce46651d3f
 Network=dankclaw_default
 User=0:0
 PublishPort=127.0.0.1:3002:3000
@@ -47,9 +47,24 @@ Environment=GF_AUTH_GENERIC_OAUTH_CLIENT_SECRET=${GRAFANA_OAUTH_CLIENT_SECRET}
 # client_id query parameter — /application/o/<slug>/authorize/ does not exist.
 Environment=GF_AUTH_GENERIC_OAUTH_AUTH_URL=https://auth.franksdank.cloud/application/o/authorize/
 Environment=GF_AUTH_GENERIC_OAUTH_TOKEN_URL=https://auth.franksdank.cloud/application/o/token/
-# ?api=1 = introspection-style userinfo: returns custom claims (groups) too.
-Environment=GF_AUTH_GENERIC_OAUTH_API_URL=https://auth.franksdank.cloud/application/o/userinfo/?api=1
-Environment=GF_AUTH_GENERIC_OAUTH_ALLOW_SIGN_UP=false
+# Standard OIDC userinfo. Grafana v13 fetches <api_url>/emails for the address
+# ONLY when the token carries no `email` claim (authentik has no /emails path and
+# 404s it, failing the login) — so the claim must actually be there: the fix is
+# the grafana-email-scope mapping (see scripts/authentik-grafana-sso-fix.sh),
+# not a Grafana flag. Do NOT append ?api=1 to this URL: Grafana then GETs
+# <...>/userinfo/?api=1/emails, a 403.
+Environment=GF_AUTH_GENERIC_OAUTH_API_URL=https://auth.franksdank.cloud/application/o/userinfo/
+# authentik's scopes are openid/email/profile. `user:email` (a GitLab-ism) is
+# not a known scope here; requesting it makes the authorize view crash.
+# Quoted: quadlet word-splits Environment=, so an unquoted spaced list
+# truncates SCOPES to its first token.
+Environment="GF_AUTH_GENERIC_OAUTH_SCOPES=openid email profile"
+Environment=GF_AUTH_GENERIC_OAUTH_EMAIL_ATTRIBUTE_PATH=email
+Environment=GF_AUTH_GENERIC_OAUTH_LOGIN_ATTRIBUTE_PATH=sub
+Environment=GF_AUTH_GENERIC_OAUTH_NAME_ATTRIBUTE_PATH=preferred_username
+# First SSO login auto-provisions the user. Safe: unauthenticated traffic never
+# reaches this callback — the Anubis -> Authentik guard fronts every request.
+Environment=GF_AUTH_GENERIC_OAUTH_ALLOW_SIGN_UP=true
 Environment=GF_AUTH_GENERIC_OAUTH_AUTO_UPSERT=true
 Environment=GF_AUTH_GENERIC_OAUTH_ALLOW_ASSIGN_ORG=true
 Environment=GF_AUTH_GENERIC_OAUTH_ORG_ID=1

dankclaw/observability/quadlet/node-exporter.container

@@ -33,7 +33,7 @@ Wants=network-online.target
 
 [Container]
 ContainerName=node-exporter
-Image=docker.io/prom/node-exporter:latest
+Image=docker.io/prom/node-exporter:latest@sha256:1b4e4438faca4dd7e001dd445d161a4a2091b0fededa84093b3a8dfeae1f1be0
 Network=host
 PodmanArgs=--pid=host
 Exec=--path.procfs=/host/proc --path.sysfs=/host/sys --path.rootfs=/rootfs --web.listen-address=127.0.0.1:9100 --web.listen-address=192.168.0.143:9100

dankclaw/observability/quadlet/prometheus.container

@@ -43,8 +43,16 @@ Wants=network-online.target
 
 [Container]
 ContainerName=prometheus
-Image=docker.io/prom/prometheus:latest
+Image=docker.io/prom/prometheus:latest@sha256:fa3302279710be2f21a8301ec17a8b4f2301fd829bd113839b3b6b02b6f191a2
 Network=dankclaw_default
+# Same-host scrape targets are dialed at host.containers.internal (the podman
+# gateway): a bridge container cannot dial its own host's LAN IP (netavark
+# hairpin gap, measured 2026-10-21), and traffic to the gateway lands on host
+# loopback / published ports (cadvisor/gpu jobs and the blackbox scrape all
+# ride it). The name resolves natively — NO HostAddr key: quadlet 5.7.0 calls
+# it unsupported and the WHOLE user quadlet batch then fails to generate,
+# silently orphaning every other unit (live 2026-10-21: prometheus.service
+# vanished while its container kept running as an orphan).
 User=0:0
 Exec=--config.file=/etc/prometheus/prometheus.yml --storage.tsdb.path=/prometheus --storage.tsdb.retention.time=30d --web.enable-lifecycle
 PublishPort=127.0.0.1:9090:9090

dankclaw/open-notebook/quadlet/open-notebook-surrealdb.container

@@ -48,13 +48,22 @@
 # without `podman unshare` — accepted for a datastore nobody edits by hand;
 # episode AUDIO is a host directory for the opposite reason (see the app unit).
 #
-# HEALTH. The base image is distroless: no shell, no curl, no wget, so no
-# CMD-SHELL probe and no wget/curl probe is possible here (same class of unit
-# as loki, whose probe had to move into the image). SurrealDB ships its own
-# probe instead — `surreal is-ready` connects to ws://localhost:8000 by default
-# and needs no credentials — verified against this digest: it prints `OK` and
-# exits 0 while the server is up. Argument-only HealthCmd, like every unit on
-# this host, because the quadlet generator splits it on spaces.
+# HEALTH. The base image is distroless — measured against this digest, not even
+# `ls` exists (`exec: "ls": executable file not found in $PATH`), so there is no
+# `/bin/sh`, no curl and no wget. SurrealDB ships its own probe instead:
+# `surreal is-ready` connects to ws://localhost:8000 by default, needs no
+# credentials, prints `OK` and exits 0 while the server is up.
+#
+# It must be handed over as a QUADLET-SIDE JSON ARRAY, not a bare command.
+# podman wraps a bare `HealthCmd` string as `CMD-SHELL` (measured on this host's
+# podman 5.7: `--health-cmd "/surreal is-ready"` stores
+# `{"Test":["CMD-SHELL","/surreal is-ready"]}`), and with no `/bin/sh` in the
+# image that probe fails in ~30 ms with empty output on every interval while the
+# database answers perfectly — which is exactly how this service's first deploy
+# died on 2026-10-19 (`did not become healthy in 90s`). The quoted array survives
+# the generator (`--health-cmd "[\"/surreal\",\"is-ready\"]"`) and stores
+# `["CMD","/surreal","is-ready"]`, which execs directly and goes healthy. Do not
+# "simplify" it back to a bare command.
 
 [Unit]
 Description=SurrealDB (open-notebook datastore)
@@ -70,7 +79,7 @@ EnvironmentFile=/home/dank/serverAppConfigs/scripts/open-notebook.env
 EnvironmentFile=/home/dank/Containers/open-notebook/env
 Exec=start --log info rocksdb:/mydata/mydatabase.db
 Volume=open-notebook-db:/mydata
-HealthCmd=/surreal is-ready
+HealthCmd=["/surreal","is-ready"]
 HealthInterval=30s
 HealthTimeout=10s
 HealthRetries=3

dankclaw/open-notebook/quadlet/open-notebook.container

@@ -33,17 +33,21 @@
 # and 5055 is exactly the port seerr already holds on this host
 # (`PublishPort=127.0.0.1:5055:5055`; `ss -ltn` on Dankclaw 2026-10-18 shows
 # 127.0.0.1:5055 taken). So the API leaves the container on host port 5056.
-# That forces one setting: the frontend auto-detects the API as
-# `<host-you-opened>:5055`, so API_URL in scripts/open-notebook.env must name
-# the remapped port explicitly, or the UI loads and every call fails. Both
-# ports are published on all interfaces because the consumer is a browser on
-# the LAN — the fleet's browser-facing services (open-webui, comfyui, gitea)
-# bind the same way, while loopback-only is reserved for services whose user
-# path is the guard chain. This service has NO vhost and no Caddy route: it is
-# internal-only until it is guarded, and its own password
-# (OPEN_NOTEBOOK_PASSWORD) is what stands in front of it. That password is not
-# decoration: with it unset the API answers everyone on the LAN, including the
-# unauthenticated episode-audio download.
+# Only 8502 is published on all interfaces, because it is the single upstream
+# the guard chain dials: notebook.franksdank.cloud → anubis → authentik →
+# http://:8017 → 192.168.0.143:8502 (dankclaw/Caddyfile), and this Caddy lives
+# in root's storage, so a published port is the only way it can reach a rootless
+# quadlet. The API needs no outward face at all — the image's own Next.js layer
+# rewrites /api/* to the FastAPI beside it, so one origin serves UI and API —
+# and the fleet's rule is that loopback-only is for services whose user path is
+# the guard chain, which this became on 2026-10-19; 5056 stays published on
+# loopback because the deployer's health gate dials it there. That is also why
+# API_URL in scripts/open-notebook.env names the vhost rather than a port: left
+# to itself the frontend auto-detects `<host-you-opened>:5055`, and the UI loads
+# while every call fails. OPEN_NOTEBOOK_PASSWORD is not made redundant by the
+# chain: it is what keeps the API honest for everything else on this host, and
+# with it unset the API answers anyone, including the unauthenticated
+# episode-audio download.
 #
 # VOLUMES. `/app/data` is a named volume: uploads, the LangGraph SQLite
 # checkpoints and the extraction caches the image keeps under it
@@ -81,7 +85,7 @@ Pull=never
 Network=dankclaw_default
 Network=open-notebook.network
 PublishPort=0.0.0.0:8502:8502
-PublishPort=0.0.0.0:5056:5055
+PublishPort=127.0.0.1:5056:5055
 EnvironmentFile=/home/dank/serverAppConfigs/scripts/open-notebook.env
 EnvironmentFile=/home/dank/Containers/open-notebook/env
 Volume=open-notebook-data:/app/data

dankclaw/open-webui/quadlet/open-webui.container

@@ -27,7 +27,7 @@ After=network.target
 [Container]
 ContainerName=open-webui
 Network=open-webui.network
-Image=ghcr.io/open-webui/open-webui:main
+Image=ghcr.io/open-webui/open-webui:main@sha256:4860ba005ae8f19f08d1e12b0868855b7b339ea0dad9927f196820fc0de04575
 PublishPort=3005:8080
 Environment=OPENAI_API_BASE_URL=http://192.168.0.143:7770
 Environment=ANONYMIZED_TELEMETRY=False

dankclaw/pihole/addn-hosts

@@ -45,3 +45,4 @@
 192.168.0.143 pihole.franksdank.cloud
 192.168.0.143 seerr.franksdank.cloud
 192.168.0.143 marreta.franksdank.cloud
+192.168.0.143 notebook.franksdank.cloud

dankclaw/pihole/quadlet/pihole.container

@@ -24,7 +24,7 @@ Wants=network-online.target
 
 [Container]
 ContainerName=pihole
-Image=docker.io/pihole/pihole:latest
+Image=docker.io/pihole/pihole:latest@sha256:d34134716fc32038b052a8674c7c6879e0ff21f0e6d8af345166fffa2c27c113
 Network=slirp4netns
 PublishPort=0.0.0.0:53:53/udp
 PublishPort=0.0.0.0:53:53/tcp

dankclaw/searxng/quadlet/gluetun.container

@@ -16,7 +16,7 @@ After=searxng-network.service network.target
 [Container]
 ContainerName=gluetun
 Network=searxng.network
-Image=docker.io/qmcgaw/gluetun:latest
+Image=docker.io/qmcgaw/gluetun:latest@sha256:c2ee4191762fca6b6a3c3359a731198a95d9c9af4db32d466e223bf3a84e779b
 AddCapability=NET_ADMIN
 AddDevice=/dev/net/tun:/dev/net/tun
 Environment=VPN_SERVICE_PROVIDER=${VPN_SERVICE_PROVIDER}

dankclaw/searxng/quadlet/searxng-valkey.container

@@ -16,7 +16,7 @@ After=searxng-network.service network.target
 ContainerName=searxng-valkey
 Network=searxng.network
 NetworkAlias=valkey
-Image=docker.io/valkey/valkey:9-alpine
+Image=docker.io/valkey/valkey:9-alpine@sha256:48332870af354a799964c0012ae1194a0bf2bf894eb508f945810596dc2d8d11
 Volume=/opt/searxng/valkey:/data
 
 [Service]

dankclaw/searxng/quadlet/searxng.container

@@ -16,7 +16,7 @@ After=gluetun.service searxng-valkey.service network.target
 [Container]
 ContainerName=searxng
 Network=gluetun.container
-Image=ghcr.io/searxng/searxng:latest
+Image=ghcr.io/searxng/searxng:latest@sha256:5ed0323b5f5f8701264ef65e239a2bd83cb57098f2b971fa30bf79c06eeae271
 Environment=SEARXNG_SECRET=${SEARXNG_SECRET}
 Environment=SEARXNG_BASE_URL=${SEARXNG_BASE_URL}
 Volume=/opt/searxng/config:/etc/searxng

dankclaw/seerr/quadlet/seerr.container

@@ -29,7 +29,7 @@ Wants=network-online.target
 
 [Container]
 ContainerName=seerr
-Image=ghcr.io/seerr-team/seerr:v3.4.1
+Image=ghcr.io/seerr-team/seerr:v3.4.1@sha256:f4768de5f616248d723e05891f3345a1402123775d03bf0890dbfedc0831bda1
 Network=dankclaw_default
 PublishPort=127.0.0.1:5055:5055
 Volume=/home/dank/Containers/seerr/data:/app/config

dankclaw/udev/98-halogen-npu-access.rules

@@ -0,0 +1,26 @@
+# /etc/udev/rules.d/98-halogen-npu-access.rules
+#
+# Why the NPU node is world-writable: `frank-dragoon` runs rootless podman under a
+# unit with `User=dank`, and the container's user namespace maps exactly one uid and
+# one gid (dank). `/dev/accel/accel0` is `root:render 0660`, so inside the container
+# the node reads `nobody:nogroup` and the engine dies with its own diagnosis:
+#
+#   halogen npu: /dev/accel/accel0 is here, but this process cannot open it
+#     (crw-rw---- nobody:nogroup).
+#
+# `--group-add keep-groups` is the vendor's advice and it does NOT work in this
+# shape: measured 2026-10-19 from the host as a `dank` shell that was already in
+# `render`, with and without the flag, the node still read `nobody:nogroup` and the
+# open was refused — an unmapped gid cannot be granted to a process inside a
+# namespace that does not map it. Same conclusion `99-comfyui-gpu-access.rules`
+# reached for `/dev/kfd` from the systemd-user-spawn direction: the mode is the only
+# spawn-context-independent door short of running the stack rootful.
+#
+# Blast radius: any process in this host's single uid domain (every rootless
+# container here shares it) can submit to the XDNA2 NPU. The NPU holds no user data
+# and no privileged context — the same trade already accepted for the GPU compute
+# nodes beside it. Installed by `deploy-remote.sh` when the NPU lane is armed and left
+# in place afterwards — the mode costs nothing while the lane is idle. `serve-frank-dragoon.sh`
+# refuses to arm the lane on a node that is not other-accessible, so a host that lost this
+# file fails loudly at boot instead of crash-looping.
+KERNEL=="accel[0-9]*", SUBSYSTEM=="accel", MODE="0666"

dankclaw/voiceservice/Containerfile.engine

@@ -19,11 +19,14 @@
 # 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:
+# THE BUILD LINE IS THE ONE PROVEN ON DANKCLAW, verbatim — with the Vulkan door
+# open since 2026-10-19. That configure was run in this exact base image and
+# answers `Found Vulkan: /usr/lib/x86_64-linux-gnu/libvulkan.so (found version
+# "1.3.275") found components: glslc` then `Including Vulkan backend`:
 #
 #   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_BLAS=OFF -DGGML_CUDA=OFF -DGGML_HIP=OFF -DGGML_VULKAN=ON \
 #       -DGGML_METAL=OFF -DGGML_SYCL=OFF -DGGML_RPC=OFF \
 #   && cmake --build build -j 8
 #
@@ -42,8 +45,12 @@
 #     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).
+#   CUDA/HIP/METAL/SYCL/RPC stay OFF, VULKAN is ON: the endpoint computes on the
+#     gfx1151 iGPU (decision and co-tenancy gates:
+#     report/tts-npu-spike-verdict-2026-10-19.md, shape in [[Frank TTS Engine]]).
+#     Nothing else is available to this image: no ROCm userland, no NVIDIA
+#     userland, no macOS, no oneAPI, and RPC would add a second process to
+#     supervise on a box that already has one engine per card.
 #
 # 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
@@ -67,9 +74,28 @@ ARG BASE_IMAGE=docker.io/library/ubuntu:24.04@sha256:68ee22004a9109b44973313b02f
 # ------------------------------------------------------------------ build
 FROM ${BASE_IMAGE} AS build
 
+# The three Vulkan build deps are not optional and not interchangeable:
+#   libvulkan-dev    vulkan/vulkan.h + the VulkanHeaders/VulkanLoader CMake
+#                    configs, i.e. what find_package(Vulkan) resolves to.
+#   glslc            ggml compiles its shaders with glslc, not glslangValidator.
+#                    Ubuntu's glslang-tools ships glslangValidator and NOT glslc,
+#                    so without this package `find_package(Vulkan COMPONENTS
+#                    glslc REQUIRED)` fails and there is no Vulkan backend.
+#                    The archive's glslc is old (2023.8): it compiles
+#                    GL_KHR_cooperative_matrix — the path ggml's quantized
+#                    matmul needs — but reports cooperative_matrix2,
+#                    integer_dot_product, bfloat16 and the micro-float
+#                    extensions as unsupported, so those shader families are
+#                    compiled out. If a Vulkan prefill ever reads as
+#                    inexplicably slow, suspect this compiler before the device;
+#                    the fix is a pinned glslang build passed as
+#                    -DVulkan_GLSLC_EXECUTABLE=<path>, not a different runtime.
+#   spirv-headers    find_package(SPIRV-Headers CONFIG REQUIRED); the distro
+#                    package ships /usr/share/cmake/SPIRV-Headers/.
 RUN apt-get update -qq \
     && apt-get install -y -qq --no-install-recommends \
         ca-certificates cmake g++ git make \
+        libvulkan-dev glslc spirv-headers \
     && rm -rf /var/lib/apt/lists/*
 
 # Checked out detached at a full SHA, then the recorded submodule. No branch
@@ -90,7 +116,7 @@ RUN cmake -B build -DCMAKE_BUILD_TYPE=Release \
         -DGGML_BLAS=OFF \
         -DGGML_CUDA=OFF \
         -DGGML_HIP=OFF \
-        -DGGML_VULKAN=OFF \
+        -DGGML_VULKAN=ON \
         -DGGML_METAL=OFF \
         -DGGML_SYCL=OFF \
         -DGGML_RPC=OFF \
@@ -102,9 +128,21 @@ 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.
+#
+# libvulkan1 + mesa-vulkan-drivers are what make `--device Vulkan0` mean
+# anything at runtime: libvulkan1 is the loader libggml-vulkan.so dlopens, and
+# mesa-vulkan-drivers is the RADV ICD that claims the gfx1151. Loader without an
+# ICD enumerates ZERO devices, and tts-server then dies in device lookup AFTER
+# both GGUFs have been read — the journal reads as a model fault, not a missing
+# driver. Enumerated from this base on 2026-10-19 with `--device /dev/dri
+# --group-add keep-groups` plus the host's ComfyUI udev rule: "Radeon 8060S
+# Graphics (RADV GFX1151)", API 1.4.318 (the heap figure is owned by
+# [[Frank TTS Engine]]; it is the GTT-backed aperture, not the ~2 GiB DRM
+# carve-out). No NVIDIA ICD is installed on purpose: one Vulkan device in the
+# enumeration is what makes the NAME Vulkan0 safe to write down.
 RUN apt-get update -qq \
     && apt-get install -y -qq --no-install-recommends \
-        ca-certificates curl libgomp1 \
+        ca-certificates curl libgomp1 libvulkan1 mesa-vulkan-drivers \
     && rm -rf /var/lib/apt/lists/*
 
 # Same unprivileged uid as the frank-tts façade (10000): the voice packs and the

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

@@ -40,12 +40,28 @@
 # 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.
+# MEMORY / THE RENDER NODE. Host RSS is ~1.7 GiB, not the size of the GGUFs:
+# the Vulkan backend copies both tensors into device memory at load, so they
+# stop counting in the process's RSS (measured after the 2026-10-19 cutover —
+# `podman stats` / `ps -o rss`). No memory limit is set: the box has the room
+# and a limit would convert a busy moment into an OOM kill mid-utterance.
+#
+# `AddDevice=/dev/dri` is what makes the iGPU visible; without it the Vulkan
+# ICD enumerates nothing and the server dies on device lookup after it has
+# already read both GGUFs. `GroupAdd=keep-groups` is belt-and-braces, not the
+# thing that works here: the units podman spawns carry no supplementary groups
+# at all, and this host grants render access a different way — the udev rule
+# that makes the render nodes world-writable (same rule ComfyUI rides, see
+# dankclaw/comfyui). Measured: `id` inside this container lists only the
+# container's own group, and `tts-server` still holds renderD129.
+# The node is NOT named: this host is hybrid, renderD128 is the NVIDIA card and
+# renderD129 the amdgpu iGPU, so a node number in the unit is a guess that a
+# re-probe can invalidate, while the directory hands the container every render
+# node and the driver picks by name.
+#
+# /dev/kfd stays absent on purpose: that is the ROCm compute interface, owned by
+# the engines that use HIP. A Vulkan endpoint has no use for it, and handing a
+# container a second way onto the GPU is surface for nothing.
 #
 # 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
@@ -98,6 +114,9 @@ Network=frank-tts-engine.network
 EnvironmentFile=/home/dank/serverAppConfigs/scripts/frank-tts-engine.env
 Volume=/home/dank/models/Qwen3-TTS-GGUF:/models:ro
 Volume=/home/dank/voices:/voices:ro
+# Render access for the iGPU (see MEMORY / THE RENDER NODE above).
+AddDevice=/dev/dri
+GroupAdd=keep-groups
 HealthCmd=curl -fsS http://127.0.0.1:8880/health
 HealthInterval=30s
 HealthTimeout=10s

dankclaw/voiceservice/tts-engine-start.sh

@@ -7,7 +7,7 @@
 # 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:
+# THE FLAG THAT 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
@@ -18,13 +18,19 @@
 #                    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.
+# --device IS here, but conditionally: it reaches the binary only when
+# QWENTTS_DEVICE is non-empty, and empty is the CPU rollback — the binary then
+# takes its own default device, which is CPU because the CPU backend is always
+# built. One line in scripts/frank-tts-engine.env moves the endpoint between the
+# two shapes, with no rebuild. What must never reach argv is a device NAME the
+# loader does not enumerate: that is not refused by the argument parser, it dies
+# during device lookup with the loader's own error, so the journal reads as a
+# load that failed rather than a configuration refusal.
+#
+# Everything defaults to the shape this endpoint runs: 1.7 B talker Q4_K_M with
+# the Q8_0 tokenizer, one request at a time, on the private bridge, on the
+# gfx1151 iGPU. An empty environment still boots that shape.
 set -euo pipefail
 
 # The binary path. Overridable for one reason: the bats seam runs a stub
@@ -60,13 +66,33 @@ set -euo pipefail
 : "${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.
+# setting, which is what keeps the per-voice timings predictable. A second
+# concurrent synthesis shares the device with the first — and on this box that
+# device is also carrying frank-dragoon — so it buys no throughput and it
+# doubles the wait for the caller behind it. The engine's own default is also 1;
+# written here because it is a decision, not an accident.
 : "${QWENTTS_MAX_BATCH:=1}"
 
+# The compute device, NAMED and not numbered: `Vulkan0` is how ggml enumerates
+# the gfx1151 iGPU on this host. An index would follow whatever order the
+# loader's device list returns; a name says which device this endpoint means.
+# The container sees exactly one Vulkan device because the image carries the
+# Mesa ICD and no NVIDIA one, so the 3090 is not in the enumeration at all.
+#
+# EMPTY IS THE CPU ROLLBACK: a value that is set but EMPTY passes no `--device`,
+# the binary picks its own default, and the CPU backend is always built — which
+# is why moving this endpoint between the iGPU and the CPU is one line in
+# scripts/frank-tts-engine.env and not a rebuild.
+#
+# That is also why the default below is NOT `${QWENTTS_DEVICE:=Vulkan0}`: `:=`
+# fires on a set-but-empty variable as well as an unset one, so the rollback line
+# `QWENTTS_DEVICE=` would be rewritten back to Vulkan0 and the endpoint would sit
+# on the shared GPU with no way out short of a rebuild. Only UNSET takes the
+# default.
+if [[ ! -v QWENTTS_DEVICE ]]; then
+    QWENTTS_DEVICE=Vulkan0
+fi
+
 # 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
@@ -79,11 +105,20 @@ for artifact in "$QWENTTS_MODEL" "$QWENTTS_CODEC"; do
     fi
 done
 
-exec "$QWENTTS_BIN" \
-    --model "$QWENTTS_MODEL" \
-    --codec "$QWENTTS_CODEC" \
-    --alias "$QWENTTS_ALIAS" \
-    --host "$QWENTTS_HOST" \
-    --port "$QWENTTS_PORT" \
-    --lang "$QWENTTS_LANG" \
+ARGS=(
+    --model "$QWENTTS_MODEL"
+    --codec "$QWENTTS_CODEC"
+    --alias "$QWENTTS_ALIAS"
+    --host "$QWENTTS_HOST"
+    --port "$QWENTTS_PORT"
+    --lang "$QWENTTS_LANG"
     --max-batch "$QWENTTS_MAX_BATCH"
+)
+
+# Only when a device is named. An empty QWENTTS_DEVICE has to produce NO flag,
+# because "the rollback shape" is argv identical to the pre-iGPU endpoint.
+if [[ -n "$QWENTTS_DEVICE" ]]; then
+    ARGS+=(--device "$QWENTTS_DEVICE")
+fi
+
+exec "$QWENTTS_BIN" "${ARGS[@]}"

dankserver/calibre-server/quadlet/calibre-server.container

@@ -43,7 +43,7 @@ After=network.target
 
 [Container]
 ContainerName=calibre-server
-Image=lscr.io/linuxserver/calibre:9.15.0
+Image=lscr.io/linuxserver/calibre:9.15.0@sha256:59e4b0e036e62f228f8bcfae1ade42f47047719885fe454ddbad38e4597b987b
 Network=pasta
 EnvironmentFile=/home/dank/Containers/calibre-server/env
 Environment=PUID=1000

dankserver/calibre-web/quadlet/calibre-web.container

@@ -16,7 +16,7 @@ After=network.target
 
 [Container]
 ContainerName=calibre-web
-Image=lscr.io/linuxserver/calibre-web:0.6.27-ls402
+Image=lscr.io/linuxserver/calibre-web:0.6.27-ls402@sha256:802729966faed5e32d671cd4f92ba6196e9e754a6c0f740ce1ee9acd86b10e55
 Network=pasta
 Environment=DOCKER_MODS=linuxserver/mods:universal-calibre
 Environment=LANG=en_US.UTF-8

dankserver/copyparty/quadlet/copyparty.container

@@ -21,7 +21,13 @@ After=network.target
 
 [Container]
 ContainerName=copyparty
-Image=ghcr.io/9001/copyparty-ac:latest
+# Digest-pinned: upstream stopped publishing version tags after 1.19.15, so
+# the pin rides :latest@digest (the tag in the reference is cosmetic; the
+# digest is the pull). Pinned 2026-10-21 at the build whose label is
+# 1.20.26 - closes GHSA-3c88-p299-7hvr (1.20.25) and GHSA-hg99-jqfp-rf76
+# (1.20.26); the previously running build was the rolling :latest at
+# 1.20.24 (issue #73 on command-center).
+Image=ghcr.io/9001/copyparty-ac:latest@sha256:7f77459160a4bf34fdca79f2965dff4f0c1d7069a3d9cdfb3632acb041dd2f6a
 Network=dankserver_appnet
 EnvironmentFile=/home/dank/Containers/copyparty/env
 Exec=-a ${COPAY_ACCOUNT}:${COPAY_PASSWORD} -v /w::r:ra,dank

dankserver/jellyfin/quadlet/jellyfin.container

@@ -16,7 +16,7 @@ After=network.target
 
 [Container]
 ContainerName=jellyfin
-Image=ghcr.io/jellyfin/jellyfin:latest
+Image=ghcr.io/jellyfin/jellyfin:latest@sha256:c3efa69a22f2691fc88d6bb035e87a8560e395a6047f062fb381c61c3185e8f5
 Network=dankserver_appnet
 Environment=DEBIAN_FRONTEND=noninteractive
 Environment=DOTNET_SYSTEM_IO_DISABLEFILELOCKING=true

dankserver/observability/quadlet/cadvisor.container

@@ -0,0 +1,39 @@
+# Quadlet unit: cadvisor (rootless, boot-persistent) — DANKSERVER.
+#
+# Install path on dankserver: ~/.config/containers/systemd/cadvisor.container
+# Unit name: cadvisor.service (container name: cadvisor)
+#
+# The Dankserver twin of dankclaw/observability/quadlet/cadvisor.container.
+# Same rootless shape, same --cgroupns=host requirement (see that file for the
+# full story), only the LAN address differs: this host publishes on
+# 192.168.0.235:8080 so Prometheus on Dankclaw can scrape it over the real
+# network (cross-host, so the host.containers.internal trick does not apply).
+# It reports the media/library stack (romm, plex, jellyfin, copyparty, calibre,
+# tautulli) by their quadlet unit names via the cgroup path.
+
+[Unit]
+Description=cAdvisor container metrics (Dankserver)
+After=network-online.target
+Wants=network-online.target
+
+[Container]
+ContainerName=cadvisor
+Image=gcr.io/cadvisor/cadvisor:v0.49.1@sha256:3cde6faf0791ebf7b41d6f8ae7145466fed712ea6f252c935294d2608b1af388
+PodmanArgs=--pid=host --cgroupns=host
+PublishPort=127.0.0.1:8080:8080
+PublishPort=192.168.0.235:8080:8080
+Volume=/sys:/sys:ro
+Volume=/:/rootfs:ro
+Exec=--housekeeping_interval=30s
+HealthCmd=wget --spider -q http://localhost:8080/healthz
+HealthInterval=30s
+HealthTimeout=10s
+HealthRetries=3
+HealthStartPeriod=40s
+
+[Service]
+Restart=always
+RestartSec=10
+
+[Install]
+WantedBy=default.target

dankserver/observability/quadlet/node-exporter.container

@@ -37,7 +37,7 @@ Wants=network-online.target
 
 [Container]
 ContainerName=node-exporter
-Image=docker.io/prom/node-exporter:latest
+Image=docker.io/prom/node-exporter:latest@sha256:1b4e4438faca4dd7e001dd445d161a4a2091b0fededa84093b3a8dfeae1f1be0
 Network=host
 PodmanArgs=--pid=host
 Exec=--path.procfs=/host/proc --path.sysfs=/host/sys --path.rootfs=/rootfs --web.listen-address=127.0.0.1:9100 --web.listen-address=192.168.0.235:9100

dankserver/plex/quadlet/plex.container

@@ -4,7 +4,7 @@ After=network-online.target
 Wants=network-online.target
 
 [Container]
-Image=lscr.io/linuxserver/plex:1.43.4.10903-e5521bd8c-ls325
+Image=lscr.io/linuxserver/plex:1.43.5.11029-6bf8af3f0-ls329@sha256:8f655bad7dcbc5398a78f70a5af12600b4ed3424f901566ed1eaa6710e9e2334
 ContainerName=plex
 Network=dankserver_appnet:alias=plex
 Environment=PUID=0

dankserver/romm/quadlet/romm-mariadb.container

@@ -14,7 +14,7 @@ After=network.target
 
 [Container]
 ContainerName=romm-mariadb
-Image=docker.io/library/mariadb:11
+Image=docker.io/library/mariadb:11@sha256:f16d7a344413e519dff518f27bdb221388f84b0d274c97c4fb5f2cb0dc1b34fa
 Network=dankserver_appnet:alias=mariadb
 EnvironmentFile=/home/dank/Containers/romm/env
 Environment=MARIADB_DATABASE=romm

dankserver/romm/quadlet/romm-redis.container

@@ -12,7 +12,7 @@ After=network.target
 
 [Container]
 ContainerName=romm-redis
-Image=docker.io/library/redis:7-alpine
+Image=docker.io/library/redis:7-alpine@sha256:858f009f9709ce576febc734aa78b8f6d624b82571f9ddb6bda4377c833b3499
 Network=dankserver_appnet:alias=redis
 Volume=/home/dank/Containers/romm/redis:/data
 HealthCmd=redis-cli ping

dankserver/romm/quadlet/romm.container

@@ -18,7 +18,7 @@ After=romm-mariadb.service romm-redis.service network.target
 
 [Container]
 ContainerName=romm
-Image=ghcr.io/rommapp/romm:latest
+Image=ghcr.io/rommapp/romm:latest@sha256:03295f95a6290e752641f9553ac4198b0e5b71b879d57f7b2371b98f608feb54
 Network=dankserver_appnet
 EnvironmentFile=/home/dank/Containers/romm/env
 Environment=DB_HOST=mariadb

dankserver/tautulli/quadlet/tautulli.container

@@ -4,7 +4,7 @@ After=network-online.target
 Wants=network-online.target
 
 [Container]
-Image=lscr.io/linuxserver/tautulli:v2.18.1-ls245
+Image=lscr.io/linuxserver/tautulli:v2.18.1-ls245@sha256:c66d3afa8f7a701a48dd1b1f57b22eca0483d895d670fe11ecff783f6a9bbd73
 ContainerName=tautulli
 Network=dankserver_appnet:alias=tautulli
 Environment=PUID=0

frankbook-pro/gluetun/quadlet/gluetun.container

@@ -19,7 +19,7 @@ Description=Gluetun VPN tunnel (FrankBook-Pro podman machine)
 
 [Container]
 ContainerName=gluetun
-Image=docker.io/qmcgaw/gluetun:latest
+Image=docker.io/qmcgaw/gluetun:latest@sha256:c2ee4191762fca6b6a3c3359a731198a95d9c9af4db32d466e223bf3a84e779b
 AddCapability=NET_ADMIN
 AddDevice=/dev/net/tun:/dev/net/tun
 Environment=VPN_SERVICE_PROVIDER=${VPN_SERVICE_PROVIDER}

frankbook-pro/lidarr/quadlet/lidarr.container

@@ -15,7 +15,7 @@ After=gluetun.service
 
 [Container]
 ContainerName=lidarr
-Image=lscr.io/linuxserver/lidarr:latest
+Image=lscr.io/linuxserver/lidarr:latest@sha256:d8549ff9ea29b4015c32257360652c1000c31ea471a2b3f0835ae77292faf35b
 Environment=PUID=0
 Environment=PGID=0
 Environment=TZ=America/Los_Angeles

frankbook-pro/prowlarr/quadlet/prowlarr.container

@@ -24,7 +24,7 @@ After=gluetun.service
 
 [Container]
 ContainerName=prowlarr
-Image=lscr.io/linuxserver/prowlarr:latest
+Image=lscr.io/linuxserver/prowlarr:latest@sha256:b3b00047ed20f6ce2b16780145cb6a0acb51c9e28ea6aa6f5dcd33c7034f1797
 Environment=PUID=0
 Environment=PGID=0
 Environment=TZ=America/Los_Angeles

frankbook-pro/qbittorrent/quadlet/qbittorrent.container

@@ -29,7 +29,7 @@ Network=gluetun.container
 # Pinned to the last 4.x line: Readarr's retired qB client requires the
 # qB 4.x login response (HTTP 200, body "Ok."); qB 5.x answers 204 with an
 # empty body, which fails Readarr's auth check. All other clients accept 4.x.
-Image=lscr.io/linuxserver/qbittorrent:4.6.7
+Image=lscr.io/linuxserver/qbittorrent:4.6.7@sha256:55f15d44396315551f87294a176efae733b16e283f38980308e46073950257c6
 Environment=PUID=0
 Environment=PGID=0
 Environment=TZ=America/Los_Angeles

frankbook-pro/radarr/quadlet/radarr.container

@@ -15,7 +15,7 @@ After=gluetun.service
 
 [Container]
 ContainerName=radarr
-Image=lscr.io/linuxserver/radarr:latest
+Image=lscr.io/linuxserver/radarr:latest@sha256:fc0ae3c50f8128b97e84381903ec8d6845c3a569641cb7117c124376cccb57c1
 Environment=PUID=0
 Environment=PGID=0
 Environment=TZ=America/Los_Angeles

frankbook-pro/readarr/quadlet/readarr.container

@@ -19,7 +19,7 @@ After=gluetun.service
 
 [Container]
 ContainerName=readarr
-Image=lscr.io/linuxserver/readarr:amd64-1.0.980
+Image=lscr.io/linuxserver/readarr:amd64-1.0.980@sha256:a95e82dbb0eb2bb43de4c150f1dab9dd821306c67ea0b418983a957e731f2b61
 Environment=PUID=0
 Environment=PGID=0
 Environment=TZ=America/Los_Angeles

frankbook-pro/sonarr/quadlet/sonarr.container

@@ -16,7 +16,7 @@ After=gluetun.service
 
 [Container]
 ContainerName=sonarr
-Image=lscr.io/linuxserver/sonarr:latest
+Image=lscr.io/linuxserver/sonarr:latest@sha256:889dcc58c6aea859033985894b519b2e6b1e55d92527ed123f9f52e42ae7c97b
 Environment=PUID=0
 Environment=PGID=0
 Environment=TZ=America/Los_Angeles

report/tts-npu-spike-verdict-2026-10-19.md

@@ -136,25 +136,36 @@ TTS engine today|3.84 GiB RSS, CPU|its device-resident replacement lands in that
    ICD**, so Vulkan device 0 is the iGPU here. Do not trust that ordering — select by
    device *name*, or an image that grows an `nvidia_icd.json` silently points TTS at the
    3090 slot.
-2. **Contention gate.** `frank-dragoon` is the endpoint the operator session runs on, so the
-   honest measurement with both loaded is dragoon's own TTFT and decode with a synthesis in
-   flight — one request each, no ladder. Expect compute-unit sharing rather than memory
-   pressure: the aperture has room, the shaders do not.
+2. **Contention gate — PASSED, measured 2026-10-19 after the cutover.** With a 16.9 s
+   synthesis occupying the device, `frank-dragoon` answered a streamed 124-token request at
+   **17 ms to first token and ~35 tok/s decode**, against 17 ms and ~33 tok/s for the same
+   request with the card idle. Compute-unit sharing showed up as nothing. One request per
+   arm, no ladder: these are the gate's evidence, not a throughput record, and the engine's
+   own shape lives in [[Frank TTS Engine]].
 
-**Change surface** — the whole edit, so nobody re-derives it:
+**Change surface — as landed** (PR #34, `6248f02`; the CPU shape stays reachable as the
+rollback):
 
-1. `Containerfile.engine` build stage: add `libvulkan-dev glslang-dev`. It installs only
-   `ca-certificates cmake g++ git make` today, and ggml's Vulkan backend compiles its
-   shaders at build time — the flag alone fails at configure.
-2. `-DGGML_VULKAN=OFF` → `ON` in the same cmake block; the flag list is written out
-   explicitly, so this is a one-word diff.
-3. Runtime stage: add `mesa-vulkan-drivers`. Without a Vulkan **ICD inside the image** the
-   device node buys nothing — there is no `radeon_icd.json` in the container today.
-4. `frank-tts-engine.container`: `AddDevice=/dev/dri` + `GroupAdd=keep-groups` — **not**
-   `renderD128`. On this hybrid box that node is the NVIDIA card; the iGPU is
-   `renderD129` (`readlink -f /sys/class/drm/renderD129/device/driver` → `amdgpu`).
-5. Engine argv: `--device Vulkan0` — qwentts.cpp's tools take `--device <name>` at the
-   pinned commit.
+1. `Containerfile.engine` build stage: add **`libvulkan-dev glslc spirv-headers`**. The
+   prediction above (`libvulkan-dev glslang-dev`) is wrong on two counts and the configure
+   says so: ggml looks for `glslc`, which Ubuntu's `glslang-tools` does **not** ship (it
+   ships `glslangValidator`), and `find_package(SPIRV-Headers CONFIG REQUIRED)` needs the
+   distro's `spirv-headers`, which does carry the CMake config. `glslc` is its own source
+   package on noble, at 2023.8 — old enough that only `GL_KHR_cooperative_matrix` compiles,
+   so the coopmat2 / integer-dot / bf16 / micro-float shader families are built out. Suspect
+   that compiler before the device if a Vulkan prefill ever reads as slow.
+2. `-DGGML_VULKAN=OFF` → `ON`: one word in the written-out flag list.
+3. Runtime stage: `mesa-vulkan-drivers` **and** `libvulkan1` — the ICD and its loader. An
+   image with a loader and no ICD enumerates zero devices.
+4. `frank-tts-engine.container`: `AddDevice=/dev/dri` + `GroupAdd=keep-groups` — the
+   DIRECTORY, never the node: on this hybrid box `renderD128` is the NVIDIA card and
+   `renderD129` the amdgpu iGPU (`readlink -f /sys/class/drm/renderD129/device/driver` →
+   `amdgpu`). On this host the udev rule already makes the nodes world-writable, so the
+   group is belt-and-braces, not the gate.
+5. Engine argv: `--device Vulkan0`, reached through `QWENTTS_DEVICE` in
+   `scripts/frank-tts-engine.env`. **An empty value passes no flag at all** — that is the
+   CPU rollback, and it is why the entrypoint's default is an `-v` test rather than `:=`,
+   which also fires on a set-but-empty value and would silently undo the rollback.
 
 Gate 1 recipe, already run and **PASSED**: `mesa-vulkan-drivers` + `vulkan-tools` in a
 throwaway container off the same base, `--device /dev/dri`, then `vulkaninfo --text` and read

scripts/apply-protected-cast.sh

@@ -1,27 +1,45 @@
 #!/usr/bin/env bash
-# apply-protected-cast.sh — RUNS ON DANKSERVER. Rewrite the recipe's
-# PROTECTED-BEGIN/END section from Swift's OWN calibration grams: run
+# apply-protected-cast.sh — RUNS ON DANKSERVER. Rewrite a recipe's
+# PROTECTED-BEGIN/END section from the campaign's OWN calibration grams: run
 # derive-protected-experts.py over the calib dir, splice its cast lines into
 # the marked section of the recipe in place, keep the pre-edit recipe in the
-# campaign trash. Refuses to run twice (marker text says derived).
+# campaign trash. Refuses to run twice (marker text says derived), and refuses
+# when a requested target count was not reached. Run it on a COPY of the
+# template so the committed recipe stays the clean, reviewable baseline.
 set -euo pipefail
-CALIB=${1:-/home/dank/corpora/calib}
-RECIPE=${2:-/home/dank/serverAppConfigs-swift15/scripts/recipes/qwen4exp-swift15-w4dn8-i8-hc8m.recipe}
-PY=/home/dank/venvs/radcorpus/bin/python
-DERIVE=/home/dank/serverAppConfigs-swift15/scripts/derive-protected-experts.py
+SELF_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+CALIB=${1:-/home/dank/campaign/qwen38-w5nl64/calib}
+RECIPE=${2:-$SELF_DIR/recipes/qwen4exp-qwen38-w5nl64-bf16trunk.recipe}
+TARGET_COUNT=${3:-0}
+PY=${PY:-/home/dank/venvs/radcorpus/bin/python}
+DERIVE=${DERIVE:-$SELF_DIR/derive-protected-experts.py}
 TS=$(date +%Y%m%d-%H%M%S)
+# OUT and TRASH_DIR are overridable so the seam can drive the whole script in a
+# scratch directory; on the box they are the campaign's usual places.
+OUT=${OUT:-/tmp/protected-cast-$TS.txt}
+TRASH_DIR=${TRASH_DIR:-/home/dank/.AGENTTRASH}
 
 grep -q "derive-protected-experts.py rewrote" "$RECIPE" && {
     echo "recipe already carries derived cast lines; refusing to re-derive" >&2; exit 1; }
 grep -q "PROTECTED-BEGIN" "$RECIPE" || { echo "no PROTECTED markers in $RECIPE" >&2; exit 1; }
 
-"$PY" "$DERIVE" "$CALIB" > "/tmp/protected-cast-$TS.txt"
-N=$(grep -c 'cast dtype=bf16' "/tmp/protected-cast-$TS.txt")
-[ "$N" -ge 2 ] || { echo "derive produced $N cast lines; refusing" >&2; exit 1; }
-echo "derived $N protected experts -> /tmp/protected-cast-$TS.txt"
+ARGS=("$DERIVE" "$CALIB")
+if [ "$TARGET_COUNT" -gt 0 ]; then
+    ARGS+=(--target-count "$TARGET_COUNT")
+fi
+"$PY" "${ARGS[@]}" > "$OUT"
+N=$(grep -c 'cast dtype=bf16' "$OUT")
+[ "$N" -ge 2 ] || { echo "derive produced $N cast lines; refusing (see $OUT)" >&2; exit 1; }
+if [ "$TARGET_COUNT" -gt 0 ] && [ "$N" -lt "$TARGET_COUNT" ]; then
+    echo "derive reached $N protected experts, target was $TARGET_COUNT; refusing to convert" >&2
+    echo "       (the bar sweep bottomed out: the recording is too thin or the target too high)" >&2
+    exit 1
+fi
+echo "derived $N protected experts -> $OUT"
 
-cp -f "$RECIPE" "/home/dank/.AGENTTRASH/$TS-qwen4exp-swift15-w4dn8-i8-hc8m.recipe"
-"$PY" - "$RECIPE" "/tmp/protected-cast-$TS.txt" <<'PYEOF'
+mkdir -p "$TRASH_DIR"
+cp -f "$RECIPE" "$TRASH_DIR/$TS-$(basename "$RECIPE")"
+"$PY" - "$RECIPE" "$OUT" <<'PYEOF'
 import sys
 recipe, castfile = sys.argv[1], sys.argv[2]
 lines = open(recipe).read().splitlines()
@@ -35,7 +53,7 @@ for l in lines:
     elif 'PROTECTED-END' in l:
         insec = False
         out.append(l)
-        out.append('# (derive-protected-experts.py rewrote this section from Swift\'s own grams)')
+        out.append('# (derive-protected-experts.py rewrote this section from the campaign grams)')
     elif not insec:
         out.append(l)
 open(recipe, 'w').write('\n'.join(out) + '\n')

scripts/authentik-grafana-sso-fix.sh

@@ -0,0 +1,81 @@
+#!/usr/bin/env bash
+# Repair the Grafana OAuth2 relying-party SSO on Dankclaw's authentik.
+#
+# grafana.franksdank.cloud logs in through authentik as an OAuth2 relying party.
+# Two DB-side facts (the provider was created by hand via `ak shell`, never
+# repo-managed) silently broke that login, and BOTH had previously been
+# mis-recorded here as a single "the property-mapping evaluator is broken, so
+# userinfo returns only `sub`" myth. They are neither, and the evaluator is fine:
+#
+#   1. provider.authorization_flow was NULL. The authorize view builds a flow
+#      planner from it and crashes with
+#      `AttributeError: 'NoneType' object has no attribute 'slug'` — an HTTP 500
+#      "Server Error — Powered by authentik", before any claim is touched.
+#      Fix: point it at default-provider-authorization-implicit-consent, the
+#      flow every other provider in this instance already uses.
+#   2. The `grafana-email-scope` ScopeMapping's expression was the bare string
+#      `user.email`. authentik merges a scope mapping's result into the token as
+#      a MAPPING: a returned dict adds its keys as claims; a returned string is
+#      keyed under the mapping's NAME ("grafana-email-scope"), so no `email`
+#      claim is ever emitted. Grafana, finding no email, falls back to
+#      GET <api_url>/emails, authentik 404s that path, and the login dies with
+#      "Login failed: InternalError". Fix: return
+#      {"email": user.email, "email_verified": True} — the shape the stock
+#      OpenID 'email' mapping uses. The dict-valued `grafana-profile-scope`
+#      mapping has always worked, which is the proof the evaluator is fine.
+#
+# This is authentik DB state. It is NOT in any deployable file: a blueprint
+# re-import, or an ak-shell re-creation of the grafana provider, reverts BOTH
+# facts and the symptom returns verbatim. Re-run this after any such rebuild.
+# Every step is idempotent.
+#
+# Grafana's own half — SCOPES="openid email profile", a standard userinfo API_URL
+# with no `?api=1`, and ALLOW_SIGN_UP=true — lives in
+# dankclaw/observability/quadlet/grafana.container and deploys normally.
+#
+# Usage: authentik-grafana-sso-fix.sh          (override host: AUTHENTIK_HOST=…)
+set -euo pipefail
+HOST="${AUTHENTIK_HOST:-dankclaw}"
+
+ssh "$HOST" 'podman exec -i authentik-server ak shell' <<'PYEOF'
+from authentik.flows.models import Flow
+from authentik.providers.oauth2.models import OAuth2Provider
+
+p = OAuth2Provider.objects.filter(name="grafana").first()
+if not p:
+    raise SystemExit("no OAuth2Provider named 'grafana'")
+
+# 1. The authorization flow every other provider uses.
+want = Flow.objects.filter(slug="default-provider-authorization-implicit-consent").first()
+if not want:
+    raise SystemExit("default-provider-authorization-implicit-consent flow is missing")
+if p.authorization_flow_id != want.pk:
+    p.authorization_flow = want
+    p.save()
+    print(f"set grafana.authorization_flow -> {want.slug}")
+else:
+    print(f"grafana.authorization_flow already {want.slug}")
+
+# 2. The email scope mapping must RETURN A DICT, not a bare string.
+m = p.property_mappings.filter(name="grafana-email-scope").first()
+if not m:
+    raise SystemExit("grafana-email-scope mapping is missing")
+fixed = 'return {"email": user.email, "email_verified": True}'
+if m.expression.strip() != fixed:
+    m.expression = fixed
+    m.save()
+    print("repaired grafana-email-scope -> returns {email, email_verified}")
+else:
+    print("grafana-email-scope expression already correct")
+
+# 3. The id_token must carry the scope claims; Grafana reads identity from it.
+if not p.include_claims_in_id_token:
+    p.include_claims_in_id_token = True
+    p.save()
+    print("enabled include_claims_in_id_token")
+else:
+    print("include_claims_in_id_token already on")
+PYEOF
+
+echo "Done. Verify: sign in at https://grafana.franksdank.cloud via Authentik;"
+echo "the round trip must land on / and /api/user must answer 200 with an email."

scripts/authentik-set-login-session-duration.sh

@@ -0,0 +1,47 @@
+#!/usr/bin/env bash
+# Set the authentik login-session TTL on Dankclaw.
+#
+# The login-session lifetime is governed by the `default-authentication-login`
+# stage's `session_duration`, NOT a global setting and NOT SESSION_COOKIE_AGE
+# (that is the pre-login session, sessions.unauthenticated_age). Authentik does
+# not expose SESSION_SAVE_EVERY_REQUEST at all, so the session is an absolute
+# window from login, not a sliding one.
+#
+# The field is a STRING in authentik's own idiom ("days=7", "seconds=30",
+# "hours=12") — not a Python timedelta. Writing str(timedelta(days=7)) stores
+# "7 days, 0:00:00", which authentik's timedelta_from_string parser REJECTS
+# (ValueError), and login then crashes computing the session expiry. Always pass
+# the "key=value" form; this script validates it before writing.
+#
+# Existing sessions keep their old expiry; the new TTL applies from the next
+# login. This is DB state — it is NOT repo-managed and a blueprint re-import or
+# rebuild-from-scratch reverts it. Run this again after such a rebuild.
+#
+# Usage: authentik-set-login-session-duration.sh ["days=7"]   (default days=7)
+set -euo pipefail
+
+DUR="${1:-days=7}"
+STAGE="default-authentication-login"
+HOST="${AUTHENTIK_HOST:-dankclaw}"
+
+# Refuse anything that is not the safe key=value duration idiom.
+if ! printf '%s' "$DUR" | grep -Eq '^[A-Za-z]+=[0-9]+([ ]+[A-Za-z]+=[0-9]+)*$'; then
+    echo "invalid duration '$DUR' — use authentik form, e.g. 'days=7' or 'seconds=30'" >&2
+    exit 2
+fi
+
+ssh "$HOST" 'podman exec -i authentik-server ak shell' <<PYEOF
+from django.apps import apps
+from authentik.lib.utils.time import timedelta_from_string
+dur = "$DUR"
+timedelta_from_string(dur)  # validate the form before touching the row
+ULS = apps.get_model("authentik_stages_user_login", "UserLoginStage")
+s = ULS.objects.get(name="$STAGE")
+s.session_duration = dur
+s.save(update_fields=["session_duration"])
+back = ULS.objects.get(name="$STAGE").session_duration
+assert back == dur, "persisted value mismatch: %r" % back
+print("session_duration set to", repr(back), "->", timedelta_from_string(back))
+PYEOF
+
+echo "Login-session TTL for '$STAGE' is now $DUR (applies on next login)."

scripts/build-qwen38-bf16-rad.sh

@@ -0,0 +1,220 @@
+#!/usr/bin/env bash
+# build-qwen38-bf16-rad.sh — RUNS ON DANKSERVER. rad-convert the vendor BF16
+# checkpoint /home/dank/models/Qwen3.8-Flash-Next into
+# /home/dank/models/rad/qwen38-bf16.rad with NO recipe and NO --reuse: a weight
+# no rule matches keeps the checkpoint's encoding, so every tensor stays the
+# bf16 it is in the safetensors and the container is the checkpoint's own
+# numbers behind a .rad header.
+#
+# This file is the campaign's measuring stick, twice over: scripts/
+# run-qwen38-bf16.sh kldref records the KLD reference logits from it (every
+# arm's --kld-ref is scored against that record) and the same container serves
+# with the calibration tap to write the Grams that derive the protected-expert
+# list and feed GPTQ. A reference that is not the vendor checkpoint, byte for
+# byte in bf16, silently moves every gate in the campaign — hence no recipe, no
+# --reuse, and the four refusal gates below.
+#
+# Why a container at all: a checkpoint dir has no mapped/file tiers, and a
+# weight only a host kernel reads (the 47.7 GiB PLE n-gram table) cannot be
+# served from one; rad-convert also bakes the tokenizer. The convert runs on
+# the HOST backend — no --device /dev/kfd, no /dev/dri — so declare resolves
+# kernels on CPU and production serving is untouched for the whole run (the
+# precedent that proved it: scripts/convert-swift15-w4dn8.sh).
+#
+# Gates, every one a refusal with exit 2 and a named reason, BEFORE anything is
+# written, cheapest first — the verifier runs last of them because its Hub gate
+# hashes 343 GiB and must not be paid for by a run that was going to refuse on
+# the output file anyway.
+#   checkpoint  the tree must be on disk; an absent dir names the command that
+#               makes one (scripts/download-qwen38-bf16.sh --fetch) and stops.
+#   free space  the convert writes ~343,323 MiB next to the ~343,323 MiB
+#               checkpoint; QWEN38_MIN_FREE_MIB (default 350000 = that figure
+#               plus 6.5 GiB of slack) is the floor. The volume that cannot
+#               hold both is discovered at minute 2, not hour 5.
+#   output      the campaign converts the reference ONCE. An existing
+#               qwen38-bf16.rad is refused; --force retires it to
+#               ~/.AGENTTRASH/<utc>-qwen38-bf16.rad (trash law: nothing is
+#               deleted, and the move is a rename on the same volume).
+#   verified    scripts/download-qwen38-bf16.sh's verify mode must pass. A
+#               failed verify exits 1, not 2: the tree being the wrong payload
+#               is a result, a missing environment is a refusal.
+#   plan        rad-convert --plan-only -v first — the oracle for "does this
+#               shape boot". A refused plan costs seconds and saves a convert.
+#
+# usage: scripts/build-qwen38-bf16-rad.sh [--dry-run] [--plan-only] [--force]
+#   --dry-run    print the argv it would exec (podman wrapping rad-convert),
+#               one shell-quoted argument a line, and exit 0. No gate runs, no
+#               container starts, nothing is written — the offline test seam.
+#               It does resolve the checkpoint and output paths through the
+#               /models mount, because an argv that carries host paths would
+#               not run either.
+#   --plan-only  run the plan and every gate except the disk and output ones —
+#               those two protect bytes the plan never writes, and this is the
+#               probe to run when the disk gate itself is what refuses
+#   --force      retire an existing output container to the trash dir first
+#
+# knobs: FRANK_QWEN38_MODELS   the host dir mounted at /models (default
+#        /home/dank/models); FRANK_QWEN38_CKPT (default $MODELS/
+#        Qwen3.8-Flash-Next, the same knob the verifier reads);
+#        FRANK_QWEN38_BF16_OUT (default $MODELS/rad/qwen38-bf16.rad);
+#        QWEN38_MIN_FREE_MIB; QWEN38_TRASH (default $HOME/.AGENTTRASH). The
+#        verifier's own census knobs (FRANK_QWEN38_SHARDS / _BYTES / _REPO)
+#        reach it through the environment untouched.
+# exit: 0 converted (or planned), 1 the checkpoint failed verification,
+#       2 refused before anything was written
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# ONE owner of the engine pin: the digest frank-archon serves on. The reference
+# must be built by the SAME engine build that scores it, or a KLD delta is
+# partly a version delta.
+# shellcheck disable=SC1091
+source "$SCRIPT_DIR/frank-archon.env"
+IMAGE="${FRANK_ARCHON_IMAGE:?FRANK_ARCHON_IMAGE must name the radiance image}"
+
+MODELS="${FRANK_QWEN38_MODELS:-/home/dank/models}"
+CKPT="${FRANK_QWEN38_CKPT:-$MODELS/Qwen3.8-Flash-Next}"
+OUT="${FRANK_QWEN38_BF16_OUT:-$MODELS/rad/qwen38-bf16.rad}"
+TRASH="${QWEN38_TRASH:-$HOME/.AGENTTRASH}"
+MIN_FREE_MIB="${QWEN38_MIN_FREE_MIB:-350000}"
+LOG="/home/dank/logs/qwen38_bf16_convert.log"
+
+DRY=0
+PLAN_ONLY=0
+FORCE=0
+while [ $# -gt 0 ]; do
+    case "$1" in
+        --dry-run)   DRY=1 ;;
+        --plan-only) PLAN_ONLY=1 ;;
+        --force)     FORCE=1 ;;
+        *) echo "usage: ${0##*/} [--dry-run] [--plan-only] [--force]" >&2
+           exit 2 ;;
+    esac
+    shift
+done
+
+# The convert sees the tree only through the /models mount, so both paths must
+# be under it; the container-side spelling is what goes into the argv.
+case "$CKPT" in
+    "$MODELS"/*) CKPT_IN="/models/${CKPT#"$MODELS"/}" ;;
+    *) echo "REFUSED: checkpoint $CKPT is not under the mounted models dir $MODELS — the convert cannot see it" >&2
+       exit 2 ;;
+esac
+case "$OUT" in
+    "$MODELS"/*) OUT_IN="/models/${OUT#"$MODELS"/}" ;;
+    *) echo "REFUSED: output $OUT is not under the mounted models dir $MODELS — rad-convert could not write it" >&2
+       exit 2 ;;
+esac
+
+# Declare with NO recipe line — that is what keeps every tensor bf16 — and at the
+# bound this container will actually be served at. Both flags come off the pinned
+# image's own help: --kv-cache-dtype at convert "only picks the kernels it
+# checks" and the container is identical either way, so naming fp8 is free
+# insurance — if the fp8 KV kernels the fleet serves would not resolve, the
+# convert refuses here instead of the boot failing on a drained window.
+# --max-ctx is the bound declare is run at, whose default is the checkpoint's
+# training context (262,144 here, whose fp8 cache is 258.8 GiB against a 192 GiB
+# machine, so the default is not an option). 32,768 is set by the corpus, not by
+# taste: kld.jsonl's longest record is 38,263 characters — ~9,600 tokens at the
+# pessimistic chars/4, ~7,700 at the chars/4.97 this repo measured on the K3
+# corpus — so the window the rig boots at clears every record 2.6x over and the
+# reference boot cannot die on a sequence that will not fit. The rig's window is
+# one knob (FRANK_QWEN38_MAX_MODEL_LEN in scripts/run-qwen38-bf16.sh, default
+# 32,768) and that script refuses a corpus its window cannot hold, so raising one
+# without the other is caught before the drained window, not inside it. The
+# payload containers the gate scores declare at the training context because
+# production must hold the 200k shape; a declared bound is a declare-time check,
+# not a weight change, so the reference and the payloads carry the same numbers
+# whatever each declared at — which is why one can be measured against the other.
+CONVERT_ARGS=("$CKPT_IN" -o "$OUT_IN" --max-ctx 32768 --kv-cache-dtype fp8)
+PODMAN=(podman run --rm --entrypoint rad-convert -v "$MODELS:/models")
+PLAN_CMD=("${PODMAN[@]}" --name qwen38-bf16-plan "$IMAGE" "${CONVERT_ARGS[@]}" --plan-only -v)
+CONV_CMD=("${PODMAN[@]}" --name qwen38-bf16-convert "$IMAGE" "${CONVERT_ARGS[@]}")
+
+if [ "$DRY" = "1" ]; then
+    echo "dry run: no gate checked, no container started, nothing written"
+    echo "# $CKPT -> $OUT (the convert sees them as $CKPT_IN and $OUT_IN)"
+    echo "# plan argv:"
+    printf '%q\n' "${PLAN_CMD[@]}"
+    echo "# convert argv:"
+    printf '%q\n' "${CONV_CMD[@]}"
+    exit 0
+fi
+
+# ---- gate: the checkpoint is on disk ---------------------------------------
+if [ ! -d "$CKPT" ]; then
+    echo "REFUSED: no checkpoint at $CKPT — fetch and verify it first: scripts/download-qwen38-bf16.sh --fetch" >&2
+    exit 2
+fi
+
+# ---- gate: peak disk --------------------------------------------------------
+# The deepest existing ancestor is the right thing to ask: a fresh
+# /home/dank/models/rad has no free space of its own to report.
+OUT_DIR="$(dirname "$OUT")"
+PROBE="$OUT_DIR"
+while [ ! -d "$PROBE" ] && [ "$PROBE" != "/" ]; do PROBE="$(dirname "$PROBE")"; done
+FREE_MIB="$(df --output=avail -m "$PROBE" | tail -1 | tr -d ' ')"
+if ! [[ "$FREE_MIB" =~ ^[0-9]+$ ]]; then
+    echo "REFUSED: cannot read the free space under $PROBE (df said: $FREE_MIB)" >&2
+    exit 2
+fi
+if [ "$PLAN_ONLY" != "1" ] && [ "$FREE_MIB" -lt "$MIN_FREE_MIB" ]; then
+    echo "REFUSED peak-disk: $FREE_MIB MiB free under $PROBE, $MIN_FREE_MIB MiB wanted (QWEN38_MIN_FREE_MIB) — the bf16 container rewrites the checkpoint's own 343,323 MiB of tensors beside it" >&2
+    exit 2
+fi
+
+# ---- gate: one conversion ---------------------------------------------------
+if [ -e "$OUT" ]; then
+    if [ "$PLAN_ONLY" = "1" ]; then
+        echo "note: $OUT already exists; --plan-only writes nothing, so it stays"
+    elif [ "$FORCE" = "1" ]; then
+        mkdir -p "$TRASH"
+        DEST="$TRASH/$(date -u +%Y%m%dT%H%M%SZ)-$(basename "$OUT")"
+        mv "$OUT" "$DEST"
+        echo "TRASHED: retired the existing reference container $OUT -> $DEST"
+    else
+        echo "REFUSED: $OUT already exists — the campaign converts the reference once; re-run with --force to retire it to $TRASH first" >&2
+        exit 2
+    fi
+fi
+
+# ---- gate: the tree really is the checkpoint (the full verify) -------------
+echo "== verifying $CKPT (scripts/download-qwen38-bf16.sh, full gates)"
+rc=0
+bash "$SCRIPT_DIR/download-qwen38-bf16.sh" --dir "$CKPT" || rc=$?
+if [ "$rc" -ne 0 ]; then
+    if [ "$rc" -eq 2 ]; then
+        echo "REFUSED: the checkpoint verifier refused the environment (rc=2); nothing was converted" >&2
+        exit 2
+    fi
+    echo "REFUSED: $CKPT failed verification (rc=$rc) — a half tree converts to a half reference" >&2
+    exit 1
+fi
+
+# ---- plan, then convert ------------------------------------------------------
+mkdir -p "$(dirname "$LOG")"
+# rad-convert opens -o during declare as well, so the output directory exists
+# before the plan; that empty directory is all this creates ahead of it.
+mkdir -p "$OUT_DIR"
+echo "== rad-convert --plan-only -v (declare + plan; writes nothing)"
+"${PLAN_CMD[@]}" 2>&1 | tee -a "$LOG"
+rc=${PIPESTATUS[0]}
+if [ "$rc" -ne 0 ]; then
+    echo "REFUSED plan: rad-convert --plan-only exited rc=$rc — the engine refuses this encoding/shape, no container was written (log: $LOG)" >&2
+    exit 2
+fi
+if [ "$PLAN_ONLY" = "1" ]; then
+    echo "PLAN_OK: $CKPT_IN declares for $OUT_IN; no container written (log: $LOG)"
+    exit 0
+fi
+
+echo "== convert: $CKPT -> $OUT ($(date -Is))"
+"${CONV_CMD[@]}" 2>&1 | tee -a "$LOG"
+rc=${PIPESTATUS[0]}
+if [ "$rc" -ne 0 ]; then
+    echo "rad-convert rc=$rc; log: $LOG" >&2
+    exit "$rc"
+fi
+MIB=$(( $(stat -c %s "$OUT") / 1048576 ))
+echo "BUILD_DONE: $OUT is ${MIB} MiB (log: $LOG)"
+echo "NEXT: scripts/run-qwen38-bf16.sh kldref records the reference logits from it"

scripts/calib-push.py

@@ -22,6 +22,9 @@ Mechanics notes:
   prompts do not bias the Hessians (the corpus is drawn round-robin over
   source classes, so loss is class-neutral as long as failures are rare;
   a systematic 4xx is loud in the log and must be fixed, not ignored).
+- a round that seals no tap bytes is a FAILURE, not a retry: the engine
+  answering 200 while the tap directory is wrong, full or read-only is
+  how a corpus gets pushed four times for nothing.
 
 Usage: calib-push.py [--port 7770] [--parallel 64] [--container arbench]
        [--corpus /home/dank/corpora/out/calib.jsonl] [--max-rounds 4]
@@ -29,11 +32,18 @@ Usage: calib-push.py [--port 7770] [--parallel 64] [--container arbench]
 import argparse
 import concurrent.futures
 import json
+import os
 import subprocess
 import sys
 import time
 import urllib.request
 
+_HERE = os.path.dirname(os.path.abspath(__file__)) if "__file__" in globals() else os.getcwd()
+if _HERE not in sys.path:
+    sys.path.insert(0, _HERE)
+
+import qwen38_common as qc  # noqa: E402 - sibling module, same directory
+
 DONE_MARK = "calibration wrote"
 
 
@@ -49,9 +59,9 @@ def tap_done(container):
     return DONE_MARK in (out.stdout + out.stderr)
 
 
-def push_one(url, prompt):
+def push_one(url, prompt, model):
     body = json.dumps({
-        "model": "frank-archon",
+        "model": model,
         "prompt": prompt,
         "max_tokens": 1,
         "temperature": 0,
@@ -68,38 +78,89 @@ def push_one(url, prompt):
         return False
 
 
-def main():
+def push_round(url, prompts, model, parallel):
+    """Push the whole corpus once; returns how many requests were accepted."""
+    ok = 0
+    with concurrent.futures.ThreadPoolExecutor(parallel) as ex:
+        for good in ex.map(lambda p: push_one(url, p, model), prompts):
+            ok += 1 if good else 0
+    return ok
+
+
+def tap_bytes(path):
+    """Bytes the tap has sealed so far; 0 when the directory is absent.
+
+    A tap whose directory is wrong, full or read-only stops writing while the
+    engine keeps answering 200 — the driver then re-pushes the whole corpus for
+    every round it is allowed and the loss is invisible until the hours are gone.
+    """
+    total = 0
+    try:
+        for root, _, files in os.walk(path):
+            for f in files:
+                try:
+                    total += os.path.getsize(os.path.join(root, f))
+                except OSError:
+                    pass
+    except OSError:
+        return 0
+    return total
+
+
+def parse_args():
     ap = argparse.ArgumentParser()
     ap.add_argument("--port", type=int, default=7770)
     ap.add_argument("--parallel", type=int, default=64)
     ap.add_argument("--container", default="arbench")
+    ap.add_argument("--model", default="frank-archon")
+    ap.add_argument("--tap-dir", default="/home/dank/campaign/qwen38-w5nl64/calib")
     ap.add_argument("--corpus", default="/home/dank/corpora/out/calib.jsonl")
     ap.add_argument("--max-rounds", type=int, default=4)
-    a = ap.parse_args()
-    url = f"http://127.0.0.1:{a.port}/v1/completions"
+    return ap.parse_args()
 
+
+def load_prompts(a) -> list[str]:
+    if not os.path.isfile(a.corpus):
+        qc.refuse(f"no corpus at {a.corpus}")
     prompts = []
-    with open(a.corpus) as f:
-        for line in f:
-            line = line.strip()
-            if line:
-                prompts.append(json.loads(line)["prompt"])
-    print(f"corpus: {len(prompts)} prompts", flush=True)
+    for lineno, rec in qc.iter_jsonl(a.corpus):
+        if not isinstance(rec.get("prompt"), str):
+            qc.refuse(f"{a.corpus}:{lineno} has no string 'prompt' field")
+        prompts.append(rec["prompt"])
+    if not prompts:
+        qc.refuse(f"the corpus at {a.corpus} holds no prompts")
+    return prompts
+
+
+def main():
+    a = parse_args()
+    url = f"http://127.0.0.1:{a.port}/v1/completions"
+    prompts = load_prompts(a)
+    chars = sum(len(p) for p in prompts)
+    print(f"corpus: {len(prompts)} prompts, ~{chars // 4} tokens (chars/4)",
+          flush=True)
 
     for rnd in range(1, a.max_rounds + 1):
         if tap_done(a.container):
             break
+        before = tap_bytes(a.tap_dir)
         t0 = time.time()
-        ok = 0
-        with concurrent.futures.ThreadPoolExecutor(a.parallel) as ex:
-            for good in ex.map(lambda p: push_one(url, p), prompts):
-                ok += 1 if good else 0
-        dt = time.time() - t0
+        ok = push_round(url, prompts, a.model, a.parallel)
+        dt = max(time.time() - t0, 1e-9)
         print(f"round {rnd}: {ok}/{len(prompts)} ok in {dt:.0f}s "
-              f"({sum(len(p) for p in prompts)/4/dt:.0f} chars/s est)",
-              flush=True)
+              f"({chars / 4 / dt:.0f} tokens/s est)", flush=True)
+        if ok == 0:
+            print("FAIL: not one prompt was accepted; fix the engine or the argv "
+                  "before spending another round", flush=True)
+            sys.exit(1)
         if tap_done(a.container):
             break
+        after = tap_bytes(a.tap_dir)
+        if after <= before:
+            print(f"FAIL: the tap at {a.tap_dir} sealed nothing this round "
+                  f"({before} B before, {after} B after) — the engine is serving "
+                  "without recording (wrong dir, full disk, read-only mount)", flush=True)
+            sys.exit(1)
     else:
         print("max rounds exhausted, tap not done", flush=True)
         sys.exit(1)

scripts/convert-qwen38-w5nl64.sh

@@ -0,0 +1,231 @@
+#!/usr/bin/env bash
+# convert-qwen38-w5nl64.sh — RUNS ON DANKSERVER. The CPU half of the Qwen3.8-Flash-Next five-bit
+# campaign: convert the vendor BF16 checkpoint into the campaign's arms, each one the whole
+# `w5nl64a8h` rung on BOTH expert projections with the protected experts kept bf16.
+#
+# Nothing here touches a GPU: the container is started without /dev/kfd or /dev/dri, so the
+# converter runs on the host backend and the fleet can keep serving through the whole script.
+# The engine pin is the digest that serves frank-archon, so a winning arm crosses no version
+# boundary between measurement and serving.
+#
+# Three arms, because the campaign's question is which search knob pays for its hours
+# (recipes/qwen4exp-qwen38-w5nl64-bf16trunk.recipe):
+#
+#   cd3     the recipe as written — coordinate descent three sweeps. The control.
+#   cd6     six sweeps: the same search, twice the passes.
+#   ao1     act_order=1 instead of cd: GPTQ sweeps columns in activation-importance order and
+#           stores them permuted. This is a SEPARATE arm, not a fourth sweep — libquant refuses
+#           cd= together with act_order=1 ("cd= sweeps the columns in their stored order, and
+#           act_order=1 stores them permuted; one or the other", libquant/lq_registry.cpp), so
+#           the two knobs cannot be combined into a best-of-both container.
+#
+# The arms are generated from ONE template with `--quant` overrides, not three near-duplicate
+# recipes: --quant rules are inserted BEFORE the recipe file and the first rule whose glob matches
+# a weight decides it (core/format/recipe.cpp: Recipe::match), so an override cleanly replaces the
+# expert line and the other 60 lines cannot drift between arms.
+#
+# Protected experts: apply-protected-cast.sh derives the bf16 set from THIS campaign's grams
+# (--target-count 48, two per layer so each rank's 256-expert half stays even) and splices it into
+# a per-run COPY of the template; the committed recipe keeps its markers and stays reviewable.
+#
+# Gates, in the order they bite — each one is a lesson the swift15 campaign paid for:
+#   inputs        checkpoint (dir + index), recipe, grams, imatrix, tokenizer. A missing grams
+#                 directory converts UNCALIBRATED with one stderr note, which is silently worse
+#                 than failing here.
+#   reference     the 335.3 GiB BF16 reference container must be GONE before the converts start.
+#                 It and the checkpoint together eat the volume; its job (the KLD recording and
+#                 the calibration grams) is finished by then, and both survive on disk without the
+#                 container beside it. The FP8-native anchor is FETCHED after the converts (disk
+#                 sequencing), so nothing here waits on it.
+#   plan          --plan-only runs FIRST, per arm, and prints "about X would be written". The
+#                 number is the bill: free space must cover it plus the 128k-prompt overshoot
+#                 margin, and the finished artifact is checked against it.
+#   outputs       no arm overwrites anything; move the old one to trash.
+#
+# Usage: convert-qwen38-w5nl64.sh [--arm cd3|cd6|ao1]... [--dry-run] [--plan-only]
+#                                 [--target-count N] [--keep-recipe]
+set -u -o pipefail
+
+SELF="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+IMAGE=${IMAGE:-stilldeadcode/radiance@sha256:d590e300234bf6d2f942a0b8d456d183153fd808f28820e6c2fa69c9389178ed}
+CKPT=${CKPT:-/home/dank/models/Qwen3.8-Flash-Next}
+CAMPAIGN=${CAMPAIGN:-/home/dank/campaign/qwen38-w5nl64}
+RECIPE=${RECIPE:-$SELF/recipes/qwen4exp-qwen38-w5nl64-bf16trunk.recipe}
+CALIB=${CALIB:-$CAMPAIGN/calib}
+IMATRIX=${IMATRIX:-$CAMPAIGN/imatrix.gguf}
+OUTDIR=${OUTDIR:-/home/dank/models/rad}
+BF16_RAD=${BF16_RAD:-$OUTDIR/qwen38-bf16.rad}   # the reference container, not an arm output
+STATE=${STATE:-$CAMPAIGN}                      # the dir the container mounts read-only: the
+                                               # spliced recipe and the imatrix live here
+TARGET_COUNT=${TARGET_COUNT:-48}
+MIN_GRAMS=${MIN_GRAMS:-24576}                 # per-expert DOWN grams: 48 recorded layers x 512
+                                               # experts. The checkpoint has 49 MoE layers, but the
+                                               # MTP layer is never recorded, so its 512 experts are
+                                               # absent from the tap's output by design
+MARGIN_MIB=${MARGIN_MIB:-40960}               # the long-prompt overshoot, off the plan number
+TS=$(date +%Y%m%d-%H%M%S)
+
+ARMS=()
+DRY=0
+PLAN_ONLY=0
+KEEP_RECIPE=0
+while [ "$#" -gt 0 ]; do
+    case "$1" in
+      --arm) [ "$#" -ge 2 ] || { echo "--arm needs a value (cd3|cd6|ao1)" >&2; exit 2; }
+             ARMS+=("$2"); shift 2 ;;
+      --dry-run) DRY=1; shift ;;
+      --plan-only) PLAN_ONLY=1; shift ;;
+      --target-count) [ "$#" -ge 2 ] || { echo "--target-count needs a value" >&2; exit 2; }
+             TARGET_COUNT="$2"; shift 2 ;;
+      --keep-recipe) KEEP_RECIPE=1; shift ;;
+      *) echo "unknown argument: $1" >&2; exit 2 ;;
+    esac
+done
+[ "${#ARMS[@]}" -gt 0 ] || ARMS=(cd3 cd6 ao1)
+for a in "${ARMS[@]}"; do
+    case "$a" in cd3|cd6|ao1) ;; *) echo "unknown arm: $a (cd3|cd6|ao1)" >&2; exit 2 ;; esac
+done
+
+# The expert rule's option set, spelled once. --quant replaces the template's line wholesale, so
+# every option has to be repeated here; `calib=$CALIB` is expanded by the recipe reader from the
+# container environment (core/format/recipe.cpp: expand refuses an unset name rather than taking
+# it for empty).
+expert_opts='table=w5nl,group=64,scale=fp8_e4m3,scale2=f32,block2=*x*,scale2_value=0.0001220703125,transform=fwht128,rule=search,calib=$CALIB'
+arm_quant() {
+    case "$1" in
+      # The control is the template itself: no override, so the recipe's own line decides.
+      cd3) return 0 ;;
+      cd6) echo "blk.*.ffn_*_exps.*.weight=gptq:${expert_opts},cd=6" ;;
+      # act_order=1 WITHOUT cd: libquant refuses the pair (lq_registry.cpp:105, "cd= sweeps the
+      # columns in their stored order, and act_order=1 stores them permuted; one or the other"), so
+      # this arm is the interleave knob alone, not cd=3 plus it.
+      ao1) echo "blk.*.ffn_*_exps.*.weight=gptq:${expert_opts},act_order=1" ;;
+    esac
+}
+
+# --- gates ------------------------------------------------------------------------------------
+[ -d "$CKPT" ] || { echo "no checkpoint at $CKPT; run scripts/download-qwen38-bf16.sh --fetch" >&2; exit 2; }
+[ -f "$CKPT/model.safetensors.index.json" ] || { echo "checkpoint at $CKPT has no safetensors index — a torn fetch" >&2; exit 2; }
+[ -f "$CKPT/tokenizer.json" ] || { echo "no tokenizer.json in $CKPT; the .rad cannot carry one without it" >&2; exit 2; }
+[ -f "$RECIPE" ] || { echo "no recipe at $RECIPE" >&2; exit 2; }
+GRAMS=$(find "$CALIB" -maxdepth 1 -name 'gram.r*.bin' 2>/dev/null | wc -l)
+[ "$GRAMS" -ge "$MIN_GRAMS" ] || {
+    echo "calib dir $CALIB holds $GRAMS gram files (<$MIN_GRAMS); run $0 after run-qwen38-bf16.sh calib" >&2; exit 2; }
+[ -f "$IMATRIX" ] || { echo "no imatrix at $IMATRIX; run scripts/grams-to-imatrix.py over $CALIB" >&2; exit 2; }
+# The container sees the campaign dir at one fixed mount point, so an imatrix kept elsewhere has
+# no path inside it: copy it in (or point IMATRIX at the campaign dir) rather than let the
+# converter fail halfway through a planned arm.
+[ "$(dirname "$IMATRIX")" = "$STATE" ] || {
+    echo "imatrix $IMATRIX is not in the campaign dir $STATE the container mounts; move it there" >&2; exit 2; }
+if [ -e "$BF16_RAD" ]; then
+    echo "the 335.3 GiB BF16 reference container $BF16_RAD is still on disk; its recording and" \
+         "the calibration grams are already taken, so move it to trash — the converts need its" \
+         "space (peak-disk law)" >&2
+    exit 2
+fi
+for a in "${ARMS[@]}"; do
+    [ -e "$OUTDIR/qwen38-w5nl64-$a.rad" ] && {
+        echo "$OUTDIR/qwen38-w5nl64-$a.rad already exists; move it to trash first" >&2; exit 2; }
+    # A killed run leaves its container behind (--rm only fires when podman itself
+    # exits), and the next arm then dies on "name already in use" AFTER the plan
+    # phase; refuse here, where the fix is one `podman rm -f`.
+    podman container exists "qwen38-convert-$a" && {
+        echo "container qwen38-convert-$a still exists (a killed run?);" \
+             "'podman rm -f qwen38-convert-$a' and re-run" >&2
+        exit 2; }
+done
+
+# --- the protected plane, spliced into a per-run copy of the template --------------------------
+mkdir -p "$STATE"
+WORK="$STATE/recipe-$TS.recipe"
+cp "$RECIPE" "$WORK"
+if [ "$DRY" = 1 ]; then
+    echo "would run: $SELF/apply-protected-cast.sh $CALIB $WORK $TARGET_COUNT"
+else
+    # Positional, because the tool reads its recipe and calib dir by position: passing them as
+    # environment variables would be silently ignored and it would rewrite the COMMITTED
+    # template in place instead of this run's copy.
+    "$SELF/apply-protected-cast.sh" "$CALIB" "$WORK" "$TARGET_COUNT" \
+        || { echo "the protected-expert derivation refused; the arms would convert unprotected" >&2; exit 1; }
+fi
+
+run_convert() { # run_convert ARM [extra flags...]
+    local arm="$1"; shift
+    local out="$OUTDIR/qwen38-w5nl64-$arm.rad" log="$STATE/convert-$arm-$TS.log"
+    local argv=(--rm --name "qwen38-convert-$arm"
+                -e "CALIB=/data/calib" -e "OMP_NUM_THREADS=$(nproc)"
+                -v "$(dirname "$CKPT"):/models:ro"
+                -v "$CALIB:/data/calib:ro"
+                -v "$STATE:/campaign:ro"
+                -v "$OUTDIR:/out")
+    local conv=(/models/"${CKPT##*/}" --recipe "/campaign/$(basename "$WORK")"
+                --tokenizer "/models/${CKPT##*/}/tokenizer.json"
+                --imatrix /campaign/"${IMATRIX##*/}"
+                # No --max-ctx: the context declare then runs at the checkpoint's training context
+                # (262144), which is what the shipped container did — rad-info --meta on it carries
+                # no override. A container declared at a smaller bound cannot be expected to serve
+                # the 200k window D2 holds, and the convert is not where to discover that.
+                # --kv-cache-dtype changes nothing in the artifact; it picks the kernels the declare
+                # checks, and the fleet serves fp8 KV, so an unresolvable fp8 kernel must be said no
+                # to by the convert, not by a boot on a drained window.
+                --kv-cache-dtype fp8 -o "/out/$(basename "$out")")
+    local q; q=$(arm_quant "$arm")
+    [ -n "$q" ] && conv+=(--quant "$q")
+    if [ "$DRY" = 1 ]; then
+        echo "podman run ${argv[*]} \$IMAGE --entrypoint /opt/radiance/bin/rad-convert ${conv[*]} $*"
+        return 0
+    fi
+    podman run "${argv[@]}" --entrypoint /opt/radiance/bin/rad-convert "$IMAGE" "${conv[@]}" "$@" \
+        2>&1 | tee "$log"
+    return "${PIPESTATUS[0]}"
+}
+
+# --- plan, then bill, then convert -------------------------------------------------------------
+overall=0
+for arm in "${ARMS[@]}"; do
+    echo "== arm $arm =="
+    if [ "$DRY" = 1 ]; then
+        # Both lines, in order: the plan runs before the convert, and the convert is what the
+        # operator is about to pay an afternoon for.
+        run_convert "$arm" --plan-only
+        run_convert "$arm"
+        continue
+    fi
+    rc=0; plan_log=$(run_convert "$arm" --plan-only) || rc=$?
+    [ "$rc" -eq 0 ] || { echo "arm $arm: --plan-only failed (rc=$rc); nothing was written" >&2; overall=1; continue; }
+    echo "$plan_log"
+    # "about 141.2 GiB would be written" is the converter's own bill; parse it rather than
+    # hardcoding a size, so the gate still works after any recipe edit.
+    want=$(printf '%s' "$plan_log" | sed -n 's/.*about \([0-9.]*\) \([KMGT]iB\) would be written.*/\1 \2/p' | tail -1)
+    [ -n "$want" ] || { echo "arm $arm: the plan printed no size; refusing to convert blind" >&2; overall=1; continue; }
+    need_mib=$(awk -v n="${want% *}" -v u="${want#* }" \
+        'BEGIN{ f = (u=="KiB") ? 2^-10 : (u=="MiB") ? 1 : (u=="GiB") ? 1024 : (u=="TiB") ? 1048576 : 0
+               if (f == 0) { exit 1 }; printf "%d", n*f + 0.5 }') || {
+        echo "arm $arm: the plan printed an unknown unit in '$want'" >&2; overall=1; continue; }
+    free_mib=$(df --output=avail -m "$OUTDIR" | tail -1 | tr -d ' ')
+    echo "plan: $want ($need_mib MiB); free ${free_mib} MiB on $OUTDIR (margin $MARGIN_MIB MiB)"
+    if [ "$free_mib" -lt $((need_mib + MARGIN_MIB)) ]; then
+        echo "arm $arm: needs ${need_mib} MiB + ${MARGIN_MIB} margin, ${free_mib} free; free space and re-run" >&2
+        overall=1; continue
+    fi
+    if [ "$PLAN_ONLY" = 1 ]; then echo "planned, not converted (--plan-only)"; continue; fi
+    rc=0; run_convert "$arm" || rc=$?
+    [ "$rc" -eq 0 ] || { echo "arm $arm: rad-convert rc=$rc; log: $STATE/convert-$arm-$TS.log" >&2; overall=1; continue; }
+    out="$OUTDIR/qwen38-w5nl64-$arm.rad"
+    [ -f "$out" ] || { echo "arm $arm: rad-convert exited 0 but wrote no $out; log: $STATE/convert-$arm-$TS.log" >&2; overall=1; continue; }
+    got_mib=$(( $(stat -c %s "$out") / 1048576 ))
+    # The receipt: the artifact is what the plan predicted, within the metadata the plan does not
+    # count. An arm that came out materially smaller lost a plane somewhere.
+    lo=$(( need_mib * 98 / 100 )); hi=$(( need_mib * 103 / 100 ))
+    if [ "$got_mib" -lt "$lo" ] || [ "$got_mib" -gt "$hi" ]; then
+        echo "arm $arm: $out is ${got_mib} MiB, the plan said ${need_mib} MiB (allowed ${lo}-${hi})" >&2
+        overall=1; continue
+    fi
+    echo "CONVERT_DONE $arm ${got_mib} MiB -> $out"
+done
+
+if [ "$KEEP_RECIPE" = 0 ] && [ "$DRY" = 0 ]; then
+    mkdir -p "$CAMPAIGN/.AGENTTRASH"
+    mv "$WORK" "$CAMPAIGN/.AGENTTRASH/$(basename "$WORK")" 2>/dev/null || true
+fi
+exit "$overall"

scripts/deploy-plan.py

@@ -34,12 +34,16 @@ SERVICE_ORDER = (
     "hermes",
     "hermes-dashboard",
     "hermes-webui",
-    "prometheus",
     "grafana",
     "loki",
     "alloy",
     "node-exporter",
+    "cadvisor",
+    "gpu-exporter",
     "alertmanager",
+    # The prober must answer before prometheus re-runs the services job.
+    "blackbox-exporter",
+    "prometheus",
     "authentik-postgres",
     "authentik-server",
     "authentik-worker",
@@ -92,7 +96,10 @@ DANKCLAW_SERVICES = {
     "loki",
     "alloy",
     "node-exporter",
+    "cadvisor",
+    "gpu-exporter",
     "alertmanager",
+    "blackbox-exporter",
     "authentik-postgres",
     "authentik-server",
     "authentik-worker",
@@ -124,6 +131,8 @@ DANKSERVER_SERVICES = {
     "readarr",
     "frank-archon",
     "node-exporter",
+    "cadvisor",
+    "gpu-exporter",
 }
 
 # FrankBook-Pro runs the *arr stack + qBittorrent inside a podman machine on
@@ -271,6 +280,8 @@ def services_for_path(path: str, target: str) -> set[str]:
             # Provisioned datasources and dashboards: git is the source of
             # truth, so a change here must restart the service that reads them.
             _add(services, "grafana")
+        elif group == "blackbox":
+            _add(services, "blackbox-exporter")
         elif group == "homepage":
             # Homepage is a Dankclaw-owned deployment. Shared homepage files
             # are intentionally not copied during a Dankserver-only run.
@@ -293,6 +304,17 @@ def services_for_path(path: str, target: str) -> set[str]:
         if len(parts) >= 2 and parts[1] in {"caddy", "comfyui", "loki", "alloy", "hermes", "anubis", "seerr"}:
             _add(services, parts[1])
             return services
+        if len(parts) >= 3 and parts[1] == "host":
+            # Host state a service needs at boot lives under dankclaw/host/.
+            # The fabric-clock hold is frank-dragoon's NPU precondition (the
+            # engine refuses to start with HALOGEN_NPU_MODELS set while the
+            # clock moves) and the deployer installs and gates it, so changing
+            # it re-dispatches that endpoint. `grub` is the tracked boot line,
+            # which moves only through scripts/set-dankclaw-bootline.sh and is
+            # a reboot decision — it plans no service.
+            if parts[2].startswith("halogen-fabric-clock"):
+                _add(services, "frank-dragoon")
+            return services
         if len(parts) >= 4 and parts[1] == "authentik" and parts[2] == "quadlet":
             name = parts[3].removesuffix(".container")
             if name in {"authentik-postgres", "authentik-server", "authentik-worker", "authentik-outpost", "authentik-outpost-ldap"}:
@@ -363,7 +385,7 @@ def services_for_path(path: str, target: str) -> set[str]:
             # consumer (prometheus before grafana, loki before alloy).
             if len(parts) >= 4 and parts[2] == "quadlet":
                 name = parts[3].removesuffix(".container")
-                if name in {"prometheus", "grafana", "loki", "alloy", "node-exporter", "alertmanager"}:
+                if name in {"prometheus", "grafana", "loki", "alloy", "node-exporter", "cadvisor", "alertmanager", "blackbox-exporter"}:
                     _add(services, name)
             return services
         if len(parts) >= 2 and parts[1] == "gitea":
@@ -406,8 +428,8 @@ def services_for_path(path: str, target: str) -> set[str]:
             # node-dankserver job had nothing to scrape.
             if len(parts) >= 4 and parts[2] == "quadlet":
                 name = parts[3].removesuffix(".container")
-                if name == "node-exporter":
-                    _add(services, "node-exporter")
+                if name in {"node-exporter", "cadvisor"}:
+                    _add(services, name)
             return services
         # frank-archon's quadlet-era directory left the tree on 2026-09-26
         # (the Lucebox DS4.1 unit was retired for the llama.cpp root unit —
@@ -438,6 +460,12 @@ def services_for_path(path: str, target: str) -> set[str]:
             # change to it redeploying alertmanager is the only path that
             # reaches it on the host.
             _add(services, "alertmanager")
+        if name in {"gpu-exporter.py", "gpu-exporter.service"}:
+            # The host-process GPU exporter is installed directly by the
+            # gpu-exporter deploy on BOTH hosts, so its script and unit select
+            # that service (target_services then keeps it only on the host being
+            # planned). Editing the collector restarts the running exporter.
+            _add(services, "gpu-exporter")
         if name in {"frank-zealot.env", "frank-zealot.service", "serve-frank-zealot.sh"}:
             # llama.cpp frank-zealot (2026-09-16) keeps its unit, env and serve
             # files here; each one selects frank-zealot only. The ik_llama.cpp

scripts/deploy-remote.sh

@@ -86,7 +86,7 @@ service_is_allowed() {
         dankclaw:open-webui|dankclaw:gitea-postgres|dankclaw:gitea-server|\
         dankclaw:comfyui|dankclaw:hermes|\
         dankclaw:hermes-dashboard|dankclaw:hermes-webui|dankclaw:prometheus|dankclaw:grafana|\
-        dankclaw:loki|dankclaw:alloy|dankclaw:node-exporter|dankclaw:alertmanager|\
+        dankclaw:loki|dankclaw:alloy|dankclaw:node-exporter|dankclaw:cadvisor|dankclaw:gpu-exporter|dankclaw:alertmanager|dankclaw:blackbox-exporter|\
         dankclaw:authentik-postgres|dankclaw:authentik-server|\
         dankclaw:authentik-worker|dankclaw:authentik-outpost|dankclaw:authentik-outpost-ldap|dankclaw:anubis|\
         dankclaw:caddy|dankclaw:homepage|dankclaw:seerr|dankclaw:marreta|\
@@ -97,7 +97,7 @@ service_is_allowed() {
         dankserver:copyparty|dankserver:jellyfin|dankserver:calibre-web|dankserver:calibre-server|dankserver:plex|dankserver:tautulli|\
         dankserver:prowlarr|dankserver:qbittorrent|dankserver:radarr|\
         dankserver:sonarr|dankserver:lidarr|dankserver:readarr|\
-        dankserver:frank-archon|dankserver:node-exporter|\
+        dankserver:frank-archon|dankserver:node-exporter|dankserver:cadvisor|dankserver:gpu-exporter|\
         frankbook-pro:gluetun|frankbook-pro:qbittorrent|frankbook-pro:prowlarr|\
         frankbook-pro:radarr|frankbook-pro:sonarr|frankbook-pro:lidarr|\
         frankbook-pro:readarr)
@@ -252,16 +252,24 @@ install_signal_relay() {
     # The relay binds the host's LAN IP (the one address a bridge container
     # can reach as host.containers.internal), so keep the unauthenticated
     # endpoint off the rest of the LAN: admit loopback, the host itself
-    # (its own health probe) and the podman bridge subnet only. Idempotent:
-    # -C before -I.
+    # (its own health probe) and the podman bridge subnet only.
+    # ORDER IS THE GATE: `iptables -I` inserts at position 1, so the old
+    # shape (-C/-I x3 ACCEPT, then -C/-I the DROP) landed the blanket DROP
+    # ABOVE the ACCEPTs and every probe timed out beside a LISTENing socket
+    # (live 2026-10-21: 159 packets on the DROP, 0 on each ACCEPT; the whole
+    # dankclaw drain aborted at the alertmanager gate twice before the cause
+    # was read off `nft list ruleset`). Rebuild the tail instead of inserting
+    # it: delete any blanket DROP wherever it sits, keep the three ACCEPTs
+    # at the head (-C before -I, unchanged), then APPEND the DROP so it is
+    # last and the ACCEPTs decide first. Converges on poisoned hosts.
+    run_privileged iptables -D INPUT -p tcp --dport 18093 -j DROP 2>/dev/null || true
     run_privileged iptables -C INPUT -p tcp --dport 18093 -s 127.0.0.1 -j ACCEPT 2>/dev/null \
         || run_privileged iptables -I INPUT -p tcp --dport 18093 -s 127.0.0.1 -j ACCEPT
     run_privileged iptables -C INPUT -p tcp --dport 18093 -s 192.168.0.143 -j ACCEPT 2>/dev/null \
         || run_privileged iptables -I INPUT -p tcp --dport 18093 -s 192.168.0.143 -j ACCEPT
     run_privileged iptables -C INPUT -p tcp --dport 18093 -s 10.89.0.0/16 -j ACCEPT 2>/dev/null \
         || run_privileged iptables -I INPUT -p tcp --dport 18093 -s 10.89.0.0/16 -j ACCEPT
-    run_privileged iptables -C INPUT -p tcp --dport 18093 -j DROP 2>/dev/null \
-        || run_privileged iptables -I INPUT -p tcp --dport 18093 -j DROP
+    run_privileged iptables -A INPUT -p tcp --dport 18093 -j DROP
     # The interpreter needs a moment to bind after restart; a one-shot curl
     # raced the socket on 2026-09-17 and failed a healthy deploy.
     local i
@@ -275,14 +283,81 @@ install_signal_relay() {
     return 1
 }
 
+# Host-process GPU metrics exporter (amdgpu sysfs + nvidia-smi). Not a quadlet:
+# it runs python3 from the checkout on the host so it can read the DRM/cgroup
+# sysfs and shell out to nvidia-smi. Same two-address bind posture as
+# node-exporter/cadvisor (loopback + this host's LAN), so it is never a wildcard.
+deploy_gpu_exporter() {
+    local unit_dir="$HOME/.config/systemd/user" lan dropin i
+    case "$TARGET" in
+        dankclaw) lan=192.168.0.143 ;;
+        dankserver) lan=192.168.0.235 ;;
+        *) echo "gpu-exporter: unknown target '$TARGET'" >&2; return 2 ;;
+    esac
+    mkdir -p "$unit_dir"
+    cp scripts/gpu-exporter.service "$unit_dir/gpu-exporter.service"
+    dropin="$unit_dir/gpu-exporter.service.d"
+    mkdir -p "$dropin"
+    printf '[Service]\nEnvironment=GPU_EXPORTER_BINDS=127.0.0.1,%s\n' "$lan" \
+        > "$dropin/bind.conf"
+    systemctl --user daemon-reload
+    systemctl --user enable gpu-exporter.service
+    systemctl --user restart gpu-exporter.service
+    # The interpreter needs a moment to bind after restart (the same race that
+    # once failed a healthy signal-relay deploy).
+    for i in $(seq 1 15); do
+        curl -fsS -m 5 http://127.0.0.1:9401/metrics >/dev/null && return 0
+        sleep 1
+    done
+    echo "gpu-exporter is not answering on 127.0.0.1:9401/metrics" >&2
+    return 1
+}
+
 copy_loki_config() {
     run_privileged mkdir -p /opt/loki/config
     run_privileged cp shared/loki/loki-config.yaml /opt/loki/config/loki-config.yaml
 }
 
 copy_alloy_config() {
-    run_privileged mkdir -p /opt/alloy/config
-    run_privileged cp shared/alloy/config.alloy /opt/alloy/config/config.alloy
+    # The repo config carries the token GRAFANA_HOST_LABEL; the installed copy
+    # carries the host's name, so Loki streams say WHICH machine's journal a
+    # line came from without a second config file per host.
+    # *_CONF_ROOT are test seams: the bats cases execute these copiers for
+    # real against a sandbox with a stubbed run_privileged.
+    local root="${ALLOY_CONF_ROOT:-/opt/alloy}" tmp
+    tmp="$(mktemp)"
+    sed "s/GRAFANA_HOST_LABEL/$TARGET/g" shared/alloy/config.alloy > "$tmp"
+    if ! grep -q "host = \"$TARGET\"," "$tmp" || grep -q "GRAFANA_HOST_LABEL" "$tmp"; then
+        echo "alloy config: host-label substitution failed" >&2
+        rm -f "$tmp"
+        return 1
+    fi
+    # Syntax gate: alloy's config language has no schema — a misplaced
+    # attribute (e.g. `on_error` outside the json stage) parses only at RUN
+    # time, and the unit then crash-loops with a healthy-looking deploy.
+    # Validate against the very image that will run it, before installing.
+    # Skipped only in the bats sandbox (no image there).
+    if [ "$root" = "/opt/alloy" ] || podman image exists localhost/franksdank/alloy:latest 2>/dev/null; then
+        if ! podman run --rm -v "$tmp:/c.alloy:ro" \
+                --entrypoint /usr/bin/alloy localhost/franksdank/alloy:latest \
+                validate /c.alloy; then
+            echo "alloy config: validate FAILED against the pinned image" >&2
+            rm -f "$tmp"
+            return 1
+        fi
+    fi
+    run_privileged mkdir -p "$root/config"
+    run_privileged cp "$tmp" "$root/config/config.alloy"
+    rm -f "$tmp"
+}
+
+copy_blackbox_config() {
+    # Single-file mount target: the unit binds this exact path into
+    # /etc/blackbox_exporter/config.yml. cp (not cp -r) keeps it one file.
+    # BLACKBOX_CONF_ROOT is the same test seam.
+    local root="${BLACKBOX_CONF_ROOT:-/opt/blackbox}"
+    run_privileged mkdir -p "$root"
+    run_privileged cp shared/blackbox/blackbox.yml "$root/blackbox.yml"
 }
 
 copy_grafana_provisioning() {
@@ -291,14 +366,25 @@ copy_grafana_provisioning() {
     # datasource would be invisible to review, lost with the data volume, and
     # unknown to anyone reading the repository. The unit already mounts
     # /opt/grafana/provisioning read-only, so this only has to populate it.
-    run_privileged mkdir -p /opt/grafana/provisioning/datasources \
-        /opt/grafana/provisioning/dashboards
+    # GRAFANA_PROV_ROOT is the test seam: point it at a sandbox and the whole
+    # copy runs unprivileged (the bats case executes this function for real).
+    local root="${GRAFANA_PROV_ROOT:-/opt/grafana}"
+    run_privileged mkdir -p "$root/provisioning/datasources" \
+        "$root/provisioning/dashboards"
     run_privileged cp shared/grafana/provisioning/datasources/prometheus.yml \
-        /opt/grafana/provisioning/datasources/prometheus.yml
+        "$root/provisioning/datasources/prometheus.yml"
     run_privileged cp shared/grafana/provisioning/dashboards/provider.yml \
-        /opt/grafana/provisioning/dashboards/provider.yml
-    run_privileged cp shared/grafana/provisioning/dashboards/llm-fleet.json \
-        /opt/grafana/provisioning/dashboards/llm-fleet.json
+        "$root/provisioning/dashboards/provider.yml"
+    # EVERY dashboard JSON rides, not a hand-listed subset: the fleet provider
+    # turns each file in the directory into a dashboard, so a copier that names
+    # files one by one silently drops new boards (measured 2026-10-21: the
+    # containers board existed in the repo since its commit and was NEVER
+    # provisioned — the panel-census browser check could not find it while the
+    # hand-placed older boards happened to be on disk). Same rule as the quadlet
+    # tier: the directory is the contract, the copy is generated state.
+    for dash in shared/grafana/provisioning/dashboards/*.json; do
+        run_privileged cp "$dash" "$root/provisioning/dashboards/$(basename "$dash")"
+    done
 }
 
 render_caddyfile() {
@@ -487,13 +573,15 @@ seed_grafana_env() {
         || { echo "grafana env missing GRAFANA_OAUTH_CLIENT_SECRET; set it in dankclaw/.env" >&2; return 1; }
 }
 
-# The five observability containers left compose on 2026-09-11 (they were
-# started by hand with podman-compose and never came back after a reboot).
-# They are ordinary rootless Quadlet units now: same images, same mounts, same
-# arguments, same container names, so nothing that addresses them by name —
-# Caddy, Prometheus' own scrape config, Alloy's loki.write endpoint — changed.
-# Only the published ports did: the three HTTP UIs bind 127.0.0.1, because the
-# compose services published on 0.0.0.0 and none of them authenticates.
+# The observability containers left compose on 2026-09-11 (they were started by
+# hand with podman-compose and never came back after a reboot). Five are ordinary
+# rootless Quadlet units: same images, same mounts, same arguments, same
+# container names, so nothing that addresses them by name — Caddy, Prometheus'
+# own scrape config — changed. Only the published ports did: the three HTTP UIs
+# bind 127.0.0.1, because the compose services published on 0.0.0.0 and none of
+# them authenticates. Alloy is the exception: a ROOT system service on
+# Network=host, because reading the host journal needs privileges a rootless
+# container cannot get. It is handled by deploy_alloy, not the loop below.
 deploy_observability() {
     local service="$1"
     # Observability units live under <target>/observability/quadlet: Dankclaw
@@ -512,16 +600,17 @@ deploy_observability() {
             copy_loki_config
             build_compose_image loki
             ;;
-        alloy)
-            copy_alloy_config
-            build_compose_image alloy
-            ;;
         grafana)
             copy_grafana_provisioning
             seed_grafana_env || return 1
             ;;
         node-exporter)
             ;;
+        cadvisor)
+            ;;
+        blackbox-exporter)
+            copy_blackbox_config
+            ;;
         *)
             echo "unknown observability service: $service" >&2
             return 2
@@ -534,11 +623,75 @@ deploy_observability() {
         alertmanager) wait_for_health alertmanager http://127.0.0.1:9093/-/healthy 60 ;;
         grafana) wait_for_health grafana http://127.0.0.1:3002/api/health 90 ;;
         loki) wait_for_health loki http://127.0.0.1:3100/ready 60 ;;
-        alloy) wait_for_health alloy http://127.0.0.1:12345/-/healthy 60 ;;
         node-exporter) wait_for_health node-exporter http://127.0.0.1:9100/metrics 60 ;;
+        cadvisor) wait_for_health cadvisor http://127.0.0.1:8080/healthz 90 ;;
+        # Loopback: the exporter binds 127.0.0.1 + LAN (the gateway address
+        # is not bindable from the host netns — see the unit header).
+        blackbox-exporter) wait_for_health blackbox-exporter http://127.0.0.1:9115/-/healthy 60 ;;
     esac
 }
 
+# Mirror an image the deployer built rootless into the ROOT image store. A root
+# quadlet reads root storage; a root build (build_compose_image is rootless) is
+# not possible on this host — the build container's resolver fails DNS — so the
+# only way to get a root-readable copy is save-and-load. Compares image ids so a
+# rebuilt alloy actually re-lands in root storage instead of leaving a stale tag.
+mirror_image_to_root() {
+    local ref="$1" rid
+    rid="$(podman image inspect "$ref" --format '{{.Id}}' 2>/dev/null)" || {
+        echo "ERROR: rootless image $ref is not built; cannot mirror to root" >&2
+        return 1
+    }
+    if [[ "$(run_privileged podman image inspect "$ref" --format '{{.Id}}' 2>/dev/null)" == "$rid" ]]; then
+        return 0
+    fi
+    local tar; tar="$(mktemp /var/tmp/alloy-mirror.XXXXXX.tar)"
+    podman save -o "$tar" "$ref"
+    run_privileged podman load -i "$tar"
+    rm -f "$tar"
+}
+
+# Install a quadlet into the SYSTEM generator dir (root manager) instead of the
+# user dir. Boot persistence is the unit's own [Install] section (multi-user
+# target); the v1 system generator creates the .wants on daemon-reload, so —
+# like the user units — no `systemctl enable` (generated units cannot be enabled
+# here).
+install_system_quadlet() {
+    local source_dir="$1" unit="$2"
+    run_privileged mkdir -p /etc/containers/systemd
+    run_privileged cp "$source_dir/$unit.container" /etc/containers/systemd/
+    run_privileged systemctl daemon-reload
+}
+
+# Alloy as a ROOT system service on Network=host. See the unit file: a rootless
+# container cannot read the 0640 journal files, and it cannot reach Loki's
+# 127.0.0.1:3100 publish from a bridge netns. Root + host network fixes both;
+# the price is that this one container runs as root and on the host network.
+deploy_alloy() {
+    copy_alloy_config
+    build_compose_image alloy                      # rootless build (resolver works)
+    mirror_image_to_root localhost/franksdank/alloy:latest
+
+    # Retire the rootless unit BEFORE the system one starts: both managers
+    # generate alloy.service, and two containers named "alloy" both binding
+    # 127.0.0.1:12345 cannot coexist. Move the user quadlet out of the generator
+    # dir (it regenerates from there) and stop the user unit.
+    if [[ -f "$quadlet_unit_dir/alloy.container" ]] ||
+       systemctl --user is-active --quiet alloy.service 2>/dev/null; then
+        systemctl --user stop alloy.service 2>/dev/null || true
+        if [[ -f "$quadlet_unit_dir/alloy.container" ]]; then
+            local trash="$HOME/.AGENTTRASH/$(date +%Y%m%d)-alloy-root-cutover"
+            mkdir -p "$trash"
+            mv -- "$quadlet_unit_dir/alloy.container" "$trash/alloy.container"
+            echo "retired rootless alloy.container -> $trash"
+        fi
+        systemctl --user daemon-reload
+    fi
+
+    install_system_quadlet dankclaw/observability/quadlet alloy
+    run_privileged systemctl restart alloy.service
+    wait_for_health alloy http://127.0.0.1:12345/-/healthy 60
+}
 build_compose_image() {
     local service="$1" image cfhash oldhash containerfile
     # Every file the image COPIES IN, beside the Containerfile. The skip below
@@ -1310,9 +1463,10 @@ deploy_anubis() {
 # conversion (2026-10-11) of the abliterated Qwen3.8-Flash-Next —
 # qwen38-flash-next-v2-abliterated.hgn (66,687,678,432 B, ~62 GiB resident)
 # + the REQUIRED n-gram lookup table + the vision tower — MTP spec decode
-# (HALOGEN_SPEC_ADAPT=0), 2 slots over ONE 401,408-position KV pool (2 × ctx,
-# raised 2026-10-18 so BOTH slots can hold a maximum-length request) at the
-# ctx 200704 ceiling, image input — on the Strix Halo iGPU. It stays a
+# (HALOGEN_SPEC_ADAPT=0), 2 slots over ONE 401,408-position KV pool at the
+# native ctx 262144 ceiling (raised 2026-10-21 from 200704 so the harness can
+# run a 200,000 window with its ~45k fit gap; the pool still carries two
+# 200k conversations at once), image input — on the Strix Halo iGPU. It stays a
 # ROOT unit because the serve script drives `podman run` directly (the frank-archon pattern):
 # relink_unit points /etc/systemd/system/frank-dragoon.service at the repo
 # file, boot persistence is that unit's [Install], and LimitMEMLOCK=infinity
@@ -1329,6 +1483,9 @@ deploy_anubis() {
 # port gate is the same as every cutover since 2026-09-16: nothing
 # starts until 7770 is released.
 LLM_DRAGOON_IMAGE="${LLM_DRAGOON_IMAGE:-ghcr.io/peonist-ai/halogen-flash-server@sha256:0c61bf84ac22308a53f5d1ca6b86806702d7039e5ebc51cae4c66621b92fe04a}"
+# The payload dir is its own twin because the NPU lane's containment gate below
+# reads it; every artifact path under it stays a full literal as usual.
+LLM_DRAGOON_MODEL_DIR="${LLM_DRAGOON_MODEL_DIR:-/home/dank/models/halogen-v2-abliterated}"
 LLM_DRAGOON_CKPT="${LLM_DRAGOON_CKPT:-/home/dank/models/halogen-v2-abliterated/qwen38-flash-next-v2-abliterated.hgn}"
 LLM_DRAGOON_CKPT_BYTES="${LLM_DRAGOON_CKPT_BYTES:-66687678432}"
 LLM_DRAGOON_NGRAM="${LLM_DRAGOON_NGRAM:-/home/dank/models/halogen-v2-abliterated/qwen38-flash-next-ngram.hgn}"
@@ -1337,6 +1494,18 @@ LLM_DRAGOON_VISION="${LLM_DRAGOON_VISION:-/home/dank/models/halogen-v2-abliterat
 LLM_DRAGOON_VISION_BYTES="${LLM_DRAGOON_VISION_BYTES:-897916416}"
 LLM_DRAGOON_TOK_DIR="${LLM_DRAGOON_TOK_DIR:-/home/dank/models/halogen-v2-abliterated/tokenizer}"
 LLM_DRAGOON_TOK_FILES="${LLM_DRAGOON_TOK_FILES:-tokenizer.json chat_template.jinja tokenizer_config.json merges.txt vocab.json generation_config.json}"
+# NPU lane (2026-10-19). HALOGEN_NPU_MODELS is the whole switch and the parity
+# twin of the env file's line: empty here AND in the env = the pre-lane
+# endpoint. The gates below mirror serve-frank-dragoon.sh, and the vendor's
+# fabric-clock host unit (dankclaw/host/, verbatim at tag v0.16.2) is installed
+# ONLY while the lane is named — on Strix Halo the iGPU and the NPU co-running
+# hang the machine while the fabric clock moves, so halogen refuses to boot with
+# the lane armed unless that clock is held.
+LLM_DRAGOON_NPU_MODELS="${LLM_DRAGOON_NPU_MODELS:-qwen3-embedding-0.6b}"
+LLM_DRAGOON_NPU_DIR="${LLM_DRAGOON_NPU_DIR:-/home/dank/models/halogen-v2-abliterated/npu}"
+LLM_DRAGOON_DEV_ACCEL="${LLM_DRAGOON_DEV_ACCEL:-/dev/accel/accel0}"
+LLM_DRAGOON_XRT_DIR="${LLM_DRAGOON_XRT_DIR:-/usr/lib/x86_64-linux-gnu}"
+LLM_DRAGOON_NETWORK="${LLM_DRAGOON_NETWORK:-dankclaw_default}"
 
 retire_halogen_dragoon_quadlet() {
     local trash="$HOME/.AGENTTRASH/20260919-orca-cutover/quadlet"
@@ -1415,6 +1584,77 @@ deploy_llm_dragoon() {
         fi
     done
 
+    # The container network has to exist before the run line names it (a typo
+    # there is a restart-looping unit, not a config error anyone reads).
+    if [[ -n "$LLM_DRAGOON_NETWORK" ]] && ! podman network exists "$LLM_DRAGOON_NETWORK"; then
+        echo "ERROR: podman network $LLM_DRAGOON_NETWORK does not exist" >&2
+        echo "frank-dragoon: create it or blank FRANK_DRAGOON_NETWORK (pasta default)" >&2
+        return 1
+    fi
+
+    # --- NPU lane: the same predicates the serve script checks --------------
+    if [[ -n "$LLM_DRAGOON_NPU_MODELS" ]]; then
+        # One door into the container: the read-only /models mount of the
+        # payload dir. A staging dir outside it needs a nested bind whose
+        # mountpoint runc cannot create through a read-only parent, so the
+        # parity twin of the serve gate refuses the shape before the restart.
+        if [[ "$LLM_DRAGOON_NPU_DIR/" != "$LLM_DRAGOON_MODEL_DIR"/* ]]; then
+            echo "ERROR: NPU staging dir $LLM_DRAGOON_NPU_DIR is outside the payload dir $LLM_DRAGOON_MODEL_DIR — the lane's files reach the container only through the read-only /models mount" >&2
+            return 1
+        fi
+        if [[ ! -e "$LLM_DRAGOON_DEV_ACCEL" ]]; then
+            echo "ERROR: NPU node $LLM_DRAGOON_DEV_ACCEL absent — amdxdna is not bound (is iommu=pt still on the boot line?)" >&2
+            return 1
+        fi
+        # Access, not existence: a rootless container cannot open a root:render
+        # 0660 node (its namespace maps one uid/gid, and keep-groups cannot grant
+        # an unmapped gid — measured 2026-10-19). Install the mode rule, re-trigger
+        # the node, then PROVE the node is other-accessible before the restart.
+        run_privileged install -m 0644 dankclaw/udev/98-halogen-npu-access.rules \
+            /etc/udev/rules.d/98-halogen-npu-access.rules
+        run_privileged udevadm control --reload-rules
+        run_privileged udevadm trigger --sysname-match="$(basename "$LLM_DRAGOON_DEV_ACCEL")"
+        # (`-o FILE` is not "other-writable" — it means "exists", and `-o` is also
+        # the OR operator inside test), so the bit is read straight off the mode.
+        if [[ $(( 8#$(stat -c '%a' "$LLM_DRAGOON_DEV_ACCEL") & 8#2 )) -eq 0 ]]; then
+            echo "ERROR: $LLM_DRAGOON_DEV_ACCEL is still $(stat -c '%a %U:%G' "$LLM_DRAGOON_DEV_ACCEL") after installing the access rule — the lane cannot open it rootless" >&2
+            return 1
+        fi
+        for xl in libxrt_coreutil.so.2 libxrt_core.so.2 libxrt_driver_xdna.so.2; do
+            if [[ ! -e "$LLM_DRAGOON_XRT_DIR/$xl" ]]; then
+                echo "ERROR: XRT NPU library $LLM_DRAGOON_XRT_DIR/$xl absent (Ubuntu libxrt2 + libxrt-npu2)" >&2
+                return 1
+            fi
+        done
+        for nm in ${LLM_DRAGOON_NPU_MODELS//,/ }; do
+            if [[ ! -d "$LLM_DRAGOON_NPU_DIR/$nm" ]]; then
+                echo "ERROR: NPU model $nm not staged in $LLM_DRAGOON_NPU_DIR" >&2
+                echo "frank-dragoon: stage it: bash scripts/download-frank-dragoon-npu.sh" >&2
+                return 1
+            fi
+        done
+        # The hold must exist BEFORE the engine starts and survive every boot
+        # (a resume hands the clock back too — the unit's WantedBy covers it).
+        run_privileged install -m 0755 dankclaw/host/halogen-fabric-clock \
+            /usr/local/sbin/halogen-fabric-clock
+        run_privileged install -m 0644 dankclaw/host/halogen-fabric-clock.service \
+            /etc/systemd/system/halogen-fabric-clock.service
+        run_privileged systemctl daemon-reload
+        run_privileged systemctl enable --now halogen-fabric-clock.service
+        if ! run_privileged /usr/local/sbin/halogen-fabric-clock status; then
+            echo "ERROR: fabric clock is not held — halogen refuses to start with HALOGEN_NPU_MODELS set" >&2
+            echo "frank-dragoon: journalctl -u halogen-fabric-clock.service -n 40" >&2
+            return 1
+        fi
+    elif [[ -x /usr/local/sbin/halogen-fabric-clock ]]; then
+        # Lane rolled back: hand the clock back to the driver and drop the boot
+        # hook. `disable` deletes the INSTALLED copy of this unit — unlike the
+        # tracked LLM unit symlinks the fleet's disable law protects, this file
+        # is repo-owned and the next lane-on deploy reinstalls it.
+        run_privileged systemctl disable halogen-fabric-clock.service 2>/dev/null || true
+        run_privileged /usr/local/sbin/halogen-fabric-clock release || true
+    fi
+
     retire_halogen_dragoon_quadlet
     # The predecessor on a re-deploy is THIS unit: stop it (ExecStop stops
     # the container) before waiting on the port. The stray sweep is keyed
@@ -1434,6 +1674,33 @@ deploy_llm_dragoon() {
     run_privileged systemctl enable frank-dragoon.service
     run_privileged systemctl restart frank-dragoon.service
     wait_for_health frank-dragoon http://127.0.0.1:7770/health 1200
+    # The lane's own gate. /health proves the engine is up, nothing about the
+    # NPU programs; one real embedding is the observable output. The first
+    # request after a boot is a warmup artifact (fleet law), so retry before
+    # calling a booted lane dead.
+    if [[ -n "$LLM_DRAGOON_NPU_MODELS" ]]; then
+        for nm in ${LLM_DRAGOON_NPU_MODELS//,/ }; do
+            lane_ok=0
+            for _try in 1 2 3 4 5; do
+                if curl -fsS -m 60 -H 'content-type: application/json' \
+                        -d "{\"model\":\"$nm\",\"input\":[\"frank-dragoon npu lane gate\"]}" \
+                        http://127.0.0.1:7770/v1/embeddings 2>/dev/null \
+                   | python3 -c 'import json,sys
+v = json.load(sys.stdin)["data"][0]["embedding"]
+raise SystemExit(0 if isinstance(v, list) and len(v) and all(isinstance(x, (int, float)) for x in v) else 1)'; then
+                    lane_ok=1
+                    break
+                fi
+                sleep 10
+            done
+            if [[ "$lane_ok" != 1 ]]; then
+                echo "ERROR: NPU model $nm answered no vector on /v1/embeddings" >&2
+                echo "frank-dragoon: read the boot ledger: tail -100 /home/dank/logs/frank_dragoon.log" >&2
+                return 1
+            fi
+            echo "frank-dragoon: NPU lane verified — $nm embedded"
+        done
+    fi
 }
 
 # deploy_llm_zealot — frank-zealot is llama.cpp (PrismML fork build) on the
@@ -1463,6 +1730,12 @@ LLM_ZEALOT_RUNTIME="${LLM_ZEALOT_RUNTIME:-/home/dank/GitPackages/llama-prism-b10
 # 868.32 MiB worst-case VRAM (595.29 model + 248.10 compute in the boot ledger)
 # lands AFTER the engine's fit check, so it is not inside the q8_0 budget.
 LLM_ZEALOT_MMPROJ="${LLM_ZEALOT_MMPROJ:-/home/dank/models/Bonsai2-9B-MTP/Ternary-Bonsai-2-9B-mmproj-Q8_0.gguf}"
+# The refusal adapter is part of the payload identity now, so the deployer
+# checks it beside the other two files — but it has its OWN fetcher, so a
+# missing adapter must not send the operator to the bonsai9 script. Integrity
+# (bytes + sha256) is the fetcher's job at download time; this gate only asks
+# whether the file the env names exists, exactly like the two above.
+LLM_ZEALOT_LORA="${LLM_ZEALOT_LORA:-/home/dank/models/Bonsai2-9B-MTP/Ternary-Bonsai-2-9B-Uncensored-LoRA.gguf}"
 
 deploy_llm_zealot() {
     # Refuse rather than restart-loop: a unit whose runtime or payload is
@@ -1484,6 +1757,13 @@ deploy_llm_zealot() {
             return 1
         fi
     done
+    if [[ ! -f "$LLM_ZEALOT_LORA" ]]; then
+        echo "ERROR: frank-zealot refusal adapter absent at $LLM_ZEALOT_LORA" >&2
+        echo "frank-zealot: run scripts/download-frank-zealot-uncensored-lora.sh first;" >&2
+        echo "frank-zealot: the env names the adapter, so the unit would refuse to boot" >&2
+        echo "frank-zealot: without it — starting the unit anyway is a crash loop." >&2
+        return 1
+    fi
     relink_unit frank-zealot
     run_privileged systemctl daemon-reload
     run_privileged systemctl enable frank-zealot.service
@@ -1815,7 +2095,9 @@ deploy_service() {
         copyparty) deploy_copyparty ;;
         plex) deploy_plex ;;
         tautulli) deploy_tautulli ;;
-        prometheus|grafana|loki|alloy|node-exporter|alertmanager) deploy_observability "$service" ;;
+        alloy) deploy_alloy ;;
+        prometheus|grafana|loki|node-exporter|cadvisor|alertmanager|blackbox-exporter) deploy_observability "$service" ;;
+        gpu-exporter) deploy_gpu_exporter ;;
         comfyui) deploy_comfyui ;;
         *) deploy_compose_service "$service" ;;
     esac

scripts/deploy.sh

@@ -133,13 +133,15 @@ fi
 valid_service() {
     local service="$1"
     case "$TARGET:$service" in
+        # dankclaw:searxng-network is client-only: a network quadlet with no
+        # remote dispatch handler, so the remote gate does not (must not) list it.
         dankclaw:caddy|dankclaw:gluetun|dankclaw:searxng-network|dankclaw:searxng-valkey|\
         dankclaw:searxng|dankclaw:marreta|dankclaw:pihole|dankclaw:open-webui|dankclaw:gitea-postgres|\
         dankclaw:gitea-server|dankclaw:homepage|\
         dankclaw:comfyui|dankclaw:hermes|dankclaw:hermes-dashboard|\
         dankclaw:hermes-webui|dankclaw:prometheus|dankclaw:grafana|dankclaw:loki|dankclaw:alloy|\
-        dankclaw:alertmanager|\
-        dankclaw:node-exporter|dankclaw:authentik-postgres|dankclaw:authentik-server|\
+        dankclaw:alertmanager|dankclaw:blackbox-exporter|\
+        dankclaw:node-exporter|dankclaw:cadvisor|dankclaw:gpu-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|\
@@ -147,8 +149,8 @@ valid_service() {
         dankserver:romm-mariadb|dankserver:romm-redis|dankserver:romm|\
         dankserver:copyparty|dankserver:jellyfin|dankserver:calibre-web|dankserver:calibre-server|dankserver:plex|dankserver:tautulli|\
         dankserver:qbittorrent|dankserver:radarr|dankserver:sonarr|\
-        dankserver:lidarr|dankserver:readarr|dankserver:node-exporter|\
-        dankserver:frank-archon|\
+        dankserver:lidarr|dankserver:readarr|dankserver:node-exporter|dankserver:cadvisor|dankserver:gpu-exporter|\
+        dankserver:prowlarr|dankserver:frank-archon|\
         frankbook-pro:gluetun|frankbook-pro:qbittorrent|frankbook-pro:prowlarr|\
         frankbook-pro:radarr|frankbook-pro:sonarr|frankbook-pro:lidarr|\
         frankbook-pro:readarr)

scripts/derive-protected-experts.py

@@ -20,9 +20,16 @@ of the Gram is its down-input energy. Rank halves: 0-255, 256-511
 Output: the cast-rule lines (recipe format) on stdout, a report on stderr.
 
 Usage: derive-protected-experts.py <calib dir> [--min-share 0.03]
-       [--min-route-mult 3.0]
+       [--min-route-mult 3.0] [--target-count 0]
+       --target-count N fills the byte bill: the bars pick the base set exactly as
+       the bar-only pass does, then the energy ranking admits experts one at a time
+       (each with its parity partner) until the count lands. The energy bar NEVER
+       relaxes, so asking for 48 bf16 experts never quietly buys 80; the ratio bar
+       walks down only when the ranking cannot produce that many candidates.
+       0 takes the bars as given.
 """
 import argparse
+import collections
 import glob
 import os
 import re
@@ -32,6 +39,7 @@ import sys
 import numpy as np
 
 NAME_RE = re.compile(r"^gram\.r(\d)\.blk\.(\d+)\.ffn_down_exps\.(\d+)\.bin$")
+CAST_RE = re.compile(r"^blk\.(\d+)\.ffn_\*_exps\.(\d+)\.weight")
 
 
 def read_gram(path):
@@ -49,27 +57,8 @@ def read_gram(path):
     return k, rank, int(rows), tr
 
 
-def main():
-    ap = argparse.ArgumentParser()
-    ap.add_argument("calib_dir")
-    ap.add_argument("--min-share", type=float, default=0.03)
-    ap.add_argument("--min-route-mult", type=float, default=3.0)
-    a = ap.parse_args()
-
-    # layer -> global expert -> (rank, rows, energy)
-    data = {}
-    for path in sorted(glob.glob(os.path.join(
-            a.calib_dir, "gram.r*.ffn_down_exps.*.bin"))):
-        m = NAME_RE.match(os.path.basename(path))
-        if not m:
-            continue
-        rank, layer, expert = int(m.group(1)), int(m.group(2)), int(m.group(3))
-        k, _, rows, tr = read_gram(path)
-        data.setdefault(layer, {})[expert] = (rank, rows, tr)
-
-    if not data:
-        raise SystemExit("no per-expert down grams found")
-
+def select(data, min_share, min_route_mult):
+    """(cast lines, report lines, count) for one pair of bars."""
     lines, report = [], []
     total = 0
     for layer in sorted(data):
@@ -83,7 +72,7 @@ def main():
         for e, (rank, rows, tr) in experts.items():
             es, rs = tr / tot_e, rows / max(tot_r, 1)
             rec = (e, rank, es, rs)
-            if es >= a.min_share and es >= a.min_route_mult * rs:
+            if es >= min_share and es >= min_route_mult * rs:
                 qual.append(rec)
             elif es > 0:
                 pool.append(rec)
@@ -107,10 +96,148 @@ def main():
                           f"energy {es*100:5.2f}%, routing {rs*100:5.3f}%, "
                           f"ratio {es/max(rs,1e-12):6.1f}")
         total += len(chosen)
+    return lines, report, total
+
+
+def parity_repair(chosen, by_half, report, only=None):
+    """Add the next-best candidate to every half — or to `only` — holding an odd count.
+
+    The four-bit GEMM takes each half's remainder as two equal tables, so an odd count
+    of bf16 experts on a half is not a style problem: the two tables would not match.
+    `by_half` is energy-descending, so the first unchosen candidate is the next most
+    energetic, which is the expert worth keeping. Returns how many were added.
+    """
+    added = 0
+    for key in ([only] if only is not None else sorted(by_half)):
+        layer, half = key
+        n = sum(1 for (l, x) in chosen if l == layer and x // 256 == half)
+        if n % 2 == 0:
+            continue
+        for e, es, rs in by_half.get(key, []):
+            if (layer, e) not in chosen:
+                chosen[(layer, e)] = (es, rs)
+                added += 1
+                report.append(f"blk.{layer}: half {half} odd -> added e{e} "
+                              f"(energy {es*100:.2f}%)")
+                break
+        else:
+            report.append(f"blk.{layer}: half {half} holds {n} and no candidate is "
+                          f"left to make it even")
+    return added
+
+
+def select_to_count(data, min_share, min_route_mult, target):
+    """(lines, report, total, cutoff) for the set that LANDS the count.
+
+    The bars decide the base set; the count is then filled from the energy ranking,
+    one expert at a time, each addition taking its half's next-best candidate with it
+    so every rank's half stays even. Only the RATIO bar walks down to find candidates
+    — it is the law that says an expert is disproportionate and not merely busy, and
+    the caller's byte bill has to be filled — while the ENERGY bar holds, because that
+    bar is what the extra GiB of bf16 is supposed to buy. `cutoff` is the energy share
+    the set bottoms out at: the bar this campaign actually converted with.
+    """
+    report = []
+    shares, ranked = {}, []
+    for layer in sorted(data):
+        experts = data[layer]
+        tot_e = sum(v[2] for v in experts.values())
+        tot_r = sum(v[1] for v in experts.values())
+        if tot_e <= 0 or tot_r <= 0:
+            report.append(f"blk.{layer}: empty recording, skipped")
+            continue
+        for e, (_rank, rows, tr) in experts.items():
+            es, rs = tr / tot_e, rows / max(tot_r, 1)
+            if es <= 0:
+                continue
+            shares[(layer, e)] = (es, rs)
+            ranked.append((es, layer, e, rs))
+    ranked.sort(key=lambda r: (-r[0], r[1], r[2]))
+    by_half = {}
+    for es, layer, e, rs in ranked:
+        by_half.setdefault((layer, e // 256), []).append((e, es, rs))
+
+    chosen = {k: v for k, v in shares.items()
+              if v[0] >= min_share and v[0] >= min_route_mult * v[1]}
+    total = len(chosen)
+    total += parity_repair(chosen, by_half, report)
+
+    mult = min_route_mult
+    while True:
+        pool = [(es, l, e, rs) for es, l, e, rs in ranked
+                if es >= mult * rs and (l, e) not in chosen]
+        if len(pool) + total >= target or mult <= 0.0:
+            break
+        mult -= 0.5
+        report.append(f"ratio bar {mult + 0.5:g} leaves {len(pool)} fill candidates "
+                      f"for {target - total} slots; relaxing toward 0")
+    for es, layer, e, rs in pool:
+        if total >= target:
+            break
+        if (layer, e) in chosen:
+            continue
+        chosen[(layer, e)] = (es, rs)
+        total += 1
+        report.append(f"blk.{layer}: count fill -> added e{e} (energy {es*100:.2f}%)")
+        total += parity_repair(chosen, by_half, report, only=(layer, e // 256))
+    lines, cutoff = [], None
+    for (layer, e) in sorted(chosen):
+        es, rs = chosen[(layer, e)]
+        cutoff = es if cutoff is None else min(cutoff, es)
+        lines.append(f"blk.{layer}.ffn_*_exps.{e}.weight         cast dtype=bf16")
+    return lines, report, total, cutoff
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument("calib_dir")
+    ap.add_argument("--min-share", type=float, default=0.03)
+    ap.add_argument("--min-route-mult", type=float, default=3.0)
+    ap.add_argument("--target-count", type=int, default=0)
+    a = ap.parse_args()
+
+    # layer -> global expert -> (rank, rows, energy)
+    data = {}
+    for path in sorted(glob.glob(os.path.join(
+            a.calib_dir, "gram.r*.ffn_down_exps.*.bin"))):
+        m = NAME_RE.match(os.path.basename(path))
+        if not m:
+            continue
+        rank, layer, expert = int(m.group(1)), int(m.group(2)), int(m.group(3))
+        k, _, rows, tr = read_gram(path)
+        data.setdefault(layer, {})[expert] = (rank, rows, tr)
+
+    if not data:
+        raise SystemExit("no per-expert down grams found")
+
+    if a.target_count > 0:
+        lines, report, total, cutoff = select_to_count(
+            data, a.min_share, a.min_route_mult, a.target_count)
+        bar = f"energy cutoff {cutoff:.3g}" if cutoff is not None else "no candidates"
+    else:
+        lines, report, total = select(data, a.min_share, a.min_route_mult)
+        bar = f"min-share {a.min_share:.3g}"
+
+    # The emitted lines ARE the contract with the four-bit GEMM: every rank's half of
+    # every layer must hold an even number of bf16 experts. Judged on the output and
+    # not on the internal sets, so a slip in either pass is caught here rather than at
+    # engine load time.
+    halves = collections.Counter()
+    for rule in lines:
+        m = CAST_RE.match(rule)
+        if m:
+            halves[(int(m.group(1)), int(m.group(2)) // 256)] += 1
+    odd = {key: n for key, n in halves.items() if n % 2}
+    if odd:
+        print("PARITY LAW BROKEN: " + ", ".join(
+            f"blk.{lay} half {half} holds {n} protected experts"
+            for (lay, half), n in sorted(odd.items())), file=sys.stderr)
+        raise SystemExit(2)
 
     print("\n".join(lines))
     print("\n".join(report), file=sys.stderr)
-    print(f"total protected: {total}", file=sys.stderr)
+    print(f"total protected: {total} (target {a.target_count or 'none'}, {bar}, "
+          f"min-route-mult {a.min_route_mult:g})", file=sys.stderr)
 
 
 if __name__ == "__main__":

scripts/download-frank-dragoon-npu.sh

@@ -0,0 +1,117 @@
+#!/usr/bin/env bash
+# download-frank-dragoon-npu.sh — stage the NPU half of frank-dragoon: the
+# vendor-precompiled AIE programs halogen-flash-server runs on the XDNA2 NPU
+# when HALOGEN_NPU_MODELS names them. These are NOT model weights you can
+# quantize yourself: XDNA2 executes only programs compiled by AMD's AIE
+# compiler, so the only source is peonist-ai's per-model NPU repo, and the
+# engine checks every file's size and sha256 against its own catalog at boot
+# (/opt/halogen/npu/models.txt inside the image) and refuses to load a model
+# whose files do not match.
+#
+# The manifest below IS that catalog block (dumped from the pinned 0.16.2
+# image on 2026-10-19), so the files land in the layout the entrypoint
+# expects — <dir>/<model-id>/devices/*, <dir>/<model-id>/<model-id>.hnpw and
+# <dir>/<model-id>/tokenizer/tokenizer.json — and the endpoint can keep
+# /models read-only and open no outbound connection at boot (HALOGEN_DOWNLOAD
+# stays unset; the vendor's own README: with it unset the container makes no
+# outbound connections at all).
+#
+# The fetch law, same as every sibling script: curl -f (an access error must
+# not become a "successful" 153-byte artifact), the exact byte count and the
+# sha256 from the manifest, --verify-only to re-check a staged set.
+#
+# Adding a second NPU model: read its block out of the image's catalog and add
+# a case below —
+#   podman exec frank-dragoon-halogen grep "^file <model-id> " /opt/halogen/npu/models.txt
+#   podman exec frank-dragoon-halogen grep "^model <model-id> " /opt/halogen/npu/models.txt
+# and add the model id to HALOGEN_NPU_MODELS in frank-dragoon.env.
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ENV_FILE="${FRANK_DRAGOON_ENV_FILE:-$SCRIPT_DIR/frank-dragoon.env}"
+# The env file owns the staging path (it must sit inside the payload dir, which
+# is the container's only /models mount); an exported FRANK_DRAGOON_NPU_DIR wins
+# so the bats seam can stage somewhere disposable.
+DEST="${FRANK_DRAGOON_NPU_DIR:-}"
+if [ -z "$DEST" ] && [ -f "$ENV_FILE" ]; then
+    DEST="$(sed -nE 's/^FRANK_DRAGOON_NPU_DIR=(.*)$/\1/p' "$ENV_FILE" | tail -1)"
+fi
+: "${DEST:?FRANK_DRAGOON_NPU_DIR is not set and $ENV_FILE names no FRANK_DRAGOON_NPU_DIR}"
+HF="https://huggingface.co"
+
+MODELS="${HALOGEN_NPU_MODELS:-}"
+if [ -z "$MODELS" ] && [ -f "$ENV_FILE" ]; then
+    MODELS="$(sed -nE 's/^HALOGEN_NPU_MODELS=(.*)$/\1/p' "$ENV_FILE" | tail -1)"
+fi
+
+VERIFY_ONLY=0
+case "${1:-}" in
+    --verify-only) VERIFY_ONLY=1 ;;
+    "") ;;
+    *) echo "usage: ${0##*/} [--verify-only]   (models come from HALOGEN_NPU_MODELS)" >&2; exit 2 ;;
+esac
+[ -n "$MODELS" ] || { echo "no NPU model named — set HALOGEN_NPU_MODELS or run with it in the environment" >&2; exit 1; }
+
+# manifest <model-id> -> repo revision + one "path bytes sha256" per file.
+manifest() {
+    case "$1" in
+      qwen3-embedding-0.6b)
+        NPU_REPO="peonist-ai/halogen-npu-qwen3-embedding-0.6b"
+        NPU_REV="4960fd9d4423dd15373ad21c83db48dbdb3b2798"
+        FILES=(
+        "devices/NOTICE.md 3248 0f267b3d2523ddf14997ee58660a492a9eaf10ccf6b08bf19dfdc85b9a478b91"
+        "devices/consts.hnpb 5086496 ae430e41545a0b1012938cda373b0c450364d3be631111cca3a8c43679f93336"
+        "devices/devices.hnpm 24047 4e9bca9d95d084fb89ce5b99f579a00666c8ca1efae2613c53e3a4878cc9f174"
+        "devices/u0.elf 4931968 b38f165886cb037b7d3951d9cb878473eaba58a432acd45416ff85fd88aa4e46"
+        "devices/u1.elf 5456000 b1811feee851b8af833b37721da92099d89772110815bbbe2c3fa1c276f0ff42"
+        "devices/u2.elf 6505552 406ea9a95b470628a7382e376f4a72cdf4d7aa4c59b4ddf0a4bdd139d63d6ff2"
+        "devices/u3.elf 6817216 bc205d51b523d770151a0c61968f7c70bf624412827580bb6fe0aaf4650dc2ee"
+        "devices/u4.elf 7444032 a5a91338a2603acdcd5c11df532033fda2d3f5479ea44ae87f98fafbdff9a62d"
+        "devices/u5.elf 7432416 6c2bf41835569e0eba25ded7c05c7264ae69c6700bdeb4791057d884f2a4c126"
+        "devices/u6.elf 4941232 919d0038ca088eafddf195f3466ff38db27d3635be1cffa5d4d4b5140902a68e"
+        "devices/u7.elf 5488304 d904cf8afae9428dd167960549e18cce5441745f18c62f8c50975dffc077d3c2"
+        "devices/u8.elf 4941232 db3aef69b17825854ee0dd2df475125a3f5c872f95c686793d6af1ee83596fa7"
+        "devices/u9.elf 5488304 d182727e551084db8fb9600441d8aa373c7f09a3d267ae0a5e921ef92326db1c"
+        "qwen3-embedding-0.6b.hnpw 813032248 b9f9901429df7b46ec17153aa3899f738adbea8e4356080da0c6e6586fb750d1"
+        "tokenizer/tokenizer.json 11423705 def76fb086971c7867b829c23a26261e38d9d74e02139253b38aeb9df8b4b50a"
+        ) ;;
+      *)
+        echo "unknown NPU model '$1' — add its catalog block to manifest() in this script" >&2
+        return 1 ;;
+    esac
+}
+
+for MODEL in ${MODELS//,/ }; do
+    manifest "$MODEL" || exit 1
+    echo "== $MODEL  ($NPU_REPO@$NPU_REV) =="
+    for entry in "${FILES[@]}"; do
+        read -r f want sha <<<"$entry"
+        path="$DEST/$MODEL/$f"
+        mkdir -p "$(dirname "$path")"
+        if [ "$VERIFY_ONLY" -eq 0 ]; then
+            if [ -f "$path" ] && [ "$(stat -c %s "$path")" = "$want" ]; then
+                echo "HAVE  $f ($want bytes) — skipping fetch"
+            else
+                echo "FETCH $f -> $path"
+                # HF answers /resolve/ with a 302 to the Xet CDN and curl
+                # DROPS the Range header across redirects, so resolve the
+                # effective URL first and resume against the CDN (the sibling
+                # 62 GiB fetch hit this on 2026-10-18).
+                url=$(curl -sfIL -o /dev/null -w '%{url_effective}' "$HF/$NPU_REPO/resolve/$NPU_REV/$f") \
+                    || { echo "cannot resolve $NPU_REPO/$f" >&2; exit 1; }
+                curl -fL --retry 5 -C - -o "$path" "$url"
+            fi
+        fi
+        [ -f "$path" ] || { echo "MISSING $path (run without --verify-only)" >&2; exit 1; }
+        if [ -L "$path" ]; then
+            echo "SYMLINK $path — the serve gate refuses symlinks; replace with a real file" >&2
+            exit 1
+        fi
+        got="$(stat -c %s "$path")"
+        [ "$got" = "$want" ] || { echo "SIZE $path: $got != $want" >&2; exit 1; }
+        got="$(sha256sum "$path" | cut -d' ' -f1)"
+        [ "$got" = "$sha" ] || { echo "SHA256 $path: $got != $sha" >&2; exit 1; }
+        echo "OK   $f ($want bytes, sha256)"
+    done
+done
+echo "DOWNLOAD_DONE $DEST ($MODELS)"

scripts/download-frank-zealot-uncensored-lora.sh

@@ -0,0 +1,101 @@
+#!/usr/bin/env bash
+# Fetch the refusal-direction adapter that frank-zealot applies at load:
+# AtomicChat/Ternary-Bonsai-2-9B-Uncensored-LoRA-GGUF — a **3.2 MB rank-1 LoRA**
+# for prism-ml/Ternary-Bonsai-2-9B, not a checkpoint. Public repo: no auth
+# header, and never a token on the command line (a Bearer token is
+# world-readable in /proc/<pid>/cmdline).
+#
+# IT IS AN EDIT INSIDE THE COMPUTE GRAPH, NOT A SECOND MODEL. The card: B = -r
+# (the refusal direction, row 23 of its own probe matrix), A = P^T(s *
+# H(r^T W_fold)) built from the base pack's folded input basis, applied at every
+# transformer layer (`target_layers = all`, `sites = 64`), with the embedding
+# deliberately untouched because an embedding LoRA crashes this fork's graph.
+# `--lora-scaled <file>:<scale>` is the flag pair: scale 1 is the card's
+# "held-out refusals 0 %" point, scale 0 is the plain model again.
+#
+# THE RUNTIME IS A GATE, NOT A PREFERENCE. The card verified the adapter on
+# `prism-b10777-e3de715` — the exact build frank-zealot runs — and says older
+# forks (e.g. `prism-b10709`) refuse these packs with `unsupported
+# prism.hadamard.version: 2`. The fork is already pinned for the payload's
+# custom tensor type 142; this adapter adds a second reason it cannot move.
+#
+# PROVENANCE ASYMMETRY, STATED HONESTLY. The GGUF's own metadata names the pack
+# the direction was fitted against:
+#   prism.abliterate.base_gguf   = Ternary-Bonsai-2-9B-PTQ1_0.gguf
+#   prism.abliterate.base_sha256 = 3561df7ac7d26a71ffa991ac2db740b10841c3a350aa2676ccd3ff5d428b4e8b
+# frank-zealot serves the PQ2_0 + MTP + Q8_0-embedding packing (its sha256 is
+# c79fcdfa…, see download-frank-zealot-bonsai9.sh), which is NOT that file and is
+# not on this host. The adapter still applies — same tensor names, and the
+# metadata is provenance rather than a checksum gate — but its strength was
+# calibrated on a sibling quantization. What proves the effect here is the
+# behaviour of the endpoint (a refusal probe before and after the swap), not the
+# metadata and not the card's table, which was measured on PTQ1_0.
+#
+# Fresh downloads, no resume; -f/--fail-with-body so an HTTP error is not a
+# success, then byte count and sha256 (this repo is NOT LFS — the file is a
+# plain git object, so the sha below is the content hash of the Hub's bytes as
+# fetched, not an LFS oid). Idempotent: a complete file is skipped.
+#
+# Usage:
+#   scripts/download-frank-zealot-uncensored-lora.sh [DEST_DIR] [--verify-only]
+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/Bonsai2-9B-MTP}"
+
+REPO="AtomicChat/Ternary-Bonsai-2-9B-Uncensored-LoRA-GGUF"
+# name | bytes | sha256 of the Hub's bytes
+FILES=(
+  "Ternary-Bonsai-2-9B-Uncensored-LoRA.gguf|3155424|861b9c099fb5cd81438ba85bad30590847c777b1e18112586be7f4f9ae5fb07b"
+)
+
+mkdir -p "$DEST"
+status=0
+for entry in "${FILES[@]}"; do
+  IFS='|' read -r name size sha <<<"$entry"
+  url="https://huggingface.co/${REPO}/resolve/main/${name}"
+  f="$DEST/$name"
+  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        $name"
+    continue
+  fi
+  if (( VERIFY_ONLY )); then
+    echo "MISSING   $name"
+    status=1
+    continue
+  fi
+  echo "FETCHING  $name (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 $name ($(stat -c%s "$f") != $size)"
+    status=1
+    continue
+  fi
+  if ! sha256sum -c --quiet <(printf '%s  %s\n' "$sha" "$f"); then
+    echo "SHA FAIL  $name"
+    status=1
+    continue
+  fi
+  echo "VERIFIED  $name"
+done
+if (( status == 0 )); then
+  echo "DOWNLOAD_DONE $DEST"
+else
+  echo "DOWNLOAD_FAILED $DEST" >&2
+fi
+exit "$status"

scripts/download-qwen38-bf16.sh

@@ -0,0 +1,249 @@
+#!/usr/bin/env bash
+# download-qwen38-bf16.sh — RUNS ON DANKSERVER. Fetch and verify the vendor
+# BF16 checkpoint Qwen/Qwen3.8-Flash-Next: the source the five-bit campaign
+# converts, and the source the KLD reference is recorded from.
+#
+# Why the base and not a finetune: the campaign converts to compare against the
+# publisher's own iq4r container, and that container was built from this
+# checkpoint. Base-in, base-out; anything else confounds the gate. (The
+# predecessor campaign ran ukisai/Swift-1.5-Qwen3.8-Flash-Next-BF16, whose key
+# set is identical to this repo's but whose weights are not — none of its
+# calibration grams, KLD reference or protected list carries over.)
+#
+# Why re-fetch instead of reusing: every BF16 copy of this family was destroyed
+# in the 2026-10-15 storage purge — only the 113.6 GiB served .rad survived.
+# 335.3 GiB of safetensors, 131 shards, ungated (the predecessor campaign
+# verified the key set against this repo, so no gate letter is needed).
+#
+# Verification is four gates deep, because the failure this repo actually lived
+# through is a fetch that reported success: `curl -o FILE URL` exits 0 on an
+# HTTP 401/403 and writes the error body as the artifact — three shards of
+# identical tiny size and a cheerful DONE in 20 seconds for 104 GiB.
+#
+#   1. shard census: the file count must equal the expected shard count, so a
+#      partially fetched fragment tree (the .partNofM trap) cannot pass.
+#   2. per-shard completeness, from the shard's OWN safetensors header: the
+#      header declares where the tensor data ends, so every shard's true size is
+#      known offline. A torn tail is named here, by file, instead of surfacing
+#      as a load error five hours later.
+#   3. index coverage: every shard model.safetensors.index.json references
+#      exists and is named.
+#   4. total bytes against the number the Hub declared, then, unless --no-hub,
+#      every file's sha256 against the Hub's LFS record — including the shards
+#      already on disk, so a previous partial download is never trusted.
+#
+# The token never enters a command line (the 2026-09-16 leak law): it is read
+# into HF_TOKEN in the environment, where a local process listing is the only
+# reader. This repo is ungated, so the fetch simply runs without one when no
+# token file exists. scripts/hfget.sh is curl+jq only — no Python, no venv, no
+# hf_transfer — and it drops the pickle/ONNX weight duplicates by itself.
+#
+# usage: download-qwen38-bf16.sh [--fetch] [--no-hub] [--dir DIR]
+#                                [--shards N] [--bytes B] [--repo ID]
+#   --fetch    download first (resumable: re-run to continue), then verify
+#   --no-hub   skip the Hub-side sha256 sweep; the other gates always run
+# exit: 0 verified, 1 verification failed, 2 environment / usage error
+set -euo pipefail
+
+REPO="${FRANK_QWEN38_HF_REPO:-Qwen/Qwen3.8-Flash-Next}"
+LOCAL_DIR="${FRANK_QWEN38_CKPT:-/home/dank/models/Qwen3.8-Flash-Next}"
+# Hub census of 2026-10-27: 144 files, 131 of them .safetensors, together
+# 360,023,351,514 bytes; the shards alone are 360,000,192,888. This gate counts
+# shards only, so a config file edited on the Hub cannot fail it.
+EXPECTED_SHARDS="${FRANK_QWEN38_SHARDS:-131}"
+EXPECTED_BYTES="${FRANK_QWEN38_BYTES:-360000192888}"
+MIN_FREE_MIB="${FRANK_QWEN38_MIN_FREE_MIB:-350000}"
+
+FETCH=0
+HUB=1
+while [ $# -gt 0 ]; do
+    case "$1" in
+        --fetch) FETCH=1 ;;
+        --no-hub) HUB=0 ;;
+        --dir)    LOCAL_DIR="$2"; shift ;;
+        --shards) EXPECTED_SHARDS="$2"; shift ;;
+        --bytes)  EXPECTED_BYTES="$2"; shift ;;
+        --repo)   REPO="$2"; shift ;;
+        *) echo "usage: ${0##*/} [--fetch] [--no-hub] [--dir DIR] [--shards N] [--bytes B] [--repo ID]" >&2
+           exit 2 ;;
+    esac
+    shift
+done
+
+SELF_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+FAILS=0
+note() { echo "$@"; FAILS=$((FAILS + 1)); }
+
+if [ "$FETCH" = "1" ]; then
+    # Every fetch gate is a hard stop: skipping the download silently and then
+    # verifying a half tree is how a campaign ships a stale payload.
+    HFGET="$SELF_DIR/hfget.sh"
+    if [ ! -f "$HFGET" ]; then
+        echo "REFUSED: the fetch helper is not here: $HFGET" >&2
+        exit 2
+    fi
+    if ! command -v jq >/dev/null 2>&1; then
+        echo "REFUSED: hfget.sh needs jq on PATH" >&2
+        exit 2
+    fi
+    mkdir -p "$LOCAL_DIR"
+    # The campaign's peak-disk law starts at the fetch: the checkpoint and the
+    # reference container built from it are ~335 GiB each, and a tree that does
+    # not fit is discovered hours into a transfer, when it costs the most.
+    free_mib=$(df -m --output=avail "$LOCAL_DIR" | tail -1 | tr -dc '0-9')
+    if [ "${free_mib:-0}" -lt "$MIN_FREE_MIB" ]; then
+        echo "REFUSED: $free_mib MiB free at $LOCAL_DIR; the fetch wants $MIN_FREE_MIB MiB free" >&2
+        echo "         (retire the peak-disk predecessors first — nothing is downloaded, so" >&2
+        echo "         nothing is left half-written)" >&2
+        exit 2
+    fi
+    echo "fetch: $REPO -> $LOCAL_DIR ($free_mib MiB free)"
+    if [ -z "${HF_TOKEN:-}" ]; then
+        CREDSTORE="$HOME/.config/huggingface/credentials/https://huggingface.co"
+        if [ -f "$CREDSTORE" ]; then
+            HF_TOKEN="$(awk '/^ OauthToken: / {print $2; exit}' "$CREDSTORE")"
+        elif [ -f "$HOME/.cache/huggingface/token" ]; then
+            # The legacy single-line token file the hub library writes.
+            HF_TOKEN="$(tr -d '[:space:]' < "$HOME/.cache/huggingface/token")"
+        elif [ -f "$HOME/.hf_token" ]; then
+            HF_TOKEN="$(tr -d '[:space:]' < "$HOME/.hf_token")"
+        fi
+    fi
+    if [ -n "${HF_TOKEN:-}" ]; then
+        export HF_TOKEN
+    fi
+    bash "$HFGET" "$REPO" "$LOCAL_DIR" main
+    unset HF_TOKEN
+fi
+
+if [ ! -d "$LOCAL_DIR" ]; then
+    echo "REFUSED: $LOCAL_DIR does not exist (run with --fetch, or pass --dir)" >&2
+    exit 1
+fi
+INDEX="$LOCAL_DIR/model.safetensors.index.json"
+if [ ! -f "$INDEX" ]; then
+    echo "REFUSED: $INDEX is missing — the checkpoint tree is not addressable without it" >&2
+    exit 1
+fi
+
+echo "== gate 1: shard census ($LOCAL_DIR)"
+SHARDS=$(find "$LOCAL_DIR" -maxdepth 1 -type f -name '*.safetensors' | wc -l)
+if [ "$SHARDS" != "$EXPECTED_SHARDS" ]; then
+    note "FAIL SHARD_COUNT: $SHARDS safetensors files on disk, expected $EXPECTED_SHARDS"
+else
+    echo "  ok: $SHARDS shards"
+fi
+
+echo "== gate 2: every shard is whole, judged by its own header"
+# A safetensors file is [u64 header length][JSON header][tensor data]. The JSON
+# declares where the data ends, so the file's true size is computable offline:
+# 8 + header + the largest end offset. Truncation and error bodies both fall
+# here, and each is reported with the file that caused it.
+while IFS= read -r f; do
+    state=$(python3 - "$f" <<'PY'
+import json, os, struct, sys
+path = sys.argv[1]
+size = os.path.getsize(path)
+try:
+    with open(path, "rb") as fh:
+        (hlen,) = struct.unpack("<Q", fh.read(8))
+        if hlen == 0 or hlen > size:
+            print("NOT_SAFETENSORS")
+            raise SystemExit
+        header = json.loads(fh.read(hlen))
+except Exception:
+    print("NOT_SAFETENSORS")
+    raise SystemExit
+if not header:
+    print("NOT_SAFETENSORS")
+    raise SystemExit
+end = max((v["data_offsets"][1] for v in header.values()
+           if isinstance(v, dict) and "data_offsets" in v), default=0)
+want = 8 + hlen + end
+print("OK" if want == size else f"TRUNCATED want={want} have={size}")
+PY
+)
+    case "$state" in
+        OK) ;;
+        NOT_SAFETENSORS*) note "FAIL NOT_SAFETENSORS: $(basename "$f") is not a safetensors file (an error body written as an artifact?)" ;;
+        TRUNCATED*) note "FAIL TRUNCATED: $(basename "$f") $state" ;;
+    esac
+done < <(find "$LOCAL_DIR" -maxdepth 1 -type f -name '*.safetensors' | sort)
+if [ "$FAILS" -eq 0 ]; then
+    echo "  ok: every shard's data extent matches its size on disk"
+fi
+
+echo "== gate 3: the index's shards are all present"
+INDEX_SHARDS=$(python3 - "$INDEX" <<'PY'
+import json, sys
+map_ = json.load(open(sys.argv[1]))["weight_map"]
+print("\n".join(sorted(set(map_.values()))))
+PY
+)
+while IFS= read -r name; do
+    [ -n "$name" ] || continue
+    if [ ! -f "$LOCAL_DIR/$name" ]; then
+        note "FAIL MISSING: $name is named by the index and is not on disk"
+    fi
+done <<< "$INDEX_SHARDS"
+if [ "$FAILS" -eq 0 ]; then
+    echo "  ok: $(printf '%s\n' "$INDEX_SHARDS" | grep -c .) referenced shards on disk"
+fi
+
+echo "== gate 4: total bytes vs the Hub's declaration"
+TOTAL=$(find "$LOCAL_DIR" -maxdepth 1 -type f -name '*.safetensors' -printf '%s\n' | awk '{s+=$1} END{print s+0}')
+if [ "$TOTAL" != "$EXPECTED_BYTES" ]; then
+    note "FAIL TOTAL_BYTES: shards total $TOTAL bytes, expected $EXPECTED_BYTES"
+else
+    echo "  ok: $TOTAL bytes"
+fi
+
+if [ "$HUB" = "1" ]; then
+    echo "== gate 5: every file's sha256 vs the Hub's LFS record"
+    # size = file size; lfs.sha256 = sha256 of the file itself (LFS or not).
+    TMPD="$(mktemp -d)"
+    trap 'rm -rf "$TMPD"' EXIT
+    MANIFEST="$TMPD/tree.json"
+    PLAN="$TMPD/plan"
+    curl -sf "https://huggingface.co/api/models/$REPO/tree/main?recursive=true&expand=true" \
+        -o "$MANIFEST" || { echo "FAIL: the Hub API call failed — refusing to report success" >&2; exit 1; }
+    python3 - "$MANIFEST" > "$PLAN" <<'PY'
+import json, sys
+for e in json.load(open(sys.argv[1])):
+    if e.get("type") != "file":
+        continue
+    sha = (e.get("lfs") or {}).get("sha256") or e.get("sha") or ""
+    if sha:
+        print(e["path"], e["size"], sha)
+PY
+    BAD=0
+    while read -r rel size sha; do
+        [ -n "${rel:-}" ] || continue
+        if [ ! -f "$LOCAL_DIR/$rel" ]; then
+            note "FAIL MISSING: $rel is on the Hub and not on disk"
+            continue
+        fi
+        have=$(stat -c %s "$LOCAL_DIR/$rel")
+        if [ "$have" != "$size" ]; then
+            note "FAIL SIZE: $rel is $have bytes, Hub says $size"
+            continue
+        fi
+        got=$(sha256sum "$LOCAL_DIR/$rel" | awk '{print $1}')
+        if [ "$got" != "$sha" ]; then
+            note "FAIL SHA256: $rel got $got want $sha"
+            BAD=$((BAD + 1))
+        fi
+    done < "$PLAN"
+    if [ "$BAD" -eq 0 ] && [ "$FAILS" -eq 0 ]; then
+        echo "  ok: sha256 matches for every file"
+    fi
+    rm -rf "$TMPD"
+    trap - EXIT
+fi
+
+if [ "$FAILS" -gt 0 ]; then
+    echo "VERIFY_FAILED: $FAILS problem(s) in $LOCAL_DIR" >&2
+    exit 1
+fi
+echo "VERIFY_OK: $SHARDS shards, $TOTAL bytes of safetensors in $LOCAL_DIR"
+echo "NEXT: build the BF16 reference container with scripts/build-qwen38-bf16-rad.sh"

scripts/frank-archon.env

@@ -46,31 +46,42 @@ FRANK_ARCHON_TP=2
 # stays EXACT for single-sequence decode and any step of <= 25 rows — see
 # MAX_SEQS x (1 + SPEC_TOKENS) below.
 FRANK_ARCHON_TP_WIRE=wht6
-# Decode slots. A slot costs KV, never decode; the pool is sized to this
-# contract and nothing more. At 1.8.1 the budget resolver caps the cache at
-# 556,348 fp8 tokens — 2.8 sessions at 200,000 — so a THIRD full-height
-# conversation answers 400 while /health and every shorter chat work fine
-# (3 x 50k streams run at 77.6 t/s aggregate). Frank's trade: declare the two
-# slots the engine can hold and let the freed ~1.1 GiB go to the expert plane,
-# instead of advertising a third slot that only exists at shorter prompts.
-FRANK_ARCHON_MAX_SEQS=2
+# Decode slots. A slot costs KV and pinned RAM, never decode: the cache target is
+# exactly MAX_SEQS x MAX_MODEL_LEN and the checkpoint store asks (1 + what the
+# retention policy keeps) per slot. Ordered 2026-10-20: FOUR slots over a pool of at
+# least 700,000 fp8 tokens, rounding UP if the resolver cannot land it exactly. The
+# target is therefore 4 x 200,000 = 800,000 tokens and HOST_POOL_MIB decides whether
+# the cache gets it (expert_vram_floor, core/place/planner.cpp:100-104: the card must
+# keep expert-plane-minus-host-room). The 2-slot shape was the answer to a
+# 365,204-token pool that backed 1.8 full-height sessions; at this pool the third and
+# fourth conversations are backed by the cache instead of over-committing it.
+FRANK_ARCHON_MAX_SEQS=4
 # Served window. The engine treats `kv group tokens >= max-model-len` as a HARD
 # limit, and models.yml contextWindow MUST quote this number (over-length is a
 # refusal, not a truncation). The pool is sized for seqs x maxlen, not one
 # sequence.
 FRANK_ARCHON_MAX_MODEL_LEN=200000
 FRANK_ARCHON_PLACEMENT=expert_tiered
-# Pinned host pool for expert rows that do not fit VRAM. Under the budget
-# resolver this is ALSO the lever that decides which experts stay on the card:
-# the card's leftover goes to the expert plane first and the KV cache takes the
-# rest, so growing the pool moves experts off the card and shrinking it spills
-# them onto VRAM the cache wanted. Under-sizing it is a boot failure (36,864
-# refused a boot). The ledger's coverage line is the referee, not this file.
-# Measured, not guessed: 45,568 (PR #30) moved host_pool to 45.09 GiB and left
-# vram_kv byte-identical at 4.20 GiB / 556,348 tokens on both ranks — extra
-# host RAM above what the expert plane's footprint needs buys no cache. Back at
-# 44,928, the size that boots clean.
-FRANK_ARCHON_HOST_POOL_MIB=44928
+# Pinned host pool for expert rows that do not fit VRAM, PINNED ONCE PER RANK: the
+# host must pin tp x this number, and the refusal that names it is
+# core/engine_bringup.cpp:250-265. Under the budget resolver this is ALSO the KV
+# lever -- the card keeps expert-plane-minus-this-room, so every MiB added moves one
+# MiB of experts off the card and into the cache. Derived from the boot ledger (a
+# 23.73 GiB floor at 44,928 room puts plane + 2 units at 67.60 GiB a rank), 49,152
+# drops the floor to 19.6 GiB and leaves the cache ~6.9 GiB, which is enough to back
+# the whole 4 x 200,000 target; the leftover returns to the experts. Cost is paid
+# twice over: pinned RAM (tp x 48 GiB, against the TTM target below) and expert
+# residency -- ~3.2 GiB a card of experts now lives in host RAM and is read over the
+# x8 link when the router picks it. The ledger's coverage line is the referee, not
+# this file: if vram_kv comes back under 700,000 tokens, raise this 1024 and redeploy.
+# 2026-10-29 A/B, measured on both payloads and folded back the same day: at 66,560 the
+# endpoint printed the identical `elastic 26.73 GiB / experts 20.72 / kv cache 5.64 /
+# vram_weights 24.30` it had printed at 49,152, opening the bigger pool with `0 B used`;
+# the campaign rig (bf16, same step) moved `vram_kv 269.99 -> 271.25 MiB`, a rounding
+# step — its window is fixed by its own n-gram table (95.37 GiB) and expert plane, not
+# by this pool, so the refused calibration documents were fixed by cutting them to the
+# window (scripts/rechunk-kld-corpus.py), not by widening the pool.
+FRANK_ARCHON_HOST_POOL_MIB=49152
 # VRAM left unclaimed per card (publisher default 96 MiB); the engine's settle
 # floor is built from it.
 FRANK_ARCHON_GPU_HEADROOM_MIB=96
@@ -93,16 +104,29 @@ FRANK_ARCHON_SPEC_TOKENS=2
 FRANK_ARCHON_MAX_BATCHED_TOKENS=2048
 # Step sharing. A prefill chunk that shares a step with decoding sequences holds
 # the device for the chunk's whole time, and every decode row in that step waits
-# that long for its next token (the census: [[LLM Performance Diagnosis]] §9).
-# `auto` leaves each decode row behind the chunk a row plus its draft window and
-# keeps a share for whatever is waiting to be admitted; a number pins the chunk's
-# cap; `off` is the pre-1.4 behaviour this endpoint ran for two eras, where the
-# chunk took the step and admission never ran. Interleave inserts N decode-only
-# steps after a chunk step taken beside decoders: it protects their cadence and
-# holds a waiting request out of those steps, so it stays 0 until the post-migration
-# decode-vs-prefill buckets say it is wanted.
+# that long for its next token: measured at this shape, decode-only steps 15.5 ms
+# against chunk steps 166 ms, which is the harness's ~146 t/s falling to ~11 t/s
+# while another session prefills (law and census: [[frank-archon]]).
+# `auto` is a PREFILL-SPEED dial, not a decoder dial: it reserves one row plus the
+# draft window per decoding sequence (3 tokens) and an eighth of the budget per
+# waiting request or waiting prefill, and the source states it will not halve for
+# decode rows alone. Live proof: prefill_chunks_capped 5,018 across 62,386 chunk
+# steps. A number is the only value that applies whenever the chunk shares a step,
+# and it must not go under the prefill stager's smallest pass -- 1025 rows here,
+# named on the boot line "prefill staging: ... a step of more than 1024 tokens" --
+# because below it every routed layer reads its pooled experts synchronously, so
+# 512 is a trap and the vendor measures the whole job slower there. Interleave
+# inserts N decode-only steps after a chunk step taken beside decoders: it protects
+# their cadence and holds a waiting request out of those steps. That is the decoder
+# dial. ARMED at 1 on 2026-10-20: at N=1 a stream takes its token from the chunk step
+# AND one from the held step, ~2 tokens per 182 ms instead of one per 166 ms; the
+# price falls on the prefilling prompt (its chunks lose every held step) and on any
+# request still waiting to enter. `--prefill-span` re-funds a prefill only when it is
+# ALONE, so it cannot buy this back while decoders run. Meter:
+# radiance:engine_steps_held_total must leave zero, and the §9 buckets must move
+# before N rises.
 FRANK_ARCHON_BUSY_PREFILL_CHUNK=auto
-FRANK_ARCHON_PREFILL_INTERLEAVE=0
+FRANK_ARCHON_PREFILL_INTERLEAVE=1
 # Prefix cache: pinned host memory only. The disk tier was removed outright
 # (--prefix-cache-dir and --prefix-cache-disk-mib are refusals), so what used to
 # be restored from NVMe is now re-prefilled. The tier is sized in ENTRIES and one
@@ -118,9 +142,11 @@ FRANK_ARCHON_NGRAM_PLACEMENT=ram
 # RESETS pages_limit to half of RAM on every boot; below the plan the load dies
 # mid-pin with an anonymous allocator error. ttm-preflight.sh raises the knob
 # itself before refusing by name, so recovery is a boot, not a visit.
-# Floor = 2 x HOST_POOL + 48,824 (static weights + arena) + PREFIX_CACHE + MNBT
-# per the bats ledger test; at the 44,928 pool that computes to 148,920 MiB.
-FRANK_ARCHON_TTM_MIN_MIB=150000
+# Floor = 2 x HOST_POOL + 48,824 (static weights + arena) + PREFIX_CACHE + MNBT + the
+# auto checkpoint store (MAX_SEQS x 10 slots of 111.98 MiB), per the bats ledger test;
+# at the 49,152 pool with 4 slots that computes to 161,848 MiB (196,664 at the
+# 66,560 pool the 2026-10-29 A/B rejected).
+FRANK_ARCHON_TTM_MIN_MIB=162000
 FRANK_ARCHON_TTM_TARGET_MIB=204800
 # Escape hatch for experiments. Unset -> no extra argv; the serve script expands
 # this unquoted on purpose, so keep multi-flag values as one string.

scripts/frank-dragoon.env

@@ -49,14 +49,21 @@ FRANK_DRAGOON_TOKENIZER_FILES="tokenizer.json chat_template.jinja tokenizer_conf
 # stays at the image default, which is what was qualified) ------------------
 # Served id. OpenWebUI api_configs model_ids for the :7770 backend MUST name it.
 HALOGEN_MODEL_ID=frank-dragoon
-# PER-REQUEST ceiling: a longer prompt is a 400 naming the limit, never a
-# truncation. The harness window must sit ~45k UNDER this (the 400-zone law on
-# the page) — a window equal to the ceiling makes every long request a 400.
-HALOGEN_CTX=200704
-# ONE pool behind both slots, sized so BOTH can carry a maximum-length request
-# at once. Pool positions buy concurrency; the per-request window never moves
-# with them. Legal band: ctx <= pool <= slots * ctx (the seam enforces it), and
-# RAM the pool takes is RAM the n-gram table's page cache loses.
+# PER-REQUEST ceiling, set to the checkpoint's NATIVE window (262,144 — a
+# longer prompt is a 400 naming the limit, never a truncation; stretching
+# past native would need HALOGEN_ROPE_YARN and is not on plan). The harness
+# `contextWindow` must sit ~45k under THIS number (the 400-zone law on the
+# page): with the window at 200,000 the gap is 62,144, which absorbs the
+# chars/4 under-count. A window at or near the ceiling makes every long
+# request a guaranteed 400.
+HALOGEN_CTX=262144
+# ONE pool behind both slots. The harness window is 200,000, so 401,408
+# still carries TWO maximum harness-length conversations at once
+# (2 x 200,000 + one 45,056 budget <= pool + cap headroom); two literal
+# ceiling-length requests would queue instead — buying those means raising
+# the pool, and RAM the pool takes is RAM the n-gram table's page cache
+# loses. Pool positions buy concurrency; the per-request window never moves
+# with them. Legal band: ctx <= pool <= slots * ctx (the seam enforces it).
 HALOGEN_KV_POOL_POSITIONS=401408
 # Two concurrent conversations: the MTP drafter is not slot-locked on this
 # engine, so the second slot is capacity, not a speculation tax.
@@ -80,3 +87,51 @@ HALOGEN_TOP_K=20
 # Weights stay pinned: the engine pins by default and only the retired w4b build
 # honored HALOGEN_FLASH_PIN_TRUNK=0, which this payload rejects.
 HALOGEN_WEIGHTS_LOCK=1
+
+# --- NPU lane (XDNA2) -------------------------------------------------------
+# HALOGEN_NPU_MODELS is the whole switch: EMPTY or unset = the endpoint exactly
+# as it ran before this lane existed (no accel device, no XRT mount, no
+# fabric-clock dependency, no /v1/embeddings). Rolling the lane back is blanking
+# this one line and re-deploying — nothing else moves.
+# Names are the vendor catalog's folder names (`/opt/halogen/npu/models.txt`
+# inside the image) and the engine reads a model ONLY at /models/npu/<name>/ —
+# HALOGEN_NPU_DIR is gone from the image and setting it is a boot refusal.
+# The engine cannot fetch anything here: /models is read-only and
+# HALOGEN_DOWNLOAD stays unset so the container opens no outbound connection at
+# boot, so scripts/download-frank-dragoon-npu.sh must stage the files first
+# (the serve gate and the deployer both refuse by name when a named model is
+# missing). FRANK_DRAGOON_NPU_DIR therefore lives INSIDE the payload dir: the
+# payload mount is the container's only handle on /models, and runc cannot
+# mkdir a nested /models/npu mountpoint through a read-only bind — the lane's
+# first boot died on precisely that (2026-10-19). Swap the payload dir and this
+# path moves with it.
+# Cost: ~1.5 GiB extra pinned host RAM per named model, and a hard dependency on
+# the host holding the GPU fabric clock — on Strix Halo the iGPU and the NPU
+# together hang the machine (and corrupt NPU results) while FCLK changes speed,
+# so halogen refuses to start with this variable set unless the clock is held
+# (dankclaw/host/halogen-fabric-clock; the deployer installs and gates it).
+HALOGEN_NPU_MODELS=qwen3-embedding-0.6b
+FRANK_DRAGOON_NPU_DIR=/home/dank/models/halogen-v2-abliterated/npu
+# Node paths and the XRT directory are variables so the bats seam can drive
+# these gates on a box with no NPU. Ubuntu's distro XRT (libxrt2 + libxrt-npu2)
+# is mounted FILE BY FILE and THREE TIMES EACH — where the image looks for XRT
+# (/opt/xilinx/xrt/lib), at its own path (those libraries find each other at
+# their install path), and at /opt/xilinx/lib/<multiarch>/ (the NPU child
+# searches that third prefix; without it the lane dies naming it and the
+# supervisor takes the container down — 2026-10-21 boot loop). The basename of
+# this directory IS the multiarch name. The vendor forbids mounting an
+# /opt/xilinx/xrt of symlinks into the system dir, which dangle in the container.
+FRANK_DRAGOON_DEV_ACCEL=/dev/accel/accel0
+FRANK_DRAGOON_XRT_DIR=/usr/lib/x86_64-linux-gnu
+# sysfs root the fabric-clock preflight reads (same knob the vendor's
+# halogen-fabric-clock status reads; the seam points it at a fixture).
+FRANK_DRAGOON_SYSFS=/sys
+# Container network. Empty = podman's rootless default (`pasta`): a private
+# netns that nothing else can join — podman refuses a second network while the
+# primary is pasta, the published port is refused from dankclaw_default
+# containers, and host.containers.internal resolves link-local, which
+# open-notebook's URL guard refuses to store. Named = the app bridge, so
+# open-notebook can dial http://frank-dragoon-halogen:8731 for the NPU
+# endpoints. The engine's unauthenticated 8730 stays private either way (it
+# binds the container's own loopback); only the API port becomes name-resolvable.
+FRANK_DRAGOON_NETWORK=dankclaw_default

scripts/frank-dragoon.service

@@ -1,5 +1,5 @@
 [Unit]
-Description=halogen-flash-server container (Quat3rnion NATIVE v2 abliterated Qwen3.8-Flash-Next, MTP spec decode, 2 slots over ONE 401408-position pool at ctx 200704, vision ON), root systemd unit (dankclaw, frank-dragoon, Strix Halo iGPU)
+Description=halogen-flash-server container (Quat3rnion NATIVE v2 abliterated Qwen3.8-Flash-Next, MTP spec decode, 2 slots over ONE 401408-position pool at ctx 262144, vision ON), root systemd unit (dankclaw, frank-dragoon, Strix Halo iGPU)
 After=network-online.target
 Wants=network-online.target
 

scripts/frank-tts-engine.env

@@ -27,6 +27,16 @@
 # below stop describing the process you are running. Nothing in this fleet
 # pins this container; that is a decision, not an oversight.
 #
+# THE DEVICE LAW (since the 2026-10-19 Vulkan cutover). Synthesis computes on
+# the gfx1151 iGPU — the SAME card frank-dragoon serves. It is a shared device,
+# never a dedicated one, so two numbers matter and neither is what `rocm-smi`
+# prints first: the memory the container may use is the RADV heap inside the
+# GTT-backed aperture (the ~2 GiB DRM carve-out is not the working set), and the
+# timing that matters is dragoon's, measured WITH a synthesis in flight. The
+# rollback is one line: set QWENTTS_DEVICE empty, and the entrypoint passes no
+# --device at all — the pre-iGPU CPU shape, no rebuild, no restart of anything
+# else on the box.
+#
 # THE REGISTRY LAW (why the unit has an ExecStartPost at all). Registrations live
 # in memory only, so a restart loses them, and re-registration alone does NOT warm
 # a voice — the warm pass has to synthesize something. Without it the façade
@@ -103,6 +113,17 @@ QWENTTS_LANG=auto
 # round-trip outside it) is what absorbs the queue.
 QWENTTS_MAX_BATCH=1
 
+# The compute device, by ggml device NAME. `Vulkan0` is the gfx1151 iGPU: the
+# image carries the Mesa (RADV) ICD and no NVIDIA ICD, so this container's
+# Vulkan enumeration has exactly one entry and it is the iGPU. The unit hands
+# the container /dev/dri and keeps the render group; on this hybrid host the
+# iGPU's render node is renderD129 and renderD128 is the NVIDIA card, which is
+# why the unit passes the directory and lets the driver resolve the node.
+#
+# ROLLBACK: an empty value means no --device flag at all — the CPU shape this
+# endpoint shipped with until 2026-10-19. One line, no rebuild.
+QWENTTS_DEVICE=Vulkan0
+
 # --- 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

scripts/frank-tts.env

@@ -7,7 +7,7 @@
 # whichever TTS engine wins the engine decision (dankclaw/voiceservice/app.py
 # is a single stdlib-only file in a locally built image). Consumers — omp's
 # TTS device, OpenWebUI, open-notebook — address a VOICE BY NAME
-# (voice=narrator1, or the harness' voice_id=narrator1) and never see a path:
+# (voice=wilwheaton, or the harness' voice_id=wilwheaton) and never see a path:
 # a name is real exactly when /voices/<name>/reference.wav exists, and
 # anything else is a 400 that lists the names that are.
 #
@@ -65,7 +65,7 @@ TTS_UPSTREAM_MODEL=voxcpm2
 # name still 400s with the list that exists — this covers the absent case only —
 # and the journal marks such a line `(default)` so an unrequested voice never
 # reads as a requested one. Any pack directory in /home/dank/voices is legal.
-DEFAULT_VOICE=narrator1
+DEFAULT_VOICE=wilwheaton
 
 # CLI-backend knobs, inert while TTS_BACKEND=omni-http. Empty means "not
 # configured": the endpoint answers a 500 that says so instead of running

scripts/frank-zealot.env

@@ -1,5 +1,6 @@
 # frank-zealot — llama.cpp (PrismML fork build 10777, CUDA) on the RTX 3090,
-# :7771. Payload: Ternary-Bonsai-2-9B PQ2_0 with the MTP head in the file.
+# :7771. Payload: Ternary-Bonsai-2-9B PQ2_0 with the MTP head in the file, plus
+# the refusal-direction adapter applied at load.
 #
 # ONE OWNER: shape, payload identity, eras, laws and every measured number
 # live in serverAppConfigs-docs/LLM/frank-zealot.md. This file carries the
@@ -13,6 +14,17 @@ MODEL_FILE=/home/dank/models/Bonsai2-9B-MTP/Ternary-Bonsai-2-9B-PQ2_0-MTP-Q8_0.g
 # Q8_0 IS MANDATORY: the publisher states the BF16 tower can crash llama-server
 # under concurrent image requests, which is exactly --parallel 3.
 MMPROJ_FILE=/home/dank/models/Bonsai2-9B-MTP/Ternary-Bonsai-2-9B-mmproj-Q8_0.gguf
+# Refusal-direction adapter (a rank-1 LoRA, 3.2 MB) applied at load; it edits
+# the compute graph, it is not a second model. Scale 1 is the card's "held-out
+# refusals 0 %" point. LORA_FILE="" is the documented opt-out — the plain pack
+# again, no rebuild — and LORA_SCALE=0 is the same result through the flag.
+# PROVENANCE ASYMMETRY: the adapter's own prism.abliterate.base_gguf names
+# Ternary-Bonsai-2-9B-PTQ1_0.gguf as the pack its direction was fitted against,
+# which is NOT this packing and is not on this host. The tensor names match, so
+# it applies; the strength was calibrated on a sibling quantization, so the
+# effect is proven by the endpoint's behaviour, never by the metadata.
+LORA_FILE=/home/dank/models/Bonsai2-9B-MTP/Ternary-Bonsai-2-9B-Uncensored-LoRA.gguf
+LORA_SCALE=1
 # Served id — the harness/family name, not a fact about the payload.
 # Id-keyed consumers: OpenWebUI (model row, access_grant, api_configs), models.yml.
 ALIAS=frank-zealot

scripts/frank-zealot.service

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

scripts/gpu-exporter.py

@@ -0,0 +1,212 @@
+#!/usr/bin/env python3
+"""gpu-exporter: unified per-GPU metrics for a mixed AMD/NVIDIA host.
+
+Emits the `gpu_*` Prometheus families the host-system dashboard graphs:
+
+    gpu_utilization_percent  gpu_memory_used_bytes  gpu_memory_total_bytes
+    gpu_temperature_celsius  gpu_power_watts
+
+each labelled {gpu, vendor, model}. The scrape job adds `host`.
+
+Two sources, both host-native — no container, no GPU passthrough:
+
+  * AMD (R9700s, the 8060S iGPU, the Raphael display GPU): the amdgpu sysfs tree.
+    Utilization comes ONLY from gpu_busy_percent — amd-smi reports gfx_busy_inst
+    as N/A on gfx1201 (verified 2026-10-20). VRAM is already bytes, temperature
+    is milli-degrees, power is micro-watts. Crucially power1_average is EMPTY on
+    the R9700s, so those cards legitimately have no gpu_power_watts line; a
+    missing file becomes an ABSENT metric, never a fabricated 0 that a dashboard
+    would plot as a real reading.
+
+  * NVIDIA (the RTX 3090 on Dankclaw): one `nvidia-smi --query-gpu` CSV. On
+    Dankserver there is an nvidia-smi binary but no NVIDIA GPU, so the command
+    fails; that is tolerated and simply yields no NVIDIA series.
+
+Default mode prints one scrape to stdout and exits (the test harness, and any
+`service ... --oneshot` one-off). `--serve` binds the HTTP endpoint for
+Prometheus; it binds EXPLICITLY (loopback + the host LAN address), never a
+wildcard, matching node-exporter's posture on these boxes.
+"""
+import argparse
+import glob
+import os
+import subprocess
+import sys
+import threading
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+
+FAMILIES = [
+    ("gpu_utilization_percent", "gauge", "GPU busy time as a percentage of wall time."),
+    ("gpu_memory_used_bytes", "gauge", "Device memory in use, in bytes."),
+    ("gpu_memory_total_bytes", "gauge", "Device memory capacity, in bytes."),
+    ("gpu_temperature_celsius", "gauge", "Package temperature in degrees Celsius."),
+    ("gpu_power_watts", "gauge", "Board power draw in watts."),
+]
+
+DEFAULT_NVIDIA_CMD = (
+    "nvidia-smi --query-gpu=index,name,utilization.gpu,memory.used,"
+    "memory.total,temperature.gpu,power.draw --format=csv,noheader,nounits"
+)
+
+
+def _read(path):
+    try:
+        with open(path) as fh:
+            return fh.read().strip()
+    except OSError:
+        return ""
+
+
+def _pci_slot(device_dir):
+    uevent = _read(os.path.join(device_dir, "uevent"))
+    for line in uevent.splitlines():
+        if line.startswith("PCI_SLOT_NAME="):
+            return line.split("=", 1)[1]
+    return ""
+
+
+def _pci_id(device_dir):
+    uevent = _read(os.path.join(device_dir, "uevent"))
+    for line in uevent.splitlines():
+        if line.startswith("PCI_ID="):
+            return "amd:" + line.split("=", 1)[1].lower()
+    return "amd"
+
+
+def collect_amd(sys_dir):
+    for card in sorted(glob.glob(os.path.join(sys_dir, "card[0-9]*"))):
+        device = os.path.join(card, "device")
+        busy = _read(os.path.join(device, "gpu_busy_percent"))
+        if busy == "":
+            continue  # not an amdgpu compute node (e.g. a render node w/o metrics)
+        labels = {"gpu": _pci_slot(device) or os.path.basename(card),
+                  "vendor": "amd", "model": _pci_id(device)}
+        yield "gpu_utilization_percent", labels, busy
+        for name, leaf in (("gpu_memory_used_bytes", "mem_info_vram_used"),
+                           ("gpu_memory_total_bytes", "mem_info_vram_total")):
+            v = _read(os.path.join(device, leaf))
+            if v != "":
+                yield name, labels, v
+        temp = ""
+        for hwmon in sorted(glob.glob(os.path.join(device, "hwmon", "hwmon*", "temp1_input"))):
+            temp = _read(hwmon)
+            if temp != "":
+                break
+        if temp != "":
+            yield "gpu_temperature_celsius", labels, str(int(temp) / 1000.0)
+        power = _read(os.path.join(device, "power1_average"))
+        if power != "":  # empty on the R9700s -> metric absent, not zero
+            yield "gpu_power_watts", labels, str(int(power) / 1e6)
+
+
+def collect_nvidia(cmd):
+    if not cmd:
+        return
+    try:
+        out = subprocess.run(cmd, shell=True, capture_output=True, text=True,
+                             timeout=10, check=True).stdout
+    except (subprocess.SubprocessError, OSError):
+        return  # no NVIDIA GPU / no driver: tolerate, emit nothing
+    for line in out.splitlines():
+        parts = [p.strip() for p in line.split(",")]
+        if len(parts) < 7:
+            continue
+        idx, name, util, mused, mtotal, temp, power = parts[:7]
+        labels = {"gpu": idx, "vendor": "nvidia", "model": name}
+        yield "gpu_utilization_percent", labels, util
+        yield "gpu_memory_used_bytes", labels, str(int(float(mused)) * 1048576)
+        yield "gpu_memory_total_bytes", labels, str(int(float(mtotal)) * 1048576)
+        if temp not in ("", "[N/A]"):
+            yield "gpu_temperature_celsius", labels, temp
+        if power not in ("", "[N/A]"):
+            yield "gpu_power_watts", labels, power
+
+
+def collect(sys_dir, nvidia_cmd):
+    samples = {}
+    for source in (collect_amd(sys_dir), collect_nvidia(nvidia_cmd)):
+        for name, labels, value in source:
+            try:
+                value = str(float(value))  # normalise; drop trailing junk
+            except ValueError:
+                continue
+            samples.setdefault(name, []).append((labels, value))
+    return samples
+
+
+def _fmt(value):
+    f = float(value)
+    if f == int(f) and abs(f) < 1e15:
+        return str(int(f))
+    return repr(f)
+
+
+def render(samples):
+    out = []
+    for name, kind, help_text in FAMILIES:
+        out.append("# HELP %s %s" % (name, help_text))
+        out.append("# TYPE %s %s" % (name, kind))
+        for labels, value in sorted(samples.get(name, []), key=lambda x: sorted(x[0].items())):
+            lset = ",".join('%s="%s"' % (k, v) for k, v in sorted(labels.items()))
+            out.append("%s{%s} %s" % (name, lset, _fmt(value)))
+    return "\n".join(out) + "\n"
+
+
+class Handler(BaseHTTPRequestHandler):
+    sys_dir = "/sys/class/drm"
+    nvidia_cmd = DEFAULT_NVIDIA_CMD
+
+    def do_GET(self):  # noqa: N802 (http.server API)
+        if self.path.split("?")[0] not in ("/metrics", "/"):
+            self.send_error(404)
+            return
+        body = render(collect(self.sys_dir, self.nvidia_cmd)).encode()
+        self.send_response(200)
+        self.send_header("Content-Type", "text/plain; version=0.0.4")
+        self.send_header("Content-Length", str(len(body)))
+        self.end_headers()
+        self.wfile.write(body)
+
+    def log_message(self, *args):
+        pass
+
+
+def main(argv):
+    ap = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    ap.add_argument("--amdgpu-sysfs", default="/sys/class/drm")
+    ap.add_argument("--nvidia-cmd", default=DEFAULT_NVIDIA_CMD)
+    ap.add_argument("--serve", action="store_true", help="serve /metrics instead of one-shot")
+    ap.add_argument("--port", type=int, default=9401)
+    ap.add_argument("--bind", action="append", default=None,
+                    help="explicit bind address (repeatable); env GPU_EXPORTER_BINDS "
+                         "comma-list if unset. NEVER a wildcard.")
+    args = ap.parse_args(argv)
+
+    if not args.serve:
+        sys.stdout.write(render(collect(args.amdgpu_sysfs, args.nvidia_cmd)))
+        return 0
+
+    binds = args.bind
+    if not binds:
+        env = os.environ.get("GPU_EXPORTER_BINDS", "")
+        binds = [b.strip() for b in env.split(",") if b.strip()] or ["127.0.0.1"]
+    Handler.sys_dir = args.amdgpu_sysfs
+    Handler.nvidia_cmd = args.nvidia_cmd
+    servers = []
+    for b in binds:
+        if b in ("0.0.0.0", "::", "*"):
+            sys.stderr.write("refusing wildcard bind %s\n" % b)
+            return 2
+        servers.append(ThreadingHTTPServer((b, args.port), Handler))
+    sys.stderr.write("gpu-exporter serving :%d on %s\n" % (args.port, ",".join(binds)))
+    # EVERY socket must be served: a listen()ed-but-never-accept()ed bind looks
+    # healthy in `ss` yet times out every scrape once its SYN backlog fills —
+    # and the loopback deploy gate cannot see it. One thread per extra bind.
+    for s in servers[1:]:
+        threading.Thread(target=s.serve_forever, daemon=True).start()
+    servers[0].serve_forever()
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))

scripts/gpu-exporter.service

@@ -0,0 +1,35 @@
+# Systemd USER unit: gpu-exporter (both Dankclaw and Dankserver).
+#
+# Install path: ~/.config/systemd/user/gpu-exporter.service
+# Installed and enabled by deploy_gpu_exporter in scripts/deploy-remote.sh.
+#
+# Per-GPU metrics (utilization / VRAM / temperature / power) for the mixed
+# AMD + NVIDIA fleet, scraped by Prometheus. Like signal-relay it is a plain
+# user unit, not a quadlet: it runs python3 straight from the checkout (a pull
+# updates it with no copy step), a hand-written user unit can be enabled where
+# the podman v1 generator's units cannot, and with Linger=yes for dank it starts
+# at boot. It reads the host's own cgroup/drm sysfs and shells to nvidia-smi, so
+# it must run on the host — a container would need GPU/DRM passthrough for
+# nothing gained.
+#
+# BINDING. The base unit serves loopback only. deploy_gpu_exporter writes a
+# drop-in adding THIS host's LAN address (the same two-address posture
+# node-exporter and cadvisor use), so the endpoint is never a wildcard. It is
+# unauthenticated metrics on the LAN, identical to node-exporter :9100 and
+# cadvisor :8080 — Prometheus reaches same-host via host.containers.internal and
+# the Dankserver instance over the LAN from Dankclaw.
+
+[Unit]
+Description=GPU metrics exporter (amdgpu sysfs + nvidia-smi)
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+# Loopback by default; the deploy drop-in appends the host LAN address.
+Environment=GPU_EXPORTER_BINDS=127.0.0.1
+ExecStart=/usr/bin/python3 /home/dank/serverAppConfigs/scripts/gpu-exporter.py --serve
+Restart=always
+RestartSec=5
+
+[Install]
+WantedBy=default.target

scripts/grams-to-imatrix.py

@@ -0,0 +1,418 @@
+#!/usr/bin/env python3
+"""grams-to-imatrix.py — the engine's own calibration recording, re-voiced as a
+llama.cpp importance matrix for `rad-convert --imatrix F`. RUNS ON DANKSERVER
+beside the recording. Python 3 stdlib only: numpy must NOT be required, because
+this runs in the plain container next to a 335 GiB checkpoint, not in a venv.
+
+WHY. `rad-convert` takes its per-column activation second moments and its
+expert-popularity profile from ONE input, an imatrix (core/format/imatrix.h).
+Only the GGUF form carries a per-expert dimension — with the legacy flat form,
+or with none, every expert in a layer is weighted by the layer's aggregate,
+which is exactly the wrong thing on a 512-expert MoE. The calibration tap has
+already measured everything; this tool only re-voices it, so the imatrix and the
+protected-expert census (derive-protected-experts.py) are the SAME recording:
+one measurement, two consumers, neither able to disagree about which experts are
+hot.
+
+INPUT. RADGRAM2 files in a RADIANCE_CALIB_DIR output directory
+(arch/common/rad_arch.h, calib_write). Header law, same parse as
+scripts/derive-protected-experts.py — 32 bytes, `<8sIIQI`: magic `RADGRAM2`,
+u32 k, u32 rank, u64 rows, u32 domain, a pad word, then k*k f32 row-major. Two
+kinds of name, both GGUF-style, both with the checkpoint's GLOBAL expert
+numbering (rad_block_moe_fp8.h: ge = expert_base + e):
+
+    gram.r<rank>.blk.L.ffn_down_exps.bin        the layer's pooled gram
+    gram.r<rank>.blk.L.ffn_down_exps.<e>.bin    expert e's own gram
+
+`rows` is that file's routing/token count and the matrix is Σ x xᵀ over those
+rows, so **the diagonal is exactly the per-column activation second moment an
+imatrix wants**, and `rows` is the count the reader hands back from `count()`.
+Every off-diagonal term is dropped on purpose: the GGUF format has nowhere to
+put a full matrix, and the quantiser asks for columns.
+
+OUTPUT, per layer L (core/format/imatrix.h: names WITHOUT `.weight`, a MoE
+layer's experts folded into ONE entry, so expert 9 is slice 9 of
+`blk.L.ffn_down_exps`):
+
+  blk.L.ffn_down_exps    in_sum2 [k, n_expert] expert-major, counts [1, n_expert]
+  blk.L.ffn_gate_up_exps the SAME matrices at the SAME offsets. A routed expert's
+                         gate_up input is the same hidden-state rows as its down
+                         input, so the second moment over them is identical and
+                         so is the routing count. Two tensor infos over one
+                         payload: the reader maps each half independently
+                         (imatrix.cpp joins `<base>.in_sum2` with `<base>.counts`
+                         by base name), and copying ~200 MB to state one fact
+                         twice buys no correctness.
+  blk.L.ssm_inz          [k] and [1], from the pooled gram: that row's input is
+                         the same hidden state, so its columns take the pooled
+                         diagonal and its count is the layer's pooled rows.
+
+  Then STOP. Nothing whose input width is not the gram's k — no ssm_out, no
+  attn_output, no mtp.*, no ple_ngram. importance_for() answers false when the
+  entry's cols do not equal the weight's width and the convert proceeds without
+  it: an entry the reader silently ignores is a lie in the artifact, worse than
+  an absent one. The corollary to check before trusting the two hidden-width
+  entries: the tap writes the gate_up gram at g.n_embd and the down gram at the
+  expert width, so the gram's k must equal the checkpoint's hidden width (its
+  config.json). Where they differ, gate_up/ssm_inz are inert, not wrong.
+
+INHERITANCE. An expert with no own gram carries the layer's POOLED diagonal, and
+its count stays its own routing rows — the rule the engine itself applies when it
+picks a Hessian (libquant/lq_hess.h, calib_resolve: an expert's own gram only
+once its rank files hold kOwnRowsPerK * K rows; below that a fit to so few rows
+is worse than round-to-nearest, and those experts carry a fraction of a percent
+of the routing). The count never inherits: popularity is `count`'s job. The count
+of inherited experts is reported on stderr.
+
+RANK FOLDING. TP=2 writes gram.r0.* and gram.r1.* with GLOBAL expert numbering,
+so the ranks describe DISJOINT experts and the fold is a UNION into the one
+[k, n_expert] entry. A pooled gram is the opposite case: every rank summed the
+same stem over its own rows, so the fold is a SUM, rows included (calib_sum,
+calib_rows). The same global expert in two per-expert files is legal only when
+the numbers agree exactly; otherwise the recording is corrupt and the entry would
+be whichever file sorted last, so refuse.
+
+GGUF v3 (the only version imatrix.cpp accepts — version != 3 is a refusal):
+`general.alignment` u32, `imatrix.chunk_size` u32, `imatrix.chunk_count` u32,
+`imatrix.datasets` array of strings; tensors f32 (ggml type 0) with offsets
+relative to the aligned data section. Every tensor offset is padded up to
+`general.alignment` and the data section itself starts aligned. That is the
+classic hand-rolled-writer bug: an unaligned offset makes the reader's extent
+arithmetic point into the middle of the previous tensor's floats, and it reads
+them without complaint.
+
+chunk_count DERIVATION. The corpus row count is the LARGEST single-layer pooled
+row total, not a sum over layers: every layer's tap accumulated over the whole
+corpus, so adding the layers counts each token once per layer and inflates the
+figure by the layer count. chunk_count = that row total // chunk_size, the
+"chunks of chunk_size" line imatrix.cpp prints for itself.
+
+REFUSALS, each exit 2 with a message naming what is missing:
+  NO_GRAMS         the directory holds no RADGRAM2 down-projection gram
+  NOT_RADGRAM2     a gram whose magic is not RADGRAM2
+  SHORT            a gram whose length is not 32 + k*k*4
+  NO_POOLED        a layer with expert grams and no pooled gram to inherit from
+  K_MISMATCH       a layer whose files disagree about k (rank pooled grams, or an
+                   expert gram against its layer's pooled gram)
+  EXPERT_CONFLICT  a global expert recorded twice with different numbers
+  EXISTS           the -o path already holds a file (the trash law: move it)
+  CHUNK_COUNT      the derived chunk count does not fit the u32 metadata field
+
+USAGE. grams-to-imatrix.py <calib-dir> -o <out.gguf>
+       [--datasets NAME,...] [--chunk-size N] [--min-rows N] [-v]
+"""
+import argparse
+import os
+import re
+import struct
+import sys
+
+MAGIC = b"RADGRAM2"
+HDR = 32                       # 8s I I Q I + pad, rad_arch.h
+KOWN_ROWS_PER_K = 4            # libquant/lq_hess.h kOwnRowsPerK
+ALIGNMENT = 32                 # general.alignment, and the pad unit
+
+POOLED_RE = re.compile(r"^gram\.r(\d+)\.blk\.(\d+)\.ffn_down_exps\.bin$")
+EXPERT_RE = re.compile(r"^gram\.r(\d+)\.blk\.(\d+)\.ffn_down_exps\.(\d+)\.bin$")
+
+GT_U32, GT_STR, GT_ARR = 4, 8, 9
+GGML_F32 = 0
+
+
+def refuse(msg):
+    sys.stderr.write("REFUSED %s\n" % msg)
+    sys.exit(2)
+
+
+def read_gram(path):
+    """(k, rank, rows, domain, diagonal) from one RADGRAM2 file."""
+    try:
+        with open(path, "rb") as f:
+            raw = f.read()
+    except OSError as e:
+        refuse("UNREADABLE %s: %s" % (path, e))
+    if len(raw) < HDR:
+        refuse("SHORT %s: %d bytes, under the %d-byte RADGRAM2 header"
+               % (path, len(raw), HDR))
+    magic, k, rank, rows, domain = struct.unpack_from("<8sIIQI", raw, 0)
+    if magic != MAGIC:
+        refuse("NOT_RADGRAM2 %s: magic %r, expected b'RADGRAM2'" % (path, magic))
+    if k <= 0:
+        refuse("SHORT %s: header claims k=%d, which describes no matrix" % (path, k))
+    need = HDR + k * k * 4
+    if len(raw) != need:
+        refuse("SHORT %s: %d bytes, expected %d (32 + k*k*4 for k=%d)"
+               % (path, len(raw), need, k))
+    # The diagonal only, read by stride out of the row-major matrix.
+    diag = [struct.unpack_from("<f", raw, HDR + (i * k + i) * 4)[0]
+            for i in range(k)]
+    return k, rank, rows, domain, diag
+
+
+def load_dir(d, verbose):
+    """{layer: {"pooled": gram|None, "experts": {global e: gram}}} + rotated count.
+
+    Files outside the ffn_down_exps stem are not ours to fold: the tap names a
+    pooled gram after every projection it taps, and those carry other widths."""
+    if not os.path.isdir(d):
+        refuse("NO_GRAMS %s: not a directory" % d)
+    layers, rotated = {}, 0
+    for name in sorted(os.listdir(d)):
+        m = POOLED_RE.match(name) or EXPERT_RE.match(name)
+        if not m:
+            continue
+        path = os.path.join(d, name)
+        if not os.path.isfile(path):
+            continue
+        pooled = bool(POOLED_RE.match(name))
+        layer = int(m.group(2))
+        k, rank, rows, domain, diag = read_gram(path)
+        if domain != 0:
+            rotated += 1
+        L = layers.setdefault(layer, {"pooled": None, "experts": {}})
+        if pooled:
+            P = L["pooled"]
+            if P is None:
+                L["pooled"] = {"k": k, "rows": rows, "diag": diag, "paths": [path]}
+            elif P["k"] != k:
+                refuse("K_MISMATCH layer %d: pooled grams %s (k=%d) and %s (k=%d)"
+                       " disagree about the width"
+                       % (layer, P["paths"][0], P["k"], path, k))
+            else:
+                # calib_sum: each rank summed the same stem over its own rows.
+                P["rows"] += rows
+                P["paths"].append(path)
+                for i in range(k):
+                    P["diag"][i] += diag[i]
+            if verbose:
+                sys.stderr.write("pooled layer %d: %s k=%d rows=%d\n"
+                                 % (layer, name, k, rows))
+            continue
+        e = int(m.group(3))
+        own = L["experts"].get(e)
+        if own is None:
+            L["experts"][e] = {"k": k, "rows": rows, "diag": diag,
+                               "path": path, "ranks": [rank]}
+            if verbose:
+                sys.stderr.write("expert layer %d r%d e%d: rows=%d\n"
+                                 % (layer, rank, e, rows))
+            continue
+        if own["rows"] != rows or own["diag"] != diag:
+            refuse("EXPERT_CONFLICT layer %d expert %d: %s (rows=%d) and %s"
+                   " (rows=%d) record the same global expert with different"
+                   " numbers" % (layer, e, own["path"], own["rows"], path, rows))
+        own["ranks"].append(rank)
+        sys.stderr.write("note: layer %d expert %d recorded identically by rank %s"
+                         " and %s; folded once\n"
+                         % (layer, e, own["path"], name))
+    if not layers:
+        refuse("NO_GRAMS %s: no RADGRAM2 gram.r<rank>.blk.<L>.ffn_down_exps"
+               "[.<expert>].bin files in the directory" % d)
+    return layers, rotated
+
+
+def build_entries(layers, min_rows, verbose):
+    """([ (name, dims, payload|None, key) ], census, layers emitted)."""
+    entries = []
+    census = {"inherited": 0, "experts": 0, "routing": 0, "rows": 0, "layers": 0}
+    for layer in sorted(layers):
+        P, E = layers[layer]["pooled"], layers[layer]["experts"]
+        if E and P is None:
+            refuse("NO_POOLED layer %d: %d expert gram(s) but no pooled gram (an"
+                   " expected gram.r<rank>.blk.%d.ffn_down_exps.bin), so an expert"
+                   " under the row threshold would have nothing to inherit"
+                   % (layer, len(E), layer))
+        if P is None:
+            continue
+        k = P["k"]
+        census["layers"] += 1
+        census["rows"] = max(census["rows"], P["rows"])
+        dn = "blk.%d.ffn_down_exps" % layer
+        # A staging key names ONE payload. A gate_up entry reuses the down
+        # layer's bytes by carrying the same key with no payload of its own;
+        # in_sum2 and counts are different bytes and must never share a key.
+        ksum, kcnt = (layer, "sum2"), (layer, "counts")
+        kpgm, kpcnt = (layer, "pooled_sum2"), (layer, "pooled_counts")
+        # One entry holds one width: an expert gram recorded at another k would
+        # inherit (or be inherited by) a diagonal of the wrong length, and the
+        # reader would then answer `cols` from whichever file set dims[0].
+        for e in sorted(E):
+            if E[e]["k"] != k:
+                refuse("K_MISMATCH layer %d expert %d: %s holds k=%d and this"
+                       " layer's pooled gram is k=%d" % (layer, e, E[e]["path"],
+                                                          E[e]["k"], k))
+
+        if not E:
+            # No per-expert recording for this layer: emit the dense form
+            # ([k], [1]) rather than 512 identical slices, which would claim a
+            # per-expert measurement that was never taken.
+            entries.append((dn + ".in_sum2", [k],
+                            struct.pack("<%df" % k, *P["diag"]), ksum))
+            entries.append((dn + ".counts", [1],
+                            struct.pack("<f", float(P["rows"])), kcnt))
+            sys.stderr.write("note: layer %d has no per-expert grams; %s is"
+                             " dense over the pooled gram\n" % (layer, dn))
+        else:
+            floor = min_rows if min_rows > 0 else KOWN_ROWS_PER_K * k
+            n_expert = max(E) + 1
+            sum2, counts = bytearray(), bytearray()
+            for e in range(n_expert):
+                own = E.get(e)
+                if own is not None and own["rows"] >= floor:
+                    src = own["diag"]
+                    rows = own["rows"]
+                else:
+                    src = P["diag"]
+                    rows = own["rows"] if own is not None else 0
+                    census["inherited"] += 1
+                sum2 += struct.pack("<%df" % k, *src)
+                counts += struct.pack("<f", float(rows))
+                census["experts"] += 1
+                census["routing"] += rows
+            if min(E) != 0:
+                sys.stderr.write("note: layer %d has no gram for experts 0..%d;"
+                                 " those slices carry the pooled gram at count 0\n"
+                                 % (layer, min(E) - 1))
+            entries.append((dn + ".in_sum2", [k, n_expert], bytes(sum2), ksum))
+            entries.append((dn + ".counts", [1, n_expert], bytes(counts), kcnt))
+            gu = "blk.%d.ffn_gate_up_exps" % layer
+            entries.append((gu + ".in_sum2", [k, n_expert], None, ksum))
+            entries.append((gu + ".counts", [1, n_expert], None, kcnt))
+            if verbose:
+                sys.stderr.write("layer %d: k=%d n_expert=%d pooled_rows=%d"
+                                 " own-gram floor=%d\n"
+                                 % (layer, k, n_expert, P["rows"], floor))
+
+        inz = "blk.%d.ssm_inz" % layer
+        entries.append((inz + ".in_sum2", [k],
+                        struct.pack("<%df" % k, *P["diag"]), kpgm))
+        entries.append((inz + ".counts", [1],
+                        struct.pack("<f", float(P["rows"])), kpcnt))
+    return entries, census
+
+
+def enc_str(v):
+    b = v.encode("utf-8")
+    return struct.pack("<Q", len(b)) + b
+
+
+def write_gguf(path, entries, datasets, chunk_size, chunk_count):
+    """Write GGUF v3 and return its size in bytes.
+
+    One payload per key: entries that share a key share the bytes and the
+    offset, so a second tensor info states the same fact without copying it."""
+    kv = bytearray()
+    kv += enc_str("general.alignment") + struct.pack("<I", GT_U32) \
+        + struct.pack("<I", ALIGNMENT)
+    kv += enc_str("imatrix.chunk_size") + struct.pack("<I", GT_U32) \
+        + struct.pack("<I", chunk_size)
+    kv += enc_str("imatrix.chunk_count") + struct.pack("<I", GT_U32) \
+        + struct.pack("<I", chunk_count)
+    kv += enc_str("imatrix.datasets") + struct.pack("<I", GT_ARR) \
+        + struct.pack("<I", GT_STR) + struct.pack("<Q", len(datasets))
+    for d in datasets:
+        kv += enc_str(d)
+
+    head = bytearray()
+    head += b"GGUF" + struct.pack("<I", 3)
+    head += struct.pack("<Q", len(entries)) + struct.pack("<Q", 4)
+    head += kv
+
+    payloads = {}
+    for name, _dims, payload, key in entries:
+        if payload is None:
+            continue
+        prev = payloads.get(key)
+        if prev is not None and prev != payload:
+            # Two different payloads on one key would ship whichever was
+            # appended last while BOTH tensor infos pointed at it: the counts
+            # payload landing over the in_sum2 payload is exactly how a
+            # hand-rolled GGUF writer loses half its data without an error.
+            refuse("INTERNAL %s: two different payloads share one staging key"
+                   % name)
+        payloads.setdefault(key, payload)
+    infos = bytearray()
+    offsets, order, size = {}, [], 0
+    for name, dims, payload, key in entries:
+        if key not in payloads:
+            refuse("INTERNAL %s: no payload staged for its key" % name)
+        if key not in offsets:
+            offsets[key] = (size + ALIGNMENT - 1) // ALIGNMENT * ALIGNMENT
+            size = offsets[key] + len(payloads[key])
+            order.append(key)
+        infos += enc_str(name) + struct.pack("<I", len(dims))
+        for d in dims:
+            infos += struct.pack("<Q", d)
+        infos += struct.pack("<I", GGML_F32) + struct.pack("<Q", offsets[key])
+
+    body = bytes(head) + bytes(infos)
+    data_start = (len(body) + ALIGNMENT - 1) // ALIGNMENT * ALIGNMENT
+    with open(path, "wb") as f:
+        f.write(body)
+        f.write(b"\0" * (data_start - len(body)))
+        # The offsets in the tensor infos are the file's law, not a hint: each
+        # payload must land at its own padded offset. Writing them back to back
+        # instead leaves every reader that trusts the info — imatrix.cpp does —
+        # reading its neighbour's floats: plausible values, no error, wrong
+        # quantisation.
+        here = data_start
+        for key in order:
+            f.write(b"\0" * (data_start + offsets[key] - here))
+            f.write(payloads[key])
+            here = data_start + offsets[key] + len(payloads[key])
+        return f.tell()
+
+
+def main():
+    ap = argparse.ArgumentParser(
+        description="Fold a radiance calibration recording into a GGUF v3 imatrix.")
+    ap.add_argument("calib_dir")
+    ap.add_argument("-o", "--out", required=True)
+    ap.add_argument("--datasets", default="",
+                    help="comma-separated names for imatrix.datasets")
+    ap.add_argument("--chunk-size", type=int, default=4096,
+                    help="rows per chunk for imatrix.chunk_size (default 4096)")
+    ap.add_argument("--min-rows", type=int, default=0,
+                    help="own-gram row threshold (default 4*k, the engine's"
+                         " kOwnRowsPerK law)")
+    ap.add_argument("-v", "--verbose", action="store_true")
+    a = ap.parse_args()
+
+    if os.path.exists(a.out):
+        # The repo's deletion law: an artifact that exists is moved to trash by
+        # a human, never silently overwritten by a re-run of the tool that made
+        # it, so a second convert cannot destroy the imatrix the first one fed.
+        refuse("EXISTS %s: an imatrix is already there; move it to"
+               " .AGENTTRASH/ or name another -o" % a.out)
+    if a.chunk_size <= 0:
+        refuse("BAD_CHUNK_SIZE --chunk-size %d is not positive" % a.chunk_size)
+    layers, rotated = load_dir(a.calib_dir, a.verbose)
+    entries, census = build_entries(layers, a.min_rows, a.verbose)
+    if not entries:
+        refuse("NO_GRAMS %s: no layer holds a pooled gram to fold" % a.calib_dir)
+    if rotated:
+        sys.stderr.write("note: %d gram(s) recorded in a rotated domain: their"
+                         " diagonal is the rotated activation's second moment,"
+                         " not the model's own\n" % rotated)
+
+    chunk_count = census["rows"] // a.chunk_size
+    if chunk_count > 0xFFFFFFFF:
+        # imatrix.chunk_count is a u32 in the reader's grammar, so there is no
+        # legal way to record a bigger one. Reaching this means either a chunk
+        # size picked for a far larger run or a row total read out of the wrong
+        # header offset — rows is a u64 and a u32 parse is off by 2**32 — and
+        # the reader would trust whatever number landed in the field.
+        refuse("CHUNK_COUNT %d = %d rows // %d does not fit the u32"
+               " imatrix.chunk_count field; raise --chunk-size"
+               % (chunk_count, census["rows"], a.chunk_size))
+    nbytes = write_gguf(a.out, entries, [d for d in a.datasets.split(",") if d],
+                        a.chunk_size, chunk_count)
+    sys.stderr.write("IMATRIX_OK entries=%d layers=%d experts=%d inherited=%d"
+                     " rows=%d routing=%d chunks=%d/%d bytes=%d out=%s\n"
+                     % (len(entries), census["layers"], census["experts"],
+                        census["inherited"], census["rows"], census["routing"],
+                        chunk_count, a.chunk_size, nbytes, a.out))
+
+
+if __name__ == "__main__":
+    main()

scripts/kld-gate-qwen38.sh

@@ -0,0 +1,122 @@
+#!/usr/bin/env bash
+# kld-gate-qwen38.sh — RUNS ON DANKSERVER (or anywhere the reports are). The campaign's
+# acceptance gate: three KLD reports against ONE reference recording, one verdict.
+#
+# The reference is the BF16 container built from the vendor checkpoint (run-qwen38-bf16.sh
+# kldref, in the same drained window that records the calibration grams). Every scored
+# container is measured against that one recording, so the KL scale runs from 0 = the
+# checkpoint itself downward in faithfulness. Three containers ride it:
+#
+#   fp8.json    the published FP8-native release   — the achievable end of the interval
+#   iq4r.json   the payload frank-archon serves    — the bar to beat
+#   cand.json   the arm under test                 — the subject
+#
+# The FP8 number is what makes the interval absolute instead of relative: "half the gap"
+# is half of the distance between the 4-bit payload and the near-lossless release, not half
+# of an invented distance to the checkpoint. That is also why the FP8 payload is FETCHED and
+# scored, never converted: it is a second opinion about what this checkpoint tolerates, not a
+# step of the campaign. It lands LAST (disk sequencing) — by then the 335 GiB bf16 container
+# is gone, so its 172.8 GiB fits.
+#
+# The law, in order of severity, on the mean KL of one slice (--slice all | a corpus source):
+#   1. KL(fp8) < KL(iq4r)                 the anchors are ordered. If the near-lossless
+#                                         release does NOT sit closer to the checkpoint than
+#                                         the 4-bit payload, the corpus, the tokenizer or the
+#                                         boot shape is wrong and no arm number means anything.
+#   2. KL(fp8) < KL(cand) < KL(iq4r)      the candidate lies strictly inside the interval —
+#                                         outside it, something is mis-measured, not better
+#   3. KL(cand) <= KL(iq4r) - R x gap     it closes at least R (--recover, default 0.5) of the
+#                                         gap = KL(iq4r) - KL(fp8): at least half the way from
+#                                         what is served toward the release (agreed 2026-10-27)
+#   4. top-1(cand) >= top-1(iq4r)         the agreement the harness keys on does not fall
+#
+# Booting the containers is NOT this script's job: `run-qwen38-bf16.sh score RAD OUT.json`
+# writes the reports and owns the single engine argv (same pin, --tp 2, --kv-cache-dtype fp8,
+# same step size, --deterministic, no speculation) that makes the three numbers comparable.
+# This script is arithmetic, so it re-runs against old reports and is testable without a GPU.
+#
+# Usage: kld-gate-qwen38.sh FP8.json IQ4R.json CAND.json [--slice NAME] [--recover F]
+set -uo pipefail
+
+[ "$#" -ge 3 ] || { echo "usage: kld-gate-qwen38.sh FP8.json IQ4R.json CAND.json [--slice NAME] [--recover F]" >&2; exit 2; }
+python3 - "$@" <<'PY'
+import json, sys
+
+a = sys.argv[1:]
+opts, files = [], []
+i = 0
+while i < len(a):
+    if a[i].startswith("--"):
+        opts += [a[i], a[i + 1]]
+        i += 2
+    else:
+        files.append(a[i])
+        i += 1
+if len(files) != 3:
+    sys.exit("usage: kld-gate-qwen38.sh FP8.json IQ4R.json CAND.json [--slice NAME] [--recover F]")
+o = dict(zip(opts[0::2], opts[1::2]))
+slice_ = o.get("--slice", "all")
+recover = float(o.get("--recover", 0.5))
+if not 0.0 < recover <= 1.0:
+    sys.exit(f"--recover must be in (0,1], got {recover}")
+
+
+def die(msg):
+    print(msg, file=sys.stderr)
+    raise SystemExit(2)
+
+
+def read(path):
+    try:
+        d = json.load(open(path))
+    except Exception as e:
+        die(f"cannot read the KLD report {path}: {e}")
+    if slice_ == "all":
+        g = d.get("all")
+    else:
+        g = (d.get("by_source") or {}).get(slice_)
+        if g is None:
+            die(f"{path} has no slice {slice_!r}; it has: "
+                f"{', '.join(sorted(d.get('by_source') or {})) or '(none)'}")
+    if g is None or "kld" not in g or "top1_agreement" not in g:
+        die(f"{path} has no {slice_!r} summary — wrong report version?")
+    return d, g
+
+
+rows = []
+for label, path in zip(("fp8", "iq4r", "cand"), files):
+    d, g = read(path)
+    rows.append((label, path, d.get("model", "?"), g["kld"]["mean"], g["kld"]["p99_9"],
+                 g["top1_agreement"], g["positions"]))
+
+print(f"reference: BF16 container; slice: {slice_}")
+print(f"{'':6} {'model':38} {'KL mean':>10} {'KL p99.9':>10} {'top-1':>8}  positions")
+for label, path, model, kl, p999, top1, n in rows:
+    print(f"{label:6} {str(model)[:38]:38} {kl:10.6f} {p999:10.4f} {100*top1:7.2f}%  {n}")
+r = {label: (kl, top1) for label, _p, _m, kl, _q, top1, _n in rows}
+kl_fp8, kl_iq4r, kl_cand = r["fp8"][0], r["iq4r"][0], r["cand"][0]
+t_iq4r, t_cand = r["iq4r"][1], r["cand"][1]
+gap = kl_iq4r - kl_fp8
+ok = True
+
+
+def law(n, text, passed):
+    global ok
+    ok = ok and passed
+    print(f"  [{'PASS' if passed else 'FAIL'}] {n}. {text}")
+
+
+law(1, f"anchors ordered: fp8 {kl_fp8:.6f} < iq4r {kl_iq4r:.6f} (gap {gap:.6f})",
+    gap > 0)
+law(2, f"candidate inside the interval: {kl_fp8:.6f} < {kl_cand:.6f} < {kl_iq4r:.6f}",
+    kl_fp8 < kl_cand < kl_iq4r)
+need = kl_iq4r - recover * gap
+law(3, f"candidate closes {100*max((kl_iq4r - kl_cand)/gap, 0):.1f}% of the "
+       f"{gap:.6f} gap (needs {100*recover:.0f}%, i.e. KL <= {need:.6f})"
+       if gap > 0 else "gap is not positive; cannot score recovery",
+    gap > 0 and kl_cand <= need)
+law(4, f"candidate top-1 {100*t_cand:.2f}% >= served iq4r top-1 {100*t_iq4r:.2f}%",
+    t_cand >= t_iq4r)
+print("KLD GATE " + ("PASS" if ok else "FAIL"))
+sys.exit(0 if ok else 1)
+PY

scripts/make-calib-corpus.py

@@ -34,14 +34,25 @@ import json
 import os
 import random
 import re
+import sys
 
 from jinja2 import Environment, FileSystemLoader
-from tokenizers import Tokenizer
+
+_HERE = os.path.dirname(os.path.abspath(__file__)) if "__file__" in globals() else os.getcwd()
+if _HERE not in sys.path:
+    sys.path.insert(0, _HERE)
+
+import qwen38_common as qc  # noqa: E402 - sibling module, same directory
 
 CODE_EXT = (".sh", ".py", ".jinja", ".recipe", ".env", ".example",
             ".yaml", ".yml", ".bats", ".service", ".container", ".toml")
 JSONL_EXTS = (".jsonl", ".json")
 DOC_DIR = "serverAppConfigs-docs"
+FRAGMENT_TOKENS = 2400   # what one fragment may contribute
+CLASS_MIX = {"code": .45, "prose": .30, "tools": .25}
+HF_CAP = {"code": 40000, "prose": 60000, "tools": 0}
+POOL_CYCLES = 40         # how many times a class pool may repeat before giving up
+KLD_GUARD = 5000         # rendered conversations tried before declaring the pool short
 
 FLEET_CMDS = [
     "systemctl status frank-archon --no-pager",
@@ -142,7 +153,7 @@ def load_parquet_texts(path: str, kind: str, rng: random.Random,
     return out[:cap]
 
 
-def main() -> None:
+def parse_args() -> argparse.Namespace:
     ap = argparse.ArgumentParser(description=__doc__)
     ap.add_argument("--repo", required=True)
     ap.add_argument("--tokenizer-json", required=True)
@@ -156,22 +167,26 @@ def main() -> None:
     ap.add_argument("--hf-code-parquet", default="")
     ap.add_argument("--hf-prose-parquet", default="")
     ap.add_argument("--seed", type=int, default=20261006)
-    a = ap.parse_args()
+    return ap.parse_args()
 
-    rng = random.Random(a.seed)
-    tokenizer = Tokenizer.from_file(a.tokenizer_json)
-    env = Environment(loader=FileSystemLoader(os.path.dirname(a.template)),
+
+def load_template(template: str) -> tuple[Environment, str]:
+    """The chat template as the engine will render it, plus its short name."""
+    env = Environment(loader=FileSystemLoader(os.path.dirname(template)),
                       trim_blocks=True, lstrip_blocks=True)
     env.filters["tojson"] = lambda v: json.dumps(v, ensure_ascii=False)
     env.filters["raise_exception"] = lambda m: (_ for _ in ()).throw(
         ValueError(m))
-    tname = os.path.basename(a.template)
+    return env, os.path.basename(template)
 
+
+def classify(repo: str) -> dict[str, list[str]]:
+    """Walk the checkout into the three source classes the mix draws from."""
     code, prose, jsonl = [], [], []
-    for root, dirs, files in os.walk(a.repo):
+    for root, dirs, files in os.walk(repo):
         dirs[:] = [d for d in dirs if not d.startswith(".")]
         for f in sorted(files):
-            p = os.path.relpath(os.path.join(root, f), a.repo)
+            p = os.path.relpath(os.path.join(root, f), repo)
             if DOC_DIR in p and f.endswith(".md"):
                 prose.append(p)
             elif p.startswith(DOC_DIR):
@@ -180,137 +195,185 @@ def main() -> None:
                 code.append(p)
             elif f.endswith(JSONL_EXTS) and f != "package-lock.json":
                 jsonl.append(p)
-    # file-level split: bucket 0 -> KLD pool, 1..4 -> calibration pool
-    pools: dict[str, tuple[list, list]] = {}
-    for cls, lst in (("code", code), ("prose", prose), ("tools", jsonl)):
-        pools[cls] = ([p for p in lst if fnv(p) % 5 == 0],
-                      [p for p in lst if fnv(p) % 5 != 0])
+    return {"code": code, "prose": prose, "tools": jsonl}
 
-    def text_of(p: str) -> str:
-        path = os.path.join(a.repo, p)
-        raw = open(path, encoding="utf-8", errors="replace").read()
-        if p.endswith(JSONL_EXTS):
-            lines = [json.loads(l)["content"] for l in raw.splitlines()
-                     if l.strip() and "content" in l]
-            raw = "\n".join(lines)
-        toks = tokenizer.encode(raw, add_special_tokens=False).ids
-        return tokenizer.decode(toks[:2400], skip_special_tokens=True)
 
+def split_pools(classes: dict[str, list[str]]) -> dict[str, tuple[list, list]]:
+    """File-level split: bucket 0 -> KLD pool, everything else -> calibration."""
+    return {cls: ([p for p in lst if fnv(p) % 5 == 0],
+                  [p for p in lst if fnv(p) % 5 != 0])
+            for cls, lst in classes.items()}
+
+
+def jsonl_content(raw: str) -> str:
+    """The content fields of a content-keyed JSONL, or "" for anything else.
+
+    A .json in this repo is not necessarily a content-keyed JSONL: the substring
+    test passes on any line that merely mentions "content", and a list-shaped
+    document raises TypeError — both used to crash the whole build. Skip what
+    does not fit instead.
+    """
+    lines = []
+    for line in raw.splitlines():
+        if not line.strip() or "content" not in line:
+            continue
+        try:
+            rec = json.loads(line)
+        except json.JSONDecodeError:
+            continue
+        if isinstance(rec, dict) and isinstance(rec.get("content"), str):
+            lines.append(rec["content"])
+    return "\n".join(lines)
+
+
+def fragment_text(repo: str, rel: str, tok) -> str:
+    """One file as a fragment: its first FRAGMENT_TOKENS tokens, decoded."""
+    raw = open(os.path.join(repo, rel), encoding="utf-8",
+               errors="replace").read()
+    if rel.endswith(JSONL_EXTS):
+        raw = jsonl_content(raw)
+    ids = tok.encode(raw, add_special_tokens=False).ids
+    return tok.decode(ids[:FRAGMENT_TOKENS], skip_special_tokens=True)
+
+
+def build_frags(a: argparse.Namespace, tok,
+                rng: random.Random) -> dict[str, dict[str, list[str]]]:
+    """Both fragment pools per class, seeded so the same seed rebuilds the corpus."""
+    pools = split_pools(classify(a.repo))
     cmds = harvest_cmds(a.repo, rng)
-    # fragment pools per class, corpus-split first
     frags: dict[str, dict[str, list[str]]] = {}
-    for cls in pools:
-        kld_files, cal_files = pools[cls]
-        fr = {}
-        src = {"kld": kld_files, "cal": cal_files}
+    for cls, (kld_files, cal_files) in pools.items():
         if cls == "tools":
-            fr["kld"] = [tool_call(rng, cmds) for _ in range(600)]
-            fr["cal"] = [tool_call(rng, cmds) for _ in range(40000)]
+            frags[cls] = {"kld": [tool_call(rng, cmds) for _ in range(600)],
+                          "cal": [tool_call(rng, cmds) for _ in range(40000)]}
         else:
-            fr["kld"] = [text_of(p) for p in src["kld"]]
-            fr["cal"] = [text_of(p) for p in src["cal"]]
-        frags[cls] = fr
+            frags[cls] = {"kld": [fragment_text(a.repo, p, tok) for p in kld_files],
+                          "cal": [fragment_text(a.repo, p, tok) for p in cal_files]}
     # per-class fragment caps: prose rows are short (~66 tok) so need many;
     # codeparrot files are long (~2.6k tok) so a small cap suffices
-    hfcap = {"code": 40000, "prose": 60000, "tools": 0}
     for cls, spec in (("code", a.hf_code_parquet),
                       ("prose", a.hf_prose_parquet)):
         for path in [p for p in spec.split(",") if p]:
             frags[cls]["cal"].extend(
-                load_parquet_texts(path, cls, rng, cap=hfcap[cls]))
+                load_parquet_texts(path, cls, rng, cap=HF_CAP[cls]))
     for cls in frags:
         rng.shuffle(frags[cls]["cal"])
+    return frags
 
-    def toks(s: str) -> int:
-        return len(tokenizer.encode(s, add_special_tokens=False).ids)
 
-    def emit_calib() -> tuple[int, list[dict]]:
-        targets = {"code": .45, "prose": .30, "tools": .25}
-        rows: list[dict] = []
-        for cls, frac in targets.items():
-            want = int(a.calib_tokens * frac)
-            pool = frags[cls]["cal"]
+def pack_class(cls: str, pool: list[str], want: int, tok,
+               chunk_tokens: int) -> list[dict]:
+    """Greedily pack `pool` into chunk_tokens-sized calibration prompts."""
+    if not pool:
+        return []
+    rows: list[dict] = []
+    # Count every fragment once: the loop cycles the pool up to POOL_CYCLES
+    # times, and re-tokenizing a 2.4k-token fragment on each pass dominated the
+    # build's wall time.
+    counts = [qc.n_tokens(tok, f) for f in pool]
+    got = 0
+    i = 0
+    buf: list[str] = []
+    nbuf = 0
+    while got < want:
+        j = i % len(pool)
+        frag = pool[j]
+        i += 1
+        n = counts[j]
+        if nbuf + n > chunk_tokens and buf:
+            rows.append({"prompt": "\n".join(buf), "cls": cls})
+            got += nbuf
+            buf, nbuf = [], 0
+            if got >= want:
+                break
+        buf.append(frag)
+        nbuf += n
+        if i > len(pool) * POOL_CYCLES:
+            break  # pool exhausted with repeats; stop
+    if buf and got < want:
+        rows.append({"prompt": "\n".join(buf), "cls": cls})
+        got += nbuf
+    print(f"calib {cls}: {got} tokens, {i} fragments")
+    return rows
+
+
+def emit_calib(a: argparse.Namespace, frags, tok,
+               rng: random.Random) -> tuple[int, list[dict]]:
+    """calib.jsonl rows: the class mix, shuffled, prompts only."""
+    rows: list[dict] = []
+    for cls, frac in CLASS_MIX.items():
+        rows.extend(pack_class(cls, frags[cls]["cal"], int(a.calib_tokens * frac),
+                               tok, a.chunk_tokens))
+    rng.shuffle(rows)
+    return len(rows), [{"prompt": r["prompt"]} for r in rows]
+
+
+def emit_kld(a: argparse.Namespace, frags, tok, rng: random.Random,
+             env: Environment, tname: str) -> tuple[int, list[dict], int]:
+    """kld.jsonl rows: multi-turn conversations, each with a scored tail."""
+    template = env.get_template(tname)
+    rows: list[dict] = []
+    total = scored_total = 0
+    classes = ["code", "prose", "tools"]
+    cursor = {c: 0 for c in classes}
+    guard = 0
+    while total < a.kld_tokens and guard < KLD_GUARD:
+        guard += 1
+        msgs, srcs = [], []
+        for t in range(rng.choice([2, 3, 4])):
+            cls = classes[(len(rows) + t) % 3]
+            pool = frags[cls]["kld"]
             if not pool:
                 continue
-            got, i, buf, nbuf = 0, 0, [], 0
-            while got < want:
-                frag = pool[i % len(pool)]
-                i += 1
-                n = toks(frag)
-                if nbuf + n > a.chunk_tokens and buf:
-                    rows.append({"prompt": "\n".join(buf), "cls": cls})
-                    got += nbuf
-                    buf, nbuf = [], 0
-                    if got >= want:
-                        break
-                buf.append(frag)
-                nbuf += n
-                if i > len(pool) * 40:
-                    break  # pool exhausted with repeats; stop
-            if buf and got < want:
-                rows.append({"prompt": "\n".join(buf), "cls": cls})
-                got += nbuf
-            print(f"calib {cls}: {got} tokens, {i} fragments")
-        rng.shuffle(rows)
-        return len(rows), [{k: v for k, v in r.items() if k == "prompt"}
-                           for r in rows]
+            frag = pool[cursor[cls] % len(pool)]
+            cursor[cls] += 1
+            msgs.append({"role": "user",
+                         "content": "Summarize and explain this "
+                                    f"engineering material:\n{frag}"})
+            msgs.append({"role": "assistant",
+                         "content": frag[:4000]})
+            srcs.append(cls)
+        rendered = template.render(messages=msgs, add_generation_prompt=False)
+        n = qc.n_tokens(tok, rendered)
+        if n < a.kld_min_prompt:
+            continue
+        rows.append({"prompt": rendered,
+                     "score_from": n - a.score_tail,
+                     "source": "+".join(sorted(set(srcs)))})
+        total += n
+        scored_total += a.score_tail
+    return len(rows), rows, scored_total
 
-    def emit_kld() -> tuple[int, list[dict]]:
-        rows, total = [], 0
-        classes = ["code", "prose", "tools"]
-        i = {c: 0 for c in classes}
-        guard = 0
-        while total < a.kld_tokens and guard < 5000:
-            guard += 1
-            msgs, srcs = [], []
-            for t in range(rng.choice([2, 3, 4])):
-                cls = classes[(len(rows) + t) % 3]
-                pool = frags[cls]["kld"]
-                if not pool:
-                    continue
-                frag = pool[i[cls] % len(pool)]
-                i[cls] += 2
-                msgs.append({"role": "user",
-                             "content": "Summarize and explain this "
-                                        f"engineering material:\n{frag}"})
-                msgs.append({"role": "assistant",
-                             "content": frag[:4000]})
-                srcs.append(cls)
-            rendered = env.get_template(tname).render(
-                messages=msgs, add_generation_prompt=False)
-            n = toks(rendered)
-            if n < a.kld_min_prompt:
-                continue
-            rows.append({"prompt": rendered,
-                         "score_from": n - a.score_tail,
-                         "source": "+".join(sorted(set(srcs)))})
-            total += n
-        return len(rows), rows
 
-    os.makedirs(a.out_dir, exist_ok=True)
-    nc, rows = emit_calib()
-    with open(os.path.join(a.out_dir, "calib.jsonl"), "w") as f:
-        for r in rows:
-            f.write(json.dumps(r) + "\n")
-    nk, krows = emit_kld()
-    with open(os.path.join(a.out_dir, "kld.jsonl"), "w") as f:
-        for r in krows:
-            f.write(json.dumps(r) + "\n")
-    scored = sum(len(tokenizer.encode(r["prompt"], add_special_tokens=False).ids)
-                 - r["score_from"] for r in krows)
-    manifest = {
+def manifest(a: argparse.Namespace, tname: str, nc: int, nk: int,
+             scored: int) -> dict:
+    return {
         "seed": a.seed, "template": tname,
         "tokenizer": os.path.basename(a.tokenizer_json),
         "calib_prompts": nc, "kld_prompts": nk,
         "kld_scored_positions": scored,
         "kld_score_tail": a.score_tail,
         "disjoint_file_pools": "local KLD material only; HF code feeds calib",
-        "calib_mix": {"code": .45, "prose": .30, "tools": .25},
+        "calib_mix": dict(CLASS_MIX),
         "hf_code": a.hf_code_parquet, "hf_prose": a.hf_prose_parquet,
     }
-    with open(os.path.join(a.out_dir, "manifest.json"), "w") as f:
-        json.dump(manifest, f, indent=1)
-    print(json.dumps(manifest, indent=1))
+
+
+def main() -> None:
+    a = parse_args()
+    rng = random.Random(a.seed)
+    tok = qc.load_tokenizer(a.tokenizer_json)
+    env, tname = load_template(a.template)
+
+    frags = build_frags(a, tok, rng)
+    os.makedirs(a.out_dir, exist_ok=True)
+    nc, calib_rows = emit_calib(a, frags, tok, rng)
+    qc.write_jsonl(os.path.join(a.out_dir, "calib.jsonl"), calib_rows)
+    nk, kld_rows, scored = emit_kld(a, frags, tok, rng, env, tname)
+    qc.write_jsonl(os.path.join(a.out_dir, "kld.jsonl"), kld_rows)
+    man = manifest(a, tname, nc, nk, scored)
+    qc.write_json(os.path.join(a.out_dir, "manifest.json"), man)
+    print(json.dumps(man, indent=1))
 
 
 if __name__ == "__main__":

scripts/open-notebook.env

@@ -1,5 +1,6 @@
 # open-notebook.env — configuration for **open-notebook**, the fleet's podcast
-# generator on Dankclaw (UI host port **8502**, API host port **5056**). Read by
+# generator on Dankclaw (user path https://notebook.franksdank.cloud; UI host
+# port **8502**, API host port **5056 loopback-only**). Read by
 # BOTH Quadlet units (dankclaw/open-notebook/quadlet/) as the FIRST
 # EnvironmentFile= line, which is why every path and host name below is the
 # value the CONTAINER must see.
@@ -47,13 +48,17 @@
 #
 # THE SCRIPTWRITER. ESPERANTO_LLM_TIMEOUT is the app's own default (180 s), kept
 # visible beside the TTS number because both belong to one podcast run: the
-# outline call and the transcript call are the slow text work, and frank-zealot
-# answers them well inside 180. Provider choice is made in the UI, not here —
-# see [[Open Notebook]] for the one-time credential provisioning — and it is
-# frank-zealot on purpose: script writing asks for a JSON-schema response, which
-# the OpenAI-compatible llama.cpp endpoint is known to serve, while halogen's
-# structured-output behaviour on frank-dragoon is UNVERIFIED. halogen remains
-# the unproven alternative, not the fallback.
+# outline call and the transcript call are the slow text work, and the endpoint
+# provisioned today answers them well inside 180. The provider itself is chosen
+# in the database, not here — [[Open Notebook]] owns that provisioning and the
+# address census behind it. Short version: frank-zealot was the plan (script
+# writing asks for a JSON-schema response, which llama.cpp serves and halogen's
+# behaviour on frank-dragoon is UNVERIFIED), but no Dankclaw LLM is dialable from
+# this container's netns, and the single address that reaches one —
+# `host.containers.internal`, 169.254.1.2 — the app refuses to store at all,
+# because link-local is a blocked address class. The writer is therefore
+# frank-archon (`http://192.168.0.235:7770/v1`), the only fleet LLM that both
+# answers from inside this netns and passes that check.
 #
 # THE DATABASE COORDINATES. SURREAL_URL addresses the sibling container BY NAME
 # on systemd-open-notebook (container DNS is scoped to the owning network, so
@@ -73,15 +78,20 @@ SURREAL_PASS=
 OPEN_NOTEBOOK_ENCRYPTION_KEY=
 OPEN_NOTEBOOK_PASSWORD=
 
-# WHERE THE BROWSER FINDS THE API. The UI auto-detects `<host-you-opened>:5055`,
-# and 5055 on this host belongs to seerr, so the API leaves the container on 5056
-# and this line has to say so. Both origins are listed in CORS_ORIGINS because
-# the API is called cross-origin from the UI's own port: the LAN origin is the
-# normal one, the localhost one covers a browser opened on Dankclaw itself. The
-# app logs a warning at start while CORS_ORIGINS is unset and defaults to `*`,
-# which is a wildcard in front of an endpoint that serves every episode's audio.
-API_URL=http://192.168.0.143:5056
-CORS_ORIGINS=http://192.168.0.143:8502,http://localhost:8502
+# WHERE THE BROWSER FINDS THE API. The guarded vhost
+# (notebook.franksdank.cloud → Caddy → 8502) is the only user path, and the
+# image's own Next.js layer rewrites `/api/*` to the FastAPI running beside it,
+# so ONE origin serves UI and API and API_URL has to name that vhost. This is
+# not cosmetic: unset, the app auto-detects `<host-you-opened>:5055` — the port
+# upstream ships, and the one seerr holds on this host — and hands the browser
+# an address nothing answers; pointed at the LAN `:5056` instead, every call
+# leaves the guarded origin and an authenticated browser session does not ride
+# it. Same-origin traffic needs no CORS at all, but CORS_ORIGINS stays set to
+# the one origin because the app warns at start while it is unset and defaults
+# to `*` — a wildcard in front of an endpoint that serves every episode's
+# audio. No trailing slash: the UI concatenates `${API_URL}/api/...`.
+API_URL=https://notebook.franksdank.cloud
+CORS_ORIGINS=https://notebook.franksdank.cloud
 
 # Concurrency: see "THE CPU-SHUTDOWN GUARD" above. Defaults are 5 and 5.
 TTS_BATCH_SIZE=1

scripts/probe-frank-archon-kv.py

@@ -147,10 +147,21 @@ def main():
     deep = corpus(160_000)
     wide = corpus(1_100_000)
 
-    # 3.28 chars/token is the measured ratio of this corpus through the
-    # froggeric template (646,000 chars -> 196,919 tokens at the 2026-10-11
-    # deploy); 98.5 % of the window leaves the response room under the ceiling.
-    chars = int(0.985 * maxlen * 3.28)
+    # The corpus's chars/token ratio is MEASURED here, not stored. A stored 3.28
+    # (646,000 chars -> 196,919 tokens, 2026-10-11) had drifted to 3.20 by
+    # 2026-10-20 (646,299 chars -> 201,876 tokens) as the repo's docs grew, and a
+    # stale constant sends leg B past --max-model-len, where the engine answers a
+    # perfectly legitimate 400 ("the request (201900 tokens) exceeds the available
+    # context size (200000)") and the leg reads as a capacity failure. One small
+    # request prices the ratio; 97 % of the window leaves the response room.
+    sample = prompt(wide, 4000, "CAL", "cal-marker")
+    cal, _, _ = post({"model": MODEL,
+                      "messages": [{"role": "user", "content": sample}],
+                      "max_tokens": 1, "temperature": 0.0,
+                      "chat_template_kwargs": {"enable_thinking": False}})
+    ratio = len(sample) / cal["usage"]["prompt_tokens"]
+    print(f"[cal] corpus ratio {ratio:.2f} chars/token")
+    chars = int(0.97 * maxlen * ratio)
     # Each marker's FIRST hyphen-separated word is unique, because show()
     # scores the hit on that word — a shared prefix would score every slot HIT
     # on any answer that says the word.
@@ -176,7 +187,7 @@ def main():
                 print(f"[B-{s}] FAILED after {time.time() - t0:.1f}s: {e!r}")
     print(f"[B] total {time.time() - t0:.1f}s")
     # D — concurrency decode: seqs streams, 512 tokens each, ~25 % depth.
-    dchars = int(0.25 * maxlen * 3.28)
+    dchars = int(0.25 * maxlen * ratio)
     dbodies = [chat(deep, dchars, f"D{i + 1}-9137", f"flint-marker-{i}", 512)
                for i in range(seqs)]
     print(f"[D] {seqs} concurrent streams x 512 tokens, "

scripts/purge-agenttrash.sh

@@ -0,0 +1,335 @@
+#!/bin/sh
+# Deterministically empty every .AGENTTRASH directory under the given roots.
+#
+# PURPOSE
+#   The fleet's deletion policy parks deleted files in .AGENTTRASH/ — in-repo
+#   beside the item, elsewhere in $HOME as .AGENTTRASH/YYYYMMDD-topic — and
+#   waits for approval to purge. This script is that purge: given a machine,
+#   it clears .AGENTTRASH directories and nothing else.
+#
+# CONTRACT
+#   Default dry-run: the plan prints and nothing is deleted; --execute deletes.
+#   Every line the script can ever print for a candidate is decided at plan time
+#   and stored in the plan table, so a dry run prints exactly what --execute
+#   will print. A .AGENTTRASH that is a root's own trash (a repo's
+#   .AGENTTRASH, a machine's ~/.AGENTTRASH) prints `plan empty <path>`: the
+#   directory is the convention and survives, its staged contents are cleared.
+#   A .AGENTTRASH deeper than that is content and prints `plan remove <path>`
+#   plus, once executed, `removed <path>`; its own nested .AGENTTRASH entries
+#   belong to that tree and are never planned again. Candidates are found with
+#   `find -xdev` per root, so a mounted tree can never be walked by accident;
+#   ordering is lexicographic (LC_ALL=C). `/`, symlinked, and foreign-owned
+#   candidates are refused and reported (exit 1), never touched.
+#   A summary line `removed=<candidates> deleted=<removed> refused=<n>` closes
+#   every run and one dated line is appended to the log.
+#   Exit: 0 success, 1 operational failure, 2 usage error. A second run over
+#   the same tree plans nothing further and exits 0.
+#
+# PORTABILITY
+#   POSIX sh, clean under `shellcheck -S style`. Externals: find (must support
+#   -delete), stat, rm, date, mkdir. No bashisms, no GNU-only flags, no arrays,
+#   no `local`. Paths containing whitespace are rejected at parse time — the
+#   same rule applied to roots and candidates — so the plan can be walked with
+#   plain word splitting and nothing can be silently mis-split.
+#
+# USAGE
+#   purge-agenttrash [--execute] [--quiet] [--log PATH] [PATH...]
+#   --execute   delete; without it the run is a plan and deletes nothing
+#   --quiet     suppress per-line output; errors and the summary still print
+#   --log PATH  log destination (default: $HOME/.AGENTTRASH-cleanup.log)
+#   PATH...     roots to search (default: $HOME)
+#
+# Everything else is fixed by design: the root default, the ordering, the
+# guards. There is no configuration file and no environment override.
+
+set -eu
+
+usage() {
+    sed -n '3,44p' "$0" | sed 's/^# \{0,1\}//'
+}
+
+die() {
+    printf '%s: %s\n' 'purge-agenttrash' "$1" >&2
+    exit "${2:-1}"
+}
+
+# ------------------------------------------------------------------ arg parser
+# Roots accumulate as one space-separated string: a root containing whitespace is
+# rejected at parse time rather than silently split later. That leaves the plan
+# iteratable with plain `$@`-free word splitting, the only portable construct
+# that cannot corrupt a path it has already vetted.
+MODE=plan
+QUIET=0
+LOGPATH=
+ROOTS=
+while [ "$#" -gt 0 ]; do
+    case "$1" in
+        --help|-h)
+            usage
+            exit 0
+            ;;
+        --execute)
+            MODE=execute
+            ;;
+        --quiet)
+            QUIET=1
+            ;;
+        --log)
+            [ "$#" -ge 2 ] || die '--log needs a value' 2
+            LOGPATH=$2
+            shift
+            ;;
+        --log=*)
+            LOGPATH=${1#--log=}
+            ;;
+        -*)
+            die "unknown option: $1" 2
+            ;;
+        *)
+            case $1 in
+                *' '*) die "root contains whitespace: $1" 2 ;;
+            esac
+            if [ -z "$ROOTS" ]; then
+                ROOTS=$1
+            else
+                ROOTS="$ROOTS $1"
+            fi
+            ;;
+    esac
+    shift
+done
+
+[ -n "${HOME:-}" ] || die 'HOME is not set; pass roots explicitly or set HOME' 2
+[ -n "$LOGPATH" ] || LOGPATH=$HOME/.AGENTTRASH-cleanup.log
+
+# ------------------------------------------------------------ tool availability
+require() {
+    command -v "$1" >/dev/null 2>&1 || die "required tool not found: $1" 1
+}
+require find
+require stat
+require rm
+require date
+require mkdir
+
+# `find -delete` backs the in-place emptying. Probe it rather than trusting
+# `find --version`: a shell function named `find` must not be able to fake it.
+if ! find . -maxdepth 0 -name '.purge-probe-does-not-exist' -delete >/dev/null 2>&1; then
+    die 'find does not support -delete; refusing to guess at deletion' 1
+fi
+
+UID_SELF=$(id -u)
+
+# ------------------------------------------------------------------- locking
+# The lock dir also hosts this run's plan table, so both live and die together:
+# the exit trap removes the whole directory and only the log survives the run.
+LOCKDIR=$HOME/.agenttrash-purge.lock
+PLANFILE=$LOCKDIR/plan
+
+acquire_lock() {
+    if ! mkdir "$LOCKDIR" 2>/dev/null; then
+        held_pid=$(cat "$LOCKDIR/pid" 2>/dev/null || printf '%s\n' '')
+        if [ -n "$held_pid" ] && kill -0 "$held_pid" 2>/dev/null; then
+            die "another purge holds $LOCKDIR (pid $held_pid)" 1
+        fi
+        # Owner died mid-run: drop its pid, then retry exactly once. An
+        # unremovable/nonempty lock dir is not ours to reclaim.
+        rm -f "$LOCKDIR/pid" 2>/dev/null || true
+        rmdir "$LOCKDIR" 2>/dev/null || die "$LOCKDIR exists and is not ours to reclaim" 1
+        mkdir "$LOCKDIR" 2>/dev/null || die "cannot reacquire $LOCKDIR" 1
+    fi
+    printf '%s\n' "$$" >"$LOCKDIR/pid" || die "cannot stamp $LOCKDIR/pid" 1
+    : >"$PLANFILE" || die "cannot write $PLANFILE" 1
+    trap 'rm -rf "$LOCKDIR"' EXIT
+    trap 'exit 130' INT
+    trap 'exit 143' TERM
+}
+
+# ------------------------------------------------------------------ predicates
+is_dir() {  # true only for a real directory, never a symlink to one
+    [ -d "$1" ] && [ ! -L "$1" ]
+}
+
+is_ours() {  # true only when the invoking user owns the path
+    owner=$(stat -c '%u' "$1" 2>/dev/null) || return 1
+    [ "$owner" = "$UID_SELF" ]
+}
+
+refuse() {  # refuse <path> <reason>  — reported, never deleted
+    printf '%s: refused %s (%s)\n' 'purge-agenttrash' "$1" "$2" >&2
+    REFUSED=$((REFUSED + 1))
+}
+
+emit() {  # emit <line>  — silenced by --quiet
+    [ "$QUIET" -eq 1 ] || printf '%s\n' "$1"
+}
+
+# --------------------------------------------------------------- the plan table
+# One row per candidate: `<action> <path> <line>`. The first two fields tell
+# `act_on` what to do; the rest of the row is EXACTLY what the run prints for
+# that candidate — in plan mode verbatim, in execute mode as the first line of
+# its report. The table is a file, so no shell quoting rule (quoted-for,
+# heredoc, IFS games) can corrupt an approved plan, and the two modes can
+# never drift apart. A removal's second line (`removed <path>`) is derived from
+# the row's action, so it is also fixed at plan time.
+CANDIDATES=0
+REFUSED=0
+
+record() {  # record <action> <path> <line>  — append one row to the plan table
+    printf '%s %s %s\n' "$1" "$2" "$3" >>"$PLANFILE"
+    CANDIDATES=$((CANDIDATES + 1))
+}
+
+# ------------------------------------------------------------- candidate rule
+# The whole contract in one place:
+#   `/` is refused outright (never a candidate, never walked);
+#   a root that is a symlink or a plain file is refused, never followed;
+#   a root (or any path) that IS a real .AGENTTRASH prints `plan empty <path>`:
+#     the convention persists, its staged contents are what gets cleared;
+#   otherwise the root's DIRECT .AGENTTRASH child is also `empty` — it is that
+#     level's own trash ($HOME/.AGENTTRASH, x1/.AGENTTRASH, repo-a/.AGENTTRASH);
+#   every .AGENTTRASH deeper than that is content: `remove`, printed as
+#     `plan remove <path>` (+ `removed <path>` when executed), unless it lives
+#     inside a tree already claimed (then it dies with that tree, never planned
+#     twice) or is foreign-owned/symlinked (then refused).
+collect_root() {  # collect_root <path> -> 0 ok, 1 refused
+    target=$1
+    if [ "$target" = / ]; then
+        refuse / 'root refusal'
+        return 1
+    fi
+    if [ -L "$target" ] || ! [ -d "$target" ]; then
+        refuse "$target" 'not a real directory'
+        return 1
+    fi
+    if ! is_ours "$target"; then
+        refuse "$target" "not owned by uid $UID_SELF"
+        return 1
+    fi
+    if [ "${target##*/}" = .AGENTTRASH ]; then
+        record empty "$target" "plan empty $target"
+        return 0
+    fi
+    # `own` is the root's own .AGENTTRASH once handled; hits below it belong to
+    # that tree and must never be planned a second time.
+    own=
+    if [ -e "$target/.AGENTTRASH" ]; then
+        if ! is_ours "$target/.AGENTTRASH"; then
+            refuse "$target/.AGENTTRASH" "not owned by uid $UID_SELF"
+        elif ! is_dir "$target/.AGENTTRASH"; then
+            refuse "$target/.AGENTTRASH" 'not a real directory'
+        else
+            record empty "$target/.AGENTTRASH" "plan empty $target/.AGENTTRASH"
+            own=$target/.AGENTTRASH
+        fi
+    fi
+    # No `-type d`: implementations disagree on whether that matches a
+    # symlink-to-directory (GNU find says no, others yes), so every entry named
+    # .AGENTTRASH is collected and classified here instead of by `find`.
+    if ! found=$(find "$target" -xdev -name .AGENTTRASH 2>/dev/null); then
+        refuse "$target" 'find failed'
+        return 1
+    fi
+    previous=
+    for entry in $found; do
+        [ -n "$entry" ] || continue
+        if [ -n "$own" ]; then
+            case $entry in
+                "$own"|"$own"/*) continue ;;   # already emptied in place
+            esac
+        fi
+        if [ -n "$previous" ]; then
+            case $entry in
+                "$previous"/*) continue ;;   # nested: dies with its parent
+            esac
+        fi
+        previous=$entry
+        if ! is_ours "$entry"; then
+            refuse "$entry" "not owned by uid $UID_SELF"
+            continue
+        fi
+        if ! is_dir "$entry"; then
+            refuse "$entry" 'not a real directory'
+            continue
+        fi
+        record remove "$entry" "plan remove $entry"
+    done
+    return 0
+}
+
+# ------------------------------------------------------------------ execution
+remove_tree() {  # rm -rf a real directory; symlinks inside die as entries
+    is_dir "$1" || return 1
+    rm -rf -- "$1"
+}
+
+empty_dir() {  # empty a real directory in place, never following symlinks
+    is_dir "$1" || return 1
+    find "$1" -mindepth 1 -xdev -delete
+}
+
+# act_on <action> <path> <line> -> 0 when the action succeeded.
+# remove: prints the stored line (`plan remove <path>`) then `removed <path>`.
+# empty:  prints the stored line (`plan empty <path>`) and nothing else — the
+#         directory survives, so the plan line IS the outcome.
+act_on() {  # act_on <action> <path> <line> -> 0 when the action succeeded
+    if [ "$1" = remove ]; then
+        if remove_tree "$2" 2>/dev/null; then
+            emit "$3"
+            emit "removed $2"
+            return 0
+        fi
+        printf '%s: failed to remove %s\n' 'purge-agenttrash' "$2" >&2
+        return 1
+    fi
+    if empty_dir "$2" 2>/dev/null; then
+        emit "$3"
+        return 0
+    fi
+    printf '%s: failed to empty %s\n' 'purge-agenttrash' "$2" >&2
+    return 1
+}
+
+# Walk the plan table once: plan mode prints every row's line verbatim, execute
+# mode acts on each row and counts failures separately from plan-time refusals.
+walk_plan() {
+    while read -r action path line; do
+        [ -n "$action" ] || continue
+        if [ "$MODE" = plan ]; then
+            emit "$line"
+        elif act_on "$action" "$path" "$line"; then
+            REMOVED=$((REMOVED + 1))
+        else
+            EXEC_REFUSED=$((EXEC_REFUSED + 1))
+        fi
+    done <"$PLANFILE"
+}
+
+# ----------------------------------------------------------------------- main
+[ -n "$ROOTS" ] || ROOTS=$HOME
+
+acquire_lock
+
+for root in $ROOTS; do
+    collect_root "$root" || true
+done
+
+REMOVED=0
+EXEC_REFUSED=0
+walk_plan
+
+STATUS=0
+[ "$REFUSED" -eq 0 ] || STATUS=1
+[ "$EXEC_REFUSED" -eq 0 ] || STATUS=1
+
+printf 'removed=%s deleted=%s refused=%s\n' \
+    "$CANDIDATES" "$REMOVED" "$((REFUSED + EXEC_REFUSED))"
+
+if ! printf '%s\tplan\tcandidates=%s\tremoved=%s\trefused=%s\n' \
+    "$(date -u '+%Y-%m-%dT%H:%M:%SZ')" "$CANDIDATES" "$REMOVED" \
+    "$((REFUSED + EXEC_REFUSED))" >>"$LOGPATH" 2>/dev/null; then
+    printf '%s: cannot write log %s\n' 'purge-agenttrash' "$LOGPATH" >&2
+    STATUS=1
+fi
+
+exit "$STATUS"

scripts/qwen38_common.py

@@ -0,0 +1,94 @@
+#!/usr/bin/env python3
+"""Shared plumbing for the qwen38 campaign corpus tools.
+
+The three tools move the same two shapes — a JSONL of prompt records and a
+one-artifact JSON manifest — and they all tokenize with the SAME tokenizer. That
+last part is not a detail: a KLD reference is only meaningful against the exact
+token sequence the corpus recorded, so `n_tokens` exists once, here, and every
+tool counts the same way. A window that decode/encode does not round-trip is a
+refusal, never a warning.
+
+Loaded as a sibling module. Each tool puts its own directory on `sys.path`
+first, so `python3 scripts/<tool>.py` and the driver's container mount
+(`runpy.run_path('/work/<tool>.py')`, `-v scripts:/work:ro`) both resolve it —
+run the tools by path, not piped through stdin.
+"""
+import contextlib
+import json
+import os
+import sys
+import tempfile
+
+
+def refuse(msg: str) -> None:
+    """Exit 2 with a REFUSED line — the code argparse uses for unusable input."""
+    print(f"REFUSED: {msg}", file=sys.stderr)
+    sys.exit(2)
+
+
+def load_tokenizer(path: str):
+    try:
+        from tokenizers import Tokenizer
+    except ImportError as exc:  # the corpus tools carry their own venv
+        refuse(f"tokenizers is not importable by {sys.executable} — run the "
+               f"corpus venv's python (on dankserver: "
+               f"/home/dank/venvs/radcorpus/bin/python) or set "
+               f"FRANK_QWEN38_TOKENIZER: {exc}")
+    if not os.path.isfile(path):
+        refuse(f"no tokenizer at {path}")
+    return Tokenizer.from_file(path)
+
+
+def n_tokens(tok, text: str) -> int:
+    """The corpus's own count: no special tokens added, prompt side only."""
+    return len(tok.encode(text, add_special_tokens=False).ids)
+
+
+def iter_jsonl(path: str):
+    """Yield `(lineno, record)` for every non-blank line; refuse on a bad line.
+
+    Field validation stays with the caller: the three corpora carry different
+    fields (`prompt` alone, `prompt`+`cls`, `prompt`+`score_from`+`source`), and
+    a record missing the one the tool needs is that tool's refusal to make.
+    """
+    with open(path, encoding="utf-8", errors="replace") as fh:
+        for lineno, line in enumerate(fh, 1):
+            if not line.strip():
+                continue
+            try:
+                rec = json.loads(line)
+            except json.JSONDecodeError as exc:
+                refuse(f"{path}:{lineno} is not JSON: {exc}")
+            yield lineno, rec
+
+
+def write_jsonl(path: str, rows) -> None:
+    with open(path, "w", encoding="utf-8") as fh:
+        for row in rows:
+            fh.write(json.dumps(row, ensure_ascii=False) + "\n")
+
+
+@contextlib.contextmanager
+def atomic_writer(path: str):
+    """Write `path` through a temporary sibling and rename on success.
+
+    An interrupted run then leaves no half corpus behind, and the temporary name
+    keeps the one-artifact-one-name law the driver applies to a score report.
+    """
+    d = os.path.dirname(os.path.abspath(path)) or "."
+    fd, tmp = tempfile.mkstemp(dir=d, prefix="." + os.path.basename(path) + "-")
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as fh:
+            yield fh
+        os.replace(tmp, path)
+    except BaseException:
+        if os.path.exists(tmp):
+            os.unlink(tmp)
+        raise
+    os.chmod(path, 0o644)
+
+
+def write_json(path: str, obj) -> None:
+    with atomic_writer(path) as fh:
+        json.dump(obj, fh, indent=1)
+        fh.write("\n")

scripts/rechunk-kld-corpus.py

@@ -0,0 +1,192 @@
+#!/usr/bin/env python3
+"""Re-chunk a KLD corpus so every document fits the container that scores it.
+
+A KLD reference is recorded by booting one container and prefilling every corpus
+document through it. radiance refuses a document the KV pool cannot hold on its
+own (core/mem/kv.cpp `can_ever_fit`: a paged group holds `n_blocks *
+block_size` tokens), and the number that matters is printed by the boot ledger,
+not by a flag:
+
+    W kv group 'kv_attn' holds 7436 tokens but the context limit is 32768, so
+    a prompt longer than 7436 tokens is refused (400) ... or lower
+    --max-model-len to 7436
+
+The BF16 qwen4exp container at the campaign's shape gets 270.00 MiB of cache --
+the expert plane owns both cards -- so its real window is 7,436 tokens however
+`--max-model-len` is spelled. The corpus the campaign inherited from the swift15
+era is 197 documents of 8,193-11,970 tokens, because make-calib-corpus.py's
+`--kld-min-prompt 8192` sets a floor and no ceiling: every one of them is
+unscoreable there, and three drained windows have proved it.
+
+This script moves the document boundaries and nothing else. Each record's token
+ids -- counted with the same tokenizer the generator used -- are cut into
+windows of at most `--max-doc-tokens`, so a record's windows concatenate back to
+that record's own token sequence, unchanged: no token dropped, rewritten or
+reworded. Each window gets its own `score_from = len - --score-tail`, the same
+relation the generator wrote for the parent, so the reference scores 256
+positions per window instead of per document: 100,864 measured positions over
+the same text against the 50,432 the inherited corpus scored, at a shorter
+context. The calibration corpus is untouched, so the quantization itself does
+not move.
+
+Usage:
+  rechunk-kld-corpus.py --corpus kld.jsonl --out kld.jsonl.new \
+      [--tokenizer-json PATH] [--max-doc-tokens 7168] [--score-tail 256] [--force]
+
+--out must not exist and be non-empty without --force: the same
+one-artifact-one-name law run-qwen38-bf16.sh applies to a score report. The file
+is written through a temporary name and renamed, so an interrupted run leaves no
+half corpus behind. A JSON summary of what was written goes to stdout.
+"""
+import argparse
+import dataclasses
+import json
+import os
+import sys
+
+_HERE = os.path.dirname(os.path.abspath(__file__)) if "__file__" in globals() else os.getcwd()
+if _HERE not in sys.path:
+    sys.path.insert(0, _HERE)
+
+import qwen38_common as qc
+
+MISSING = object()  # "the parent record carried no source field"
+
+
+def parse_args() -> argparse.Namespace:
+    ap = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    ap.add_argument("--corpus", required=True,
+                    help="the kld.jsonl to re-chunk (records: prompt, score_from, source)")
+    ap.add_argument("--out", required=True,
+                    help="file to write; refuse if it exists and is non-empty without --force")
+    ap.add_argument("--tokenizer-json",
+                    default=os.environ.get("FRANK_QWEN38_TOKENIZER",
+                                           "/home/dank/models/Qwen3.8-Flash-Next/tokenizer.json"),
+                    help="the tokenizer the corpus was authored with (the same one the "
+                         "manifest in the corpus output dir names)")
+    ap.add_argument("--max-doc-tokens", type=int, default=7168,
+                    help="the widest document the scoring container can hold; 7,168 is "
+                         "7x1024, the largest whole kilopage under the 7,436 the bf16 "
+                         "container's ledger reports")
+    ap.add_argument("--score-tail", type=int, default=256,
+                    help="positions scored at the end of every document, as the generator "
+                         "recorded it")
+    ap.add_argument("--force", action="store_true",
+                    help="overwrite a non-empty --out (after moving the old file to trash)")
+    return ap.parse_args()
+
+
+@dataclasses.dataclass(frozen=True)
+class Window:
+    """One scoring document cut out of a parent record."""
+    prompt: str
+    score_from: int
+    n_tokens: int
+    clamped: bool
+    source: object = MISSING
+
+    def record(self) -> dict:
+        rec = {"prompt": self.prompt, "score_from": self.score_from}
+        if self.source is not MISSING:
+            rec["source"] = self.source
+        return rec
+
+
+def validate(a: argparse.Namespace) -> None:
+    """Everything that makes this run unusable, named before a token is cut."""
+    if a.max_doc_tokens <= 0:
+        qc.refuse(f"--max-doc-tokens must be positive (got {a.max_doc_tokens})")
+    if a.score_tail <= 0:
+        qc.refuse(f"--score-tail must be positive (got {a.score_tail})")
+    if a.max_doc_tokens <= a.score_tail:
+        qc.refuse(f"--max-doc-tokens {a.max_doc_tokens} cannot hold a "
+                  f"{a.score_tail}-position score tail: every window would be all "
+                  "tail and no context")
+    if not os.path.isfile(a.corpus):
+        qc.refuse(f"no corpus at {a.corpus}")
+    if os.path.realpath(a.out) == os.path.realpath(a.corpus):
+        qc.refuse(f"--out {a.out} is the corpus itself; move it to trash first — the "
+                  "trash law means the old segmentation stays recoverable")
+    if os.path.exists(a.out) and os.path.getsize(a.out) > 0 and not a.force:
+        qc.refuse(f"{a.out} exists and is not empty; pass --force after moving it to trash")
+
+
+def cut(rec: dict, tok, a: argparse.Namespace,
+        where: str) -> tuple[list[Window], int]:
+    """Cut one record's token ids into windows, proving each one round-trips.
+
+    The round-trip encode is the whole reason this tool may claim the reference
+    scores the corpus's own token sequence: decoding a window to text and
+    encoding it back must return the identical ids, or the score is of a
+    different document than the one on disk.
+    """
+    ids = tok.encode(rec["prompt"], add_special_tokens=False).ids
+    windows: list[Window] = []
+    for start in range(0, max(len(ids), 1), a.max_doc_tokens):
+        window = ids[start:start + a.max_doc_tokens]
+        if not window:
+            continue
+        text = tok.decode(window)
+        if tok.encode(text, add_special_tokens=False).ids != window:
+            qc.refuse(f"{where} window at token {start} does not round-trip through "
+                      "text — the reference would score a different token sequence "
+                      "than the corpus holds")
+        windows.append(Window(prompt=text,
+                              score_from=max(len(window) - a.score_tail, 0),
+                              n_tokens=len(window),
+                              clamped=len(window) < a.score_tail,
+                              source=rec["source"] if "source" in rec else MISSING))
+    return windows, len(ids)
+
+
+def rechunk(a: argparse.Namespace, tok) -> dict:
+    """Write the re-chunked corpus and return the summary it printed."""
+    docs_in = docs_out = tokens_in = tokens_out = 0
+    longest_child = clamped = scored = 0
+    sources: dict[str, int] = {}
+    with qc.atomic_writer(a.out) as out:
+        for lineno, rec in qc.iter_jsonl(a.corpus):
+            where = f"{a.corpus}:{lineno}"
+            if not isinstance(rec.get("prompt"), str):
+                qc.refuse(f"{where} has no string 'prompt' field")
+            windows, n_parent = cut(rec, tok, a, where)
+            docs_in += 1
+            tokens_in += n_parent
+            for w in windows:
+                out.write(json.dumps(w.record(), ensure_ascii=False) + "\n")
+                docs_out += 1
+                tokens_out += w.n_tokens
+                longest_child = max(longest_child, w.n_tokens)
+                clamped += 1 if w.clamped else 0
+                scored += w.n_tokens - w.score_from
+                if "source" in rec:
+                    for cls in str(rec["source"]).split("+"):
+                        sources[cls] = sources.get(cls, 0) + 1
+    if tokens_out != tokens_in:
+        raise SystemExit(f"REFUSED: the windows hold {tokens_out} tokens and the corpus "
+                         f"has {tokens_in} — re-chunking lost or invented tokens")
+    return {
+        "corpus": a.corpus,
+        "out": a.out,
+        "tokenizer": os.path.basename(a.tokenizer_json),
+        "documents_in": docs_in,
+        "documents_out": docs_out,
+        "tokens_in": tokens_in,
+        "tokens_out": tokens_out,
+        "longest_document": longest_child,
+        "max_doc_tokens": a.max_doc_tokens,
+        "score_tail": a.score_tail,
+        "scored_positions": scored,
+        "clamped_score_from": clamped,
+        "source_documents": sources,
+    }
+
+
+def main() -> None:
+    a = parse_args()
+    validate(a)
+    print(json.dumps(rechunk(a, qc.load_tokenizer(a.tokenizer_json)), indent=1))
+
+
+if __name__ == "__main__":
+    main()

scripts/recipes/qwen4exp-qwen38-w5nl64-bf16trunk.recipe

@@ -0,0 +1,80 @@
+# qwen4exp-qwen38-w5nl64-bf16trunk.recipe — every routed expert, BOTH projections, at five bits:
+# u5 codes into libquant's 32-level w5nl table, an E4M3 scale a group of 64 under the fixed 2^-13
+# second level, rotated by the 128-wide Hadamard, chosen by GPTQ against $CALIB and swept three
+# times by coordinate descent. This is `w5nl64a8h` in the engine's served-encoding table — the top of
+# the four-bit class — applied wider than any published radiance container of this checkpoint: the
+# author's own w5 rung (`qwen4exp-w5dn64-i8-hc8m.recipe`) moves only `down`, because that rung was
+# priced as a byte-for-error trade against prefill; this campaign buys the whole rung and pays for
+# it out of the pinned host pool (+15.3 GiB of expert plane, `--host-pool-mib 61440` per rank), not
+# out of the KV pool.
+#
+# Every other line is the served container's recipe (dump it with
+# `rad-info --recipe /home/dank/models/rad/qwen3.8-next-flash-fp8-iq4r-moe.rad`), minus the rows this
+# campaign leaves at the checkpoint:
+#
+#   * the trunk's block linears, the shared expert and the hyper-connection mixers are NOT listed —
+#     dropping their i8/fp8 lines leaves them bf16, which is what the checkpoint holds. Measured bill
+#     +1.978 GiB of always-resident weight = ~131k tokens of KV off the pool.
+#   * `ssm_inz`/`ssm_out` STAY int8: the delta-net gates are the largest trunk rows (+1.9 GiB, 126k
+#     tokens) and the least sensitive per byte.
+#   * `mtp.draft_head` STAYS 2-bit and the PLE n-gram table STAYS one fixed E4M3 scale: the draft
+#     head's rung is cheap and its acceptance cost is a decode question this campaign does not touch,
+#     and bf16 for the n-gram table would pin +47.69 GiB of host RAM for a lookup.
+#
+# Protected experts: none in this file. `scripts/apply-protected-cast.sh` appends the derived set
+# (48, two per layer so each rank's 256-expert half stays even — the four-bit GEMM takes the rest of
+# a half as two equal tables by parity) from the fresh 12M-token energy/routing census, and they must
+# sit ABOVE the expert row because the first rule that matches a weight decides it.
+#
+#   CALIB=/home/dank/campaign/qwen38-w5nl64/calib \
+#     rad-convert /home/dank/models/Qwen3.8-Flash-Next \
+#       --recipe this.file --imatrix .../imatrix.gguf -o out.rad
+#
+# The arm driver (`scripts/convert-qwen38-w5nl64.sh`) generates the per-arm variants of the expert
+# row from this template — cd=3 (control), cd=6, and `act_order=1` with NO cd= (libquant refuses the
+# pair, lq_registry.cpp:105) — rather than keeping three near-duplicate recipes that can drift apart.
+#
+# The whole campaign, in the order that fits on one disk (every step runs on dankserver):
+#
+#   1. scripts/download-qwen38-bf16.sh --fetch      the vendor BF16 checkpoint, 335.3 GiB
+#   2. scripts/build-qwen38-bf16-rad.sh             the BF16 reference container, another 335.3 GiB
+#   3. one drained window, two boots:
+#        scripts/run-qwen38-bf16.sh kldref          the KLD reference recording (the zero of scale)
+#        scripts/run-qwen38-bf16.sh calib           the 12M-position calibration tap -> grams
+#   4. trash qwen38-bf16.rad                        the peak-disk law: the converts need its room
+#   5. scripts/grams-to-imatrix.py                  grams -> imatrix.gguf in the campaign dir
+#   6. scripts/convert-qwen38-w5nl64.sh             the arms, planned and billed before each one runs
+#   7. fetch the published FP8-native release, then per container:
+#        scripts/run-qwen38-bf16.sh score RAD OUT   fp8 anchor, served iq4r, each arm
+#      then scripts/kld-gate-qwen38.sh fp8.json iq4r.json cand.json
+#   8. a winner is a trio edit plus `scripts/deploy.sh dankserver --service frank-archon`; the
+#      rollback is the commit before it. If the win needs the bigger pinned plane, raise
+#      FRANK_ARCHON_HOST_POOL_MIB and FRANK_ARCHON_TTM_TARGET_MIB in the SAME commit: the preflight
+#      floor is 2xHOST_POOL + 48,824 + prefix cache + MNBT + the store, and a pool raised without
+#      the TTM target is a boot refusal that Restart=always repeats forever, invisible to deploy.sh.
+
+# PROTECTED-BEGIN — scripts/apply-protected-cast.sh splices the derived cast lines in here.
+# They MUST sit above the expert rule: the first rule whose glob matches a weight decides it, so a
+# cast line below the five-bit rule would never win. The set is derived from the campaign's own
+# 12M-token recording (`derive-protected-experts.py --target-count 48` over the fresh grams), and the
+# driver splices it into a per-arm COPY so this template stays the clean, reviewable baseline.
+# PROTECTED-END
+
+# Every routed expert, trunk and MTP layer alike, both projections, at five bits. The experts' scales
+# sit between 2^-15 and 2^-10.6 under w4nl's top level of 22 and half a binade lower under w5nl's 30
+# — inside E4M3's normal range under 2^-13 either way. The MTP layer has no recording and is rounded
+# to nearest, which libquant says on stderr; it is one layer of 49 and only ever changes drafts.
+blk.*.ffn_*_exps.*.weight            gptq table=w5nl group=64 scale=fp8_e4m3 scale2=f32 block2=*x* scale2_value=0.0001220703125 transform=fwht128 rule=search cd=3 calib=$CALIB
+
+# The delta-net's in/out gates, int8 with a bf16 scale a group of 128 searched for least error — the
+# served recipe's lines, unchanged.
+blk.*.ssm_inz.weight                 rtn codes=i8 group=128 scale=bf16 clamp=sym rule=search
+blk.*.ssm_out.weight                 rtn codes=i8 group=128 scale=bf16 clamp=sym rule=search
+
+# The MTP head's two mixing rows, E4M3 as served. They only ever change the drafts.
+mtp.fc_hidden.weight                 rtn codes=fp8_e4m3 group=128 scale=f32
+mtp.fc_embedding.weight              rtn codes=fp8_e4m3 group=128 scale=f32
+
+# The n-gram table at one fixed E4M3 scale, and the 2-bit draft head — both the served lines.
+blk.*.ple_ngram.weight               rtn codes=fp8_e4m3 block=*x* scale=bf16 rule=fixed scale_value=1.99317932128906e-4
+mtp.draft_head.weight                rtn codes=u2 zero=u8 group=128 scale=f16

scripts/run-qwen38-bf16.sh

@@ -0,0 +1,381 @@
+#!/usr/bin/env bash
+# run-qwen38-bf16.sh — RUNS ON DANKSERVER. Boot a container over the campaign's
+# ONE measuring shape for the phases that need both R9700s. The engine owns the
+# cards, so frank-archon is stopped first and restored on every exit path — the
+# autoresearch pattern: stop, never mask (the unit file in /etc/systemd/system
+# is a symlink into the checkout and mask fails on a relinked unit; the deploy
+# restores it).
+#
+#   kldref            --kld-record the reference log-probabilities: the engine
+#                     runs /home/dank/corpora/out/kld.jsonl (197 prompts, 50,432
+#                     scored positions, score tail 256) through prefill, writes
+#                     /home/dank/campaign/qwen38-w5nl64/kld-ref, and EXITS. The
+#                     model behind it is the BF16 container from
+#                     scripts/build-qwen38-bf16-rad.sh — the vendor checkpoint's
+#                     own numbers, which is what makes it the zero point.
+#   score RAD OUT     --kld-ref score ONE container against that recording and
+#                     EXIT: the FP8-native anchor, the served iq4r, and every
+#                     arm. Deliberately the SAME engine pin, the same TP, the
+#                     same step size, the same fp8 KV, --deterministic and no
+#                     speculation as kldref — KL and top-1 agreement are only
+#                     comparable across boots when everything except the weights
+#                     is identical, so this mode is one argv with --model and
+#                     the two --kld-* flags changed, never a second shape.
+#                     RAD must sit under the models dir (the container reads it
+#                     through the ro /models mount); OUT lands on a writable
+#                     mount because --kld-out F also writes F.rows beside it.
+#   calib             serve on :7770 with the calibration tap open
+#                     (RADIANCE_CALIB_DIR + RADIANCE_CALIB_TOKENS=12000000). A
+#                     separate driver — scripts/calib-push.py --port 7770
+#                     --container qwen38-bf16 --corpus
+#                     /home/dank/corpora/out/calib.jsonl — pushes the corpus; at
+#                     12M pooled positions the engine writes the Grams and the
+#                     tap switches itself off (calib-push prints TAP_DONE). Stop
+#                     this script after that; the trap brings frank-archon back.
+#
+# Shape: the vendor's bf16 calibration lines — expert_tiered placement with the
+# weights disk tier, deterministic (the resident set pinned to the loader's plan,
+# so a recorded reference and a scored candidate see the same one), no
+# speculation, fp8 KV, a 32,768-token window, the PLE n-gram table pinned to RAM,
+# and the production chat template rather than the one baked into the container —
+# every scored container is asked the same tokenised questions the reference
+# answered. The window the flag spells is 32,768; the pool this payload's boot
+# actually gets is 7,436 tokens, so kld.jsonl is re-chunked by
+# scripts/rechunk-kld-corpus.py into documents of at most 7,168 tokens — the
+# widest one the reference can hold. The kldref gate below re-checks the file
+# against the declared window, and the re-chunker is what keeps that honest.
+#
+# NO --vram-kv-mib: it was REMOVED at 1.3.0 and naming it is a boot refusal, not
+# a no-op — verified on the pinned image 2026-10-27: "E --vram-kv-mib was
+# removed: the card is split between the weights and the cache from what the
+# model needs." The resolver derives the split from --host-pool-mib,
+# --gpu-headroom-mib and the activation arena; the rig inherits the first two from
+# frank-archon.env, the file that owns them. On THIS payload the host pool is not
+# the cache's supplier: the boot lands in vram_budget.cpp's `no lender` branch,
+# where the experts keep their plan-fixed 25.29 GiB and the cache gets the residue.
+# Measured twice — 12,288 and 49,152 MiB of host pool both printed the same
+# "kv cache 271.25 MiB ... 7,436"; only --gpu-headroom-mib moved anything
+# (768 -> 96 grew vram_weights 29.41 -> 30.06 GiB). The supplier the source names
+# is the arena: vram_budget.cpp:117, "lower --max-num-batched-tokens (the arena
+# scales with it)" — which is what the step size below now does.
+#
+# The pool, not the window, decides what the recorder accepts: it refuses any
+# document longer than the pool, so the 32,768-token window was decorative while the
+# cache held 7,436 — "E kld: document 196 is 8507 tokens and the KV pool holds
+# 7436, so it can never be scored" on all 197 records, exit 1. The longest record
+# is 10,554 tokens by the engine's own count (chars/3.6 for this file, not the
+# chars/4.97 this repo measured on the K3 corpus).
+#
+# The step size is ONE value for the recording and every scoring pass, and it is
+# the value frank-archon.env owns (FRANK_ARCHON_MAX_BATCHED_TOKENS, 2,048): the
+# quantised expert FILE tiers (the served iq4r, the arms) stream only at
+# MNBT<=2048 and refuse the widened form above it, and the arena a step costs the
+# card comes straight out of the cache — 1.08 GiB at a 2,048-token step against
+# 504.39 MiB at 1,024. The corpora are cut to the window the boot ledger reports,
+# which is what the pool raise is for (frank-archon.env: HOST_POOL_MIB); a narrow
+# step was never the fix, it was the symptom's disguise.
+#
+# usage: scripts/run-qwen38-bf16.sh kldref|calib|score RAD OUT [--dry-run] [--image REF]
+#   (RAD and OUT are score's two positionals: RAD is a container under the models
+#    dir, OUT the report path whose directory is created if missing)
+#   --dry-run   print the exact `podman run` argv, one shell-quoted argument a
+#               line, and exit 0: the service is NOT stopped, nothing is
+#               mounted, nothing is written — the offline test seam. It still
+#               validates the argv's own shape (paths through the /models mount,
+#               a step size that is a number), because an argv that could not
+#               boot is not worth printing.
+#   --image REF override the digest pin (a probe boot, or the test seam)
+#
+# knobs: FRANK_QWEN38_MODELS (the dir mounted at /models), FRANK_QWEN38_RAD (the
+#        bf16 container, kldref only), FRANK_QWEN38_CAMPAIGN (holds kld-ref/ and
+#        calib/), FRANK_QWEN38_KLD_CORPUS, FRANK_QWEN38_TPL (the template copy
+#        the container reads through /models), FRANK_QWEN38_LOG_DIR, and the step
+#        and slot counts inherited as FRANK_ARCHON_MAX_BATCHED_TOKENS /
+#        FRANK_ARCHON_MAX_SEQS — no per-mode literals (the audit law: a mode that
+#        carries its own step measures a shape nothing serves) —
+#        and FRANK_QWEN38_MAX_MODEL_LEN — the window every mode boots at (32,768;
+#        see the corpus census above, and raise it together with the corpus).
+# kldref refuses (exit 2) when the longest record of the corpus it is about to
+# read is longer than MAX_MODEL_LEN x 3 characters — chars/3 being the
+# pessimistic token:char ratio, so the script says no before the engine finds out
+# inside a drained window, after the checkpoint work is already done. score
+# refuses when the reference dir is absent, when RAD is not on disk or not under
+# the models mount, or when OUT already exists: the trash law means a second
+# score over the same name is a deliberate act, and two numbers in one file is
+# how a campaign loses its own history.
+# Engine stdout goes to $LOG_DIR/qwen38_bf16_<mode>.log — the boot ledger is the
+# record of what the resolver actually gave the cards; the journal never sees it.
+# exit: the engine's code; 2 = refused before the service was touched
+set -uo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck disable=SC1091
+source "$SCRIPT_DIR/frank-archon.env"
+IMAGE="${FRANK_ARCHON_IMAGE:?FRANK_ARCHON_IMAGE must name the radiance image}"
+
+MODE=""
+POS=()
+DRY=0
+while [ $# -gt 0 ]; do
+    case "$1" in
+        kldref|calib|score) MODE="$1" ;;
+        --dry-run)          DRY=1 ;;
+        --image)            [ "$#" -ge 2 ] || { echo "--image needs a reference" >&2; exit 2; }
+                            IMAGE="$2"; shift ;;
+        *)
+            # score's two positional arguments, and nothing else may be bare.
+            if [ "$MODE" = score ] && [ "${#POS[@]}" -lt 2 ]; then
+                POS+=("$1")
+            else
+                echo "usage: ${0##*/} kldref|calib|score RAD OUT [--dry-run] [--image REF]  (unknown argument: $1)" >&2
+                exit 2
+            fi ;;
+    esac
+    shift
+done
+if [ -z "$MODE" ]; then
+    echo "usage: ${0##*/} kldref|calib|score RAD OUT [--dry-run] [--image REF]  (no mode given)" >&2
+    exit 2
+fi
+if [ "$MODE" = score ] && [ "${#POS[@]}" -ne 2 ]; then
+    echo "usage: ${0##*/} score RAD OUT  — RAD is the container to score, OUT the report to write (got ${#POS[@]} argument(s))" >&2
+    exit 2
+fi
+
+MODELS="${FRANK_QWEN38_MODELS:-/home/dank/models}"
+CAMPAIGN="${FRANK_QWEN38_CAMPAIGN:-/home/dank/campaign/qwen38-w5nl64}"
+KLD_CORPUS="${FRANK_QWEN38_KLD_CORPUS:-/home/dank/corpora/out/kld.jsonl}"
+RAD="${FRANK_QWEN38_RAD:-$MODELS/rad/qwen38-bf16.rad}"
+TPL="${FRANK_QWEN38_TPL:-$MODELS/tpl.jinja}"
+TEMPLATE="$SCRIPT_DIR/qwen38-froggeric-v22.5.jinja"
+LOG_DIR="${FRANK_QWEN38_LOG_DIR:-/home/dank/logs}"
+LOG="$LOG_DIR/qwen38_bf16_${MODE}.log"
+KLD_REF_DIR="$CAMPAIGN/kld-ref"
+CALIB_DIR="$CAMPAIGN/calib"
+C=qwen38-bf16
+SERVICE=frank-archon
+# The card split, taken from the file that owns it instead of a private pair:
+# --host-pool-mib also funds the KV cache (see the header), so hardcoding it
+# here once starved the recorder. The `:?` guards keep an empty env fatal.
+HOST_POOL_MIB="${FRANK_ARCHON_HOST_POOL_MIB:?FRANK_ARCHON_HOST_POOL_MIB must be set}"
+GPU_HEADROOM_MIB="${FRANK_ARCHON_GPU_HEADROOM_MIB:?FRANK_ARCHON_GPU_HEADROOM_MIB must be set}"
+# The slot count, from the same file that owns the card split: production runs
+# four slots and every mode measures at production's geometry. A per-mode
+# literal here is what let calib ask for eight slots and then starve its own
+# cache. The `:?` guard keeps an empty env fatal, as for the card split.
+MAX_SEQS="${FRANK_ARCHON_MAX_SEQS:?FRANK_ARCHON_MAX_SEQS must be set}"
+if ! [[ "$MAX_SEQS" =~ ^[0-9]+$ ]]; then
+    echo "REFUSED: FRANK_ARCHON_MAX_SEQS must be a slot count (got: $MAX_SEQS)" >&2
+    exit 2
+fi
+
+# ONE step size for every mode, quoted from the file that owns it — the audit
+# law for a radiance rig is to inherit the proven number, not to carry a
+# campaign-private value: production's FRANK_ARCHON_MAX_BATCHED_TOKENS. The
+# 1,024 default this script carried was PR #80's answer to a starved cache;
+# production moved to its widest legal step (2,048) on 2026-10-29 and the rig
+# follows. The pool raise that shipped with it (66,560 a rank) bought this
+# container 1.26 MiB of cache (`vram_kv 269.99 -> 271.25 MiB`, window still
+# 7,436 tokens — the 95.37 GiB n-gram table's claim decides the rig's cache,
+# not the pool) and was folded back the same day. The corpora stay cut to the
+# window the boot ledger reports, never the other way round.
+MNBT="${FRANK_ARCHON_MAX_BATCHED_TOKENS:?FRANK_ARCHON_MAX_BATCHED_TOKENS must be set}"
+if ! [[ "$MNBT" =~ ^[0-9]+$ ]]; then
+    echo "REFUSED: FRANK_ARCHON_MAX_BATCHED_TOKENS must be a token count (got: $MNBT)" >&2
+    exit 2
+fi
+
+# The window every mode boots at. Over-length is a REFUSAL, not a truncation (the
+# env file says so for production), so this is the number the corpus must fit in.
+MAX_MODEL_LEN="${FRANK_QWEN38_MAX_MODEL_LEN:-32768}"
+if ! [[ "$MAX_MODEL_LEN" =~ ^[0-9]+$ ]]; then
+    echo "REFUSED: FRANK_QWEN38_MAX_MODEL_LEN must be a token count (got: $MAX_MODEL_LEN)" >&2
+    exit 2
+fi
+
+# Every container this campaign boots is read through the ro /models mount, so
+# the host path must live under it; the container-side spelling is what goes
+# into the argv. Same rule for the container a score pass opens.
+under_models() {
+    case "$1" in
+        "$MODELS"/*) printf '/models/%s' "${1#"$MODELS"/}" ;;
+        *) return 1 ;;
+    esac
+}
+
+# same_dir A B — the two name one directory, judged only when BOTH exist: a dry
+# run has no fixtures on disk, and two absent paths are not the same place.
+same_dir() {
+    [ -d "$1" ] && [ -d "$2" ] && [ "$(cd "$1" && pwd)" = "$(cd "$2" && pwd)" ]
+}
+
+if [ "$MODE" = score ]; then
+    SCORE_RAD="${POS[0]}"
+    SCORE_OUT="${POS[1]}"
+    OUT_DIR="$(dirname "$SCORE_OUT")"
+    MODEL_IN="$(under_models "$SCORE_RAD")" || {
+        echo "REFUSED: container to score $SCORE_RAD is not under the mounted models dir $MODELS — the engine cannot read it" >&2
+        exit 2
+    }
+else
+    MODEL_IN="$(under_models "$RAD")" || {
+        echo "REFUSED: reference container $RAD is not under the mounted models dir $MODELS — the engine cannot read it" >&2
+        exit 2
+    }
+fi
+
+# The measuring shape. Identical for kldref and score by construction — this
+# array is the only place the campaign's KL numbers are defined.
+ARGS=(--tp 2 --placement expert_tiered --weights-disk-tier
+      --host-pool-mib "$HOST_POOL_MIB" --gpu-headroom-mib "$GPU_HEADROOM_MIB"
+      --deterministic --num-speculative-tokens 0
+      --kv-cache-dtype fp8 --max-model-len "$MAX_MODEL_LEN"
+      --ngram-placement ram
+      --override-chat-template /models/tpl.jinja)
+MOUNTS=(-v "$MODELS:/models:ro")
+TAPENV=()
+case "$MODE" in
+  kldref)
+    # Recording is prefill-only over four slots at the campaign's single step
+    # size, which is frank-archon.env's FRANK_ARCHON_MAX_BATCHED_TOKENS (2,048) —
+    # see the header: the file tier's ceiling and the slot count both come from
+    # the file that owns them. Corpus read-only, record dir rw.
+    ARGS+=(--model "$MODEL_IN"
+           --kld-record /data/kld-ref --kld-corpus /data/kld.jsonl
+           --max-num-seqs "$MAX_SEQS" --max-num-batched-tokens "$MNBT")
+    MOUNTS+=(-v "$KLD_CORPUS:/data/kld.jsonl:ro"
+             -v "$KLD_REF_DIR:/data/kld-ref")
+    ;;
+  score)
+    # The same argv with three words changed: which container, and that this
+    # time the engine reads a recording and writes a report instead of the
+    # reverse. The reference dir mounts READ-ONLY — a scoring pass must not be
+    # able to touch the zero point — and the report gets its own writable bind.
+    if [ "$OUT_DIR" = "$KLD_REF_DIR" ] || same_dir "$OUT_DIR" "$KLD_REF_DIR" \
+       || [ "$(realpath -m "$OUT_DIR")" = "$(realpath -m "$KLD_REF_DIR")" ]; then
+        echo "REFUSED: score output $SCORE_OUT is inside the reference dir $KLD_REF_DIR, which this mode mounts read-only" >&2
+        exit 2
+    fi
+    ARGS+=(--model "$MODEL_IN"
+           --kld-ref /data/kld-ref --kld-out "/data/out/$(basename "$SCORE_OUT")"
+           --max-num-seqs "$MAX_SEQS" --max-num-batched-tokens "$MNBT")
+    MOUNTS+=(-v "$KLD_REF_DIR:/data/kld-ref:ro"
+             -v "$OUT_DIR:/data/out")
+    ;;
+  calib)
+    # Calibration rides the shared step like every other mode. The old
+    # exemption — eight slots at MNBT 65,536 for "free throughput", because
+    # "a disk-tier step costs the same at 1 token as at 64k" — is false: the
+    # step's activation arena is billed on the card, not on the disk. The
+    # engine's own ledger for this container: at MNBT 1,024 the arena is
+    # 504 MiB and the card claims 30.87 GiB (weights 28.90 GiB of it); at
+    # 65,536 the arena is 10.65 GiB (fixed region 1.25 GiB), the claim falls
+    # to 16.85 GiB, the experts shrink to 10.98 GiB and the KV to 271 MiB —
+    # one slot's worth of cache for eight slots, and the boot dies at
+    # "startup stopped: out of memory" (measured 2026-10-29). A wide step
+    # buys throughput with the expert slab, so price it like any other
+    # VRAM knob. The slots follow frank-archon.env's FRANK_ARCHON_MAX_SEQS
+    # through MAX_SEQS, exactly as kldref and score do.
+    ARGS+=(--model "$MODEL_IN" --port 7770
+           --max-num-seqs "$MAX_SEQS" --max-num-batched-tokens "$MNBT")
+    # The tap is only real if this directory exists and the engine can write it:
+    # without the check a typo'd CALIB_DIR auto-creates a root-owned empty dir in
+    # whatever path was given, and the run burns hours serving prompts into a tap
+    # nobody reads. RADIANCE_CALIB_TOKENS is the whole corpus' floor, not a round's.
+    [ "$DRY" = 1 ] || [ -w "$CALIB_DIR" ] || {
+        echo "REFUSED: calib tap dir $CALIB_DIR is not writable (mkdir it, chown it, then re-run)" >&2
+        exit 2
+    }
+    MOUNTS+=(-v "$CALIB_DIR:/data/calib")
+    TAPENV=(-e RADIANCE_CALIB_DIR=/data/calib
+            -e "RADIANCE_CALIB_TOKENS=${FRANK_QWEN38_CALIB_TOKENS:-12000000}")
+    ;;
+esac
+
+CMD=(podman run --rm --name "$C"
+     --network host --init
+     --security-opt seccomp=unconfined
+     --ulimit memlock=-1:-1
+     --device /dev/kfd --device /dev/dri
+     "${MOUNTS[@]}" "${TAPENV[@]}"
+     "$IMAGE" "${ARGS[@]}")
+
+# ---- gate: the window must hold the corpus (kldref alone can meet it) --------
+# score reads a recording instead of a corpus, and every arm declares at the
+# checkpoint's training context, so neither can meet a sequence too long to boot.
+# Measured on the raw JSON line — the pessimistic direction, and the same figure
+# the census in the header quotes. It runs on a dry run too, because a refusal
+# this cheap should never have to wait for the drained window to be discovered.
+if [ "$MODE" = kldref ] && [ -f "$KLD_CORPUS" ]; then
+    read -r REC_NO REC_CHARS < <(awk '{ if (length($0) > best) { best = length($0); where = NR } } END { print where + 0, best + 0 }' "$KLD_CORPUS")
+    LIMIT_CHARS=$(( MAX_MODEL_LEN * 3 ))
+    if [ "$REC_CHARS" -gt "$LIMIT_CHARS" ]; then
+        echo "REFUSED: record $REC_NO of $KLD_CORPUS is $REC_CHARS chars, past the $LIMIT_CHARS a $MAX_MODEL_LEN-token window promises at the pessimistic chars/3 — raise FRANK_QWEN38_MAX_MODEL_LEN, and the container's declared --max-ctx with it, before booting the reference" >&2
+        exit 2
+    fi
+    echo "corpus fits: longest record $REC_CHARS chars (number $REC_NO) inside the $MAX_MODEL_LEN-token window (limit $LIMIT_CHARS chars)"
+fi
+
+if [ "$DRY" = 1 ]; then
+    echo "dry run: $MODE — the production unit is left running, nothing is mounted, nothing is written"
+    printf '%q\n' "${CMD[@]}"
+    exit 0
+fi
+
+# ---- gates that only a real run needs ---------------------------------------
+if [ "$MODE" = score ]; then
+    if [ ! -d "$KLD_REF_DIR" ]; then
+        echo "REFUSED: no KLD reference at $KLD_REF_DIR — record it first in a drained window: scripts/run-qwen38-bf16.sh kldref" >&2
+        exit 2
+    fi
+    if [ ! -f "$SCORE_RAD" ]; then
+        echo "REFUSED: no container to score at $SCORE_RAD" >&2
+        exit 2
+    fi
+    if [ -e "$SCORE_OUT" ]; then
+        echo "REFUSED: $SCORE_OUT already exists — one report per name; move the old one to trash before re-scoring" >&2
+        exit 2
+    fi
+    mkdir -p "$OUT_DIR"
+else
+    if [ ! -f "$RAD" ]; then
+        echo "REFUSED: no reference container at $RAD — build it first: scripts/build-qwen38-bf16-rad.sh" >&2
+        exit 2
+    fi
+    [ "$MODE" = kldref ] && [ ! -f "$KLD_CORPUS" ] && {
+        echo "REFUSED: no KLD corpus at $KLD_CORPUS — the record would be empty" >&2
+        exit 2
+    }
+fi
+if [ ! -f "$TEMPLATE" ]; then
+    echo "REFUSED: no chat template at $TEMPLATE" >&2
+    exit 2
+fi
+mkdir -p "$LOG_DIR"
+# The prod template, staged where the ro /models mount reaches it: a reference
+# recorded with the container's baked template scores a different tokenisation
+# than the arms served with froggeric's, and the KL would be measuring that.
+cp -f "$TEMPLATE" "$TPL" || {
+    echo "REFUSED: cannot stage the chat template at $TPL (the container reads it through /models)" >&2
+    exit 2
+}
+[ "$MODE" = kldref ] && mkdir -p "$KLD_REF_DIR"
+[ "$MODE" = calib ]  && mkdir -p "$CALIB_DIR"
+
+# Stop the campaign container BEFORE handing the cards back: a killed run leaves
+# its conmon alive (--rm only fires when podman itself exits), and production
+# then boots beside a container still holding the GPUs — measured 2026-10-29,
+# where the service reported `active` while its engine starved on the rig's VRAM.
+restore() {
+    podman rm -f "$C" >/dev/null 2>&1 || true
+    sudo systemctl start "$SERVICE" >/dev/null 2>&1 || true
+}
+trap restore EXIT
+echo "run-qwen38-bf16 $MODE: stopping $SERVICE ($(date -Is)); log: $LOG"
+sudo systemctl stop "$SERVICE" >/dev/null 2>&1 || true
+podman rm -f "$C" >/dev/null 2>&1 || true
+
+"${CMD[@]}" 2>&1 | tee "$LOG"
+rc=${PIPESTATUS[0]}
+echo "run-qwen38-bf16 $MODE exited rc=$rc; $SERVICE restored; log: $LOG"
+exit "$rc"

scripts/serve-frank-archon.sh

@@ -15,18 +15,21 @@
 # log states every budget before anything is allocated (weights vs KV
 # split, the expert host pool's coverage of the worst case, the PLE pin,
 # the P2P answer per pair) — read it after every resize.
-# Deployed shape (2026-10-19, radiance 1.8.1): THREE decode slots x 200,000
-# tokens, fp8 KV, 44 GiB/rank pinned expert pool, MTP depth 2, prefix cache in
-# pinned host RAM, PLE pinned in RAM. The per-card split between the expert slab
-# and the KV pool is NO LONGER an operator number — 1.3.0 removed the VRAM pair
-# and the budget resolver derives it from headroom, the cache bound and the host
-# pool, so the slab size and the pool's token count are LEDGER lines: after every
-# boot read them out of the log and check the pool still backs 3 x 200,000.
+# Deployed shape (2026-10-20, radiance 1.8.1): FOUR decode slots x 200,000 tokens over a
+# >= 700,000-token fp8 KV pool, 48 GiB/rank pinned expert pool, MTP depth 2, prefix cache
+# in pinned host RAM, PLE pinned in RAM. The per-card split between the expert slab and the KV
+# pool is NO LONGER an operator number — 1.3.0 removed the VRAM pair and the budget
+# resolver derives it from headroom, the cache bound and the host pool, so the slab
+# size and the pool's token count are LEDGER lines. After every boot read them, plus
+# the two lines that size a prefill step — "activation arena: ... lends ... while
+# steps are at most N tokens" (the arena levels the expert slab borrows) and
+# "prefill staging: ... a step of more than N tokens ..." (the chunk size below which
+# pooled experts are read synchronously) — and the cache's session backing.
 #
 # The root unit (scripts/frank-archon.service, User=dank,
-# LimitMEMLOCK=infinity) grants the pin budget: 2 x 44 GiB expert pools +
-# the 47.7 GiB PLE table + 8 GiB prefix host tier — ~147 GiB of pinned
-# pages, which is ALSO why this script refuses to start when ttm's
+# LimitMEMLOCK=infinity) grants the pin budget: 2 x 48 GiB expert pools + the 47.7 GiB PLE
+# table + 8 GiB prefix host tier + the checkpoint store (slots x 112 MiB) — ~159 GiB of
+# pinned pages, which is ALSO why this script refuses to start when ttm's
 # pages_limit/pages_max cap is under FRANK_ARCHON_TTM_MIN_MIB (see below).
 set -euo pipefail
 
@@ -45,7 +48,7 @@ set +a
 : "${FRANK_ARCHON_IMAGE:?FRANK_ARCHON_IMAGE must name the radiance image}"
 : "${FRANK_ARCHON_MODEL_DIR:?FRANK_ARCHON_MODEL_DIR must name the .rad dir}"
 : "${FRANK_ARCHON_MODEL_FILE:?FRANK_ARCHON_MODEL_FILE must name the .rad file}"
-: "${FRANK_ARCHON_STATE_DIR:?FRANK_ARCHON_STATE_DIR must name the /data state dir}"
+: "${FRANK_ARCHON_STATE_DIR:?FRANK_ARCHON_STATE_DIR must name the host dir holding the rad-tune cache}"
 : "${FRANK_ARCHON_CONTAINER:?FRANK_ARCHON_CONTAINER must name the container}"
 : "${FRANK_ARCHON_SERVED_NAME:?FRANK_ARCHON_SERVED_NAME must name the alias}"
 : "${FRANK_ARCHON_PORT:?FRANK_ARCHON_PORT must be the port}"

scripts/serve-frank-dragoon.sh

@@ -27,6 +27,11 @@
 # the flash-server line reads it; it ships as a container; the root unit
 # keeps LimitMEMLOCK=infinity for parity and to outlive the login session,
 # exactly like frank-archon's.
+# Since 2026-10-19 the container also carries the XDNA2 NPU lane
+# (HALOGEN_NPU_MODELS): the vendor's precompiled AIE programs for the models
+# named there run on the NPU inside THIS container and answer /v1/embeddings,
+# beside the Flash model, on the same port. Opt-in — the variable empty is the
+# pre-lane endpoint, byte for byte.
 set -euo pipefail
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
@@ -115,6 +120,128 @@ if [ ! -e "$DEV_KFD" ] || [ ! -d "$DEV_DRI" ]; then
     echo "frank-dragoon: $DEV_KFD or $DEV_DRI missing — no gfx1151 to serve on" >&2
     exit 1
 fi
+
+# --- NPU lane (XDNA2), opt-in via HALOGEN_NPU_MODELS ------------------------
+# Empty = the endpoint exactly as it ran before the lane existed: no device, no
+# extra mounts, no gate below. Set = three host preconditions, each refused BY
+# NAME (the 2026-10-01 law: the serve gate and the deployer gate must agree):
+#   1. the staged model files under $FRANK_DRAGOON_NPU_DIR — a path that MUST
+#      live INSIDE $FRANK_DRAGOON_MODEL_DIR, because the container's only
+#      handle on them is the read-only /models mount. A nested bind at
+#      /models/npu cannot work: runc has to mkdir its mountpoint and the parent
+#      bind is ro (`mkdirat .../merged/models/npu: read-only file system`,
+#      measured 2026-10-19), and the image ships no /models at all for it to
+#      land on. `$MODEL_DIR/npu/<id>` is visible at /models/npu/<id> through
+#      the existing mount, which is also where the vendor's catalog expects it.
+#      The engine re-checks size+sha256 against that catalog at boot; it cannot
+#      fetch anything here because /models is read-only and HALOGEN_DOWNLOAD
+#      stays unset — no outbound connection at boot),
+#   2. the distro XRT's three libraries, each mounted THREE times: where the
+#      image looks for XRT (/opt/xilinx/xrt/lib), at their own path (the
+#      libraries find each other there), and at /opt/xilinx/lib/<multiarch>
+#      — the NPU child searches that third prefix too, and since the host's
+#      libxrt2 was reconfigured 2026-10-20 it is the ONLY prefix the child
+#      names: omitting it crashes the lane with `No such library
+#      '/opt/xilinx/lib/x86_64-linux-gnu/libxrt_core.so.2'` and the engine
+#      supervisor takes the dead lane down on the whole container (measured
+#      2026-10-21: 88-restart boot loop). Real files only — an /opt/xilinx/xrt
+#      of symlinks into the system dir dangles inside the container, which the
+#      vendor calls out explicitly),
+#   3. the GPU fabric clock HELD: on Strix Halo the iGPU and the NPU co-running
+#      hang the machine while FCLK changes speed, and the engine refuses to
+#      start when it moves — it cannot read host sysfs from inside the
+#      container, so the proof lives here, checked exactly the way the vendor's
+#      `halogen-fabric-clock status` checks it.
+NPU_ARGS=()
+NPU_MODELS="${HALOGEN_NPU_MODELS:-}"
+if [ -n "$NPU_MODELS" ]; then
+    DEV_ACCEL="${FRANK_DRAGOON_DEV_ACCEL:-/dev/accel/accel0}"
+    NPU_DIR="${FRANK_DRAGOON_NPU_DIR:?HALOGEN_NPU_MODELS is set, so FRANK_DRAGOON_NPU_DIR must name the staged model dir}"
+    XRT_DIR="${FRANK_DRAGOON_XRT_DIR:-/usr/lib/x86_64-linux-gnu}"
+    SYSFS="${FRANK_DRAGOON_SYSFS:-/sys}"
+    # The lane's files have exactly one door into the container: the read-only
+    # payload mount. A staging dir OUTSIDE it would need a nested bind whose
+    # mountpoint runc cannot create through that read-only parent, so refuse the
+    # shape by name here rather than let runc die at container init (2026-10-19).
+    case "$NPU_DIR/" in
+        "$FRANK_DRAGOON_MODEL_DIR"/*) ;;
+        *) echo "frank-dragoon: FRANK_DRAGOON_NPU_DIR=$NPU_DIR is outside the payload dir $FRANK_DRAGOON_MODEL_DIR — the lane's files reach the container only through the read-only /models mount; move the staging dir inside it" >&2
+           exit 1 ;;
+    esac
+    if [ ! -e "$DEV_ACCEL" ]; then
+        echo "frank-dragoon: $DEV_ACCEL missing — the NPU lane needs the amdxdna node (is iommu=pt still on the boot line?)" >&2
+        exit 1
+    fi
+    # Existence is not access. This endpoint runs rootless, so the container's
+    # namespace maps exactly one uid/gid (dank) and a root:render 0660 node reads
+    # `nobody:nogroup` inside it — the engine then dies naming the node itself
+    # (measured 2026-10-19). --group-add keep-groups cannot help: an unmapped gid
+    # cannot be granted into a namespace that does not map it, verified with and
+    # without the flag from a shell already in `render`. The door is the udev mode.
+    # NB: `[ -o FILE ]` is NOT "other-writable" — it means "exists", and `-o` is
+    # also the OR operator inside test — so the permission bit is read directly.
+    if [ $(( 8#$(stat -c '%a' "$DEV_ACCEL") & 8#2 )) -eq 0 ]; then
+        echo "frank-dragoon: $DEV_ACCEL is $(stat -c '%a %U:%G' "$DEV_ACCEL") — a rootless container cannot open it; install dankclaw/udev/98-halogen-npu-access.rules and re-trigger udev (sudo udevadm control --reload-rules && sudo udevadm trigger --sysname-match=accel0)" >&2
+        exit 1
+    fi
+    for M in ${NPU_MODELS//,/ }; do
+        if [ ! -d "$NPU_DIR/$M" ]; then
+            echo "frank-dragoon: NPU model $M not staged in $NPU_DIR;" >&2
+            echo "  fetch it: bash scripts/download-frank-dragoon-npu.sh" >&2
+            exit 1
+        fi
+    done
+    for L in libxrt_coreutil.so.2 libxrt_core.so.2 libxrt_driver_xdna.so.2; do
+        if [ ! -e "$XRT_DIR/$L" ]; then
+            echo "frank-dragoon: XRT NPU library $XRT_DIR/$L missing — the NPU lane cannot load (Ubuntu libxrt2 + libxrt-npu2)" >&2
+            exit 1
+        fi
+        REAL="$(readlink -f "$XRT_DIR/$L")"
+        MULTIARCH="${XRT_DIR##*/}"
+        NPU_ARGS+=(-v "$REAL:/opt/xilinx/xrt/lib/$L:ro" -v "$REAL:$XRT_DIR/$L:ro"
+                   -v "$REAL:/opt/xilinx/lib/$MULTIARCH/$L:ro")
+    done
+    HELD=0
+    for D in "$SYSFS"/class/drm/card*/device; do
+        [ -e "$D/pp_dpm_fclk" ] || continue
+        [ -e "$D/power_dpm_force_performance_level" ] || continue
+        PERF="$(cat "$D/power_dpm_force_performance_level" 2>/dev/null || true)"
+        TOP="$(grep . "$D/pp_dpm_fclk" | tail -n 1)"
+        if [ "$PERF" = high ] || { [ "$PERF" = manual ] \
+                && [ "$(grep -c '\*' "$D/pp_dpm_fclk")" = 1 ] && [ "${TOP%\*}" != "$TOP" ]; }; then
+            HELD=1
+        else
+            echo "frank-dragoon: fabric clock at $D is '$PERF', not held — the NPU lane refuses to start (GPU+NPU together need FCLK pinned)" >&2
+            echo "  hold it: sudo halogen-fabric-clock hold" >&2
+            exit 1
+        fi
+    done
+    if [ "$HELD" = 0 ]; then
+        echo "frank-dragoon: no amdgpu device with a fabric-clock control under $SYSFS/class/drm — cannot prove FCLK is held" >&2
+        exit 1
+    fi
+    NPU_ARGS+=(--device "$DEV_ACCEL" \
+               -e HALOGEN_NPU_MODELS="$NPU_MODELS")
+    echo "frank-dragoon: NPU lane armed: $NPU_MODELS on $DEV_ACCEL (fabric clock held)" >&2
+fi
+
+# Container network. Empty = podman's rootless default (`pasta`), which is a
+# private netns and CANNOT be joined by anything else: podman refuses a second
+# network while the primary is pasta ("cannot set multiple networks without
+# bridge network mode"), the endpoint's published port answers 200 on the host
+# and on the LAN but is REFUSED from a dankclaw_default container (measured
+# 2026-10-19), and `host.containers.internal:7770` answers 200 yet resolves to
+# 169.254.1.2 — link-local, which open-notebook's URL guard refuses to store.
+# So an endpoint on pasta has no address an app container can use; naming the
+# app bridge here is the only shape that lets open-notebook dial
+# http://frank-dragoon-halogen:8731 for the NPU endpoints. It does not widen
+# the surface: the engine's unauthenticated 8730 is bound to the container's
+# OWN loopback (/proc/net/tcp: 127.0.0.1:8730 vs 0.0.0.0:8731, checked the same
+# day), so only the API port is reachable by name.
+NET_ARGS=()
+if [ -n "${FRANK_DRAGOON_NETWORK:-}" ]; then
+    NET_ARGS=(--network "$FRANK_DRAGOON_NETWORK")
+fi
 # Host-RAM preflight — the engine's pin gate, checked BEFORE podman run.
 # The engine refuses to pin when MemAvailable is below the checkpoint plus
 # a 16 GiB floor: pinned pages cannot be swapped, and under the floor the
@@ -189,6 +316,8 @@ podman run --name "$FRANK_DRAGOON_CONTAINER" \
   ${HALOGEN_WEIGHTS_LOCK:+-e HALOGEN_WEIGHTS_LOCK="$HALOGEN_WEIGHTS_LOCK"} \
   -v "$FRANK_DRAGOON_MODEL_DIR:/models:ro" \
   -v "$FRANK_DRAGOON_MODEL_DIR/tokenizer:/tokenizer:ro" \
+  "${NET_ARGS[@]}" \
+  "${NPU_ARGS[@]}" \
   "$FRANK_DRAGOON_IMAGE" \
   > "$LOG" 2>&1
 

scripts/serve-frank-zealot.sh

@@ -33,6 +33,19 @@
 # what gives this endpoint eyes; MMPROJ_FILE="" is the documented text-only
 # opt-out.
 #
+# A refusal-direction adapter rides on top of the pack (Frank, 2026-10-19):
+# AtomicChat's rank-1 LoRA, applied at load by --lora-scaled. It is an edit
+# inside the compute graph, not a second model — B = -r (the refusal direction),
+# A built from the base pack's folded input basis, every transformer layer, the
+# embedding deliberately untouched because an embedding LoRA crashes this fork's
+# graph. The card verified it on prism-b10777-e3de715 — the build pinned here —
+# and says older forks refuse the pack outright (`unsupported
+# prism.hadamard.version: 2`), which makes the runtime lock doubly load-bearing.
+# Its own metadata names the PTQ1_0 packing as the pack the direction was fitted
+# against, so what proves the effect is a refusal probe against the live
+# endpoint, not the metadata and not the card's table. LORA_FILE="" drops the
+# flag and the endpoint is the plain pack again.
+#
 # Speculative decoding ships ON (Frank, 2026-10-19). The head is IN the file and
 # accepts well (0.798/0.617 per position, mean length 2.41, measured 2026-10-18);
 # what made it lose that evening was the bill, not the drafts — the draft context
@@ -136,6 +149,13 @@ fi
 # Vision projector. No colon on purpose: an explicitly empty value means
 # "text-only, on purpose" and must NOT be replaced by the default path.
 : "${MMPROJ_FILE=/home/dank/models/Bonsai2-9B-MTP/Ternary-Bonsai-2-9B-mmproj-Q8_0.gguf}"
+# Refusal adapter. No colon on purpose, the same convention as MMPROJ_FILE: an
+# explicitly empty LORA_FILE is the documented opt-out (the plain pack again)
+# and must NOT be replaced by the default path. The scale travels INSIDE the
+# same argv token as the file, so LORA_SCALE only matters while LORA_FILE names
+# something; 0 is the card's "switch it off without touching the file" value.
+: "${LORA_FILE=/home/dank/models/Bonsai2-9B-MTP/Ternary-Bonsai-2-9B-Uncensored-LoRA.gguf}"
+: "${LORA_SCALE:=1}"
 
 # Fail loudly rather than half-loading: a missing file is a download that
 # has not finished, and Restart=always would turn it into a crash loop that
@@ -149,6 +169,17 @@ if [[ -n "$MMPROJ_FILE" ]]; then
     EXTRA_ARGS+=(--mmproj "$MMPROJ_FILE")
 fi
 
+# The adapter reaches the engine as ONE token — --lora-scaled <file>:<scale> —
+# so a scale can never arrive without its file. It is applied once, at load;
+# nothing here hot-swaps it (--lora-init-without-apply plus POST /lora-adapters
+# is that shape, and a process holding three conversations is not the place to
+# re-parameterise weights mid-flight). A missing file is a fetch that never
+# finished, so refuse rather than let Restart=always loop on it.
+if [[ -n "$LORA_FILE" ]]; then
+    [[ -e "$LORA_FILE" ]] || { echo "frank-zealot: missing $LORA_FILE" >&2; exit 1; }
+    EXTRA_ARGS+=(--lora-scaled "${LORA_FILE}:${LORA_SCALE}")
+fi
+
 # Prometheus scraping is opt-IN in llama.cpp: without --metrics the server
 # answers 501 on /metrics, and the fleet scrape then reports the endpoint DOWN.
 if [[ "$METRICS" = "1" ]]; then

scripts/stack-qwen38-official-fp8.py

@@ -337,8 +337,12 @@ def main():
     if any(meta[shard_ids[i]][4][1] != hd for i in range(n_shards)):
         log("ERROR: PLE shards disagree on HD")
         return 2
-    if hd % 128 != 0 and hd != 160:
-        log(f"WARNING: PLE HD={hd} is neither 160 nor a multiple of 128")
+    if hd != 160 and hd % 128 != 0:
+        # The pack below writes lanes of 128 codes; any other HD would produce a
+        # table that decodes to the wrong rows. The old warning let it continue.
+        log(f"ERROR: PLE HD={hd} is neither 160 nor a multiple of 128, and the "
+            "128-lane pack cannot express it")
+        return 2
 
     # ---- idempotence gate -------------------------------------------------
     stacked_names = [f"{p}.mlp.experts.gate_up_proj" for p in prefixes]
@@ -521,12 +525,16 @@ def verify(stage, prefixes, n_e, shapes, meta, shard_ids, rows, hd,
         }
         for name, (dt, shp) in want.items():
             e = hdr[name]
-            assert e["dtype"] == dt and list(e["shape"]) == shp, name
-            assert e["data_offsets"][1] - e["data_offsets"][0] == \
-                int(np.prod(shp)) * (1 if dt == F8 else 2), name
+            if e["dtype"] != dt or list(e["shape"]) != shp:
+                raise RuntimeError(f"{name}: header is {e['dtype']}{e['shape']}, expected {dt}{shp}")
+            if e["data_offsets"][1] - e["data_offsets"][0] != int(np.prod(shp)) * (1 if dt == F8 else 2):
+                raise RuntimeError(f"{name}: data span is {e['data_offsets']}, shape {shp} needs "
+                                   f"{int(np.prod(shp)) * (1 if dt == F8 else 2)} B")
     _, phdr = parse_header(out_path)
     e = phdr[next(iter(phdr))]
-    assert e["dtype"] == BF16 and list(e["shape"]) == [sum(rows), hd]
+    if e["dtype"] != BF16 or list(e["shape"]) != [sum(rows), hd]:
+        raise RuntimeError(f"PLE table header is {e['dtype']}{e['shape']}, "
+                           f"expected {BF16}[{sum(rows)}, {hd}]")
 
     # sampled PLE rows: recompute and compare bytes exactly
     lut = e4m3_lut()
@@ -546,7 +554,8 @@ def verify(stage, prefixes, n_e, shapes, meta, shard_ids, rows, hd,
                 with open(out_path, "rb") as ofh:
                     ofh.seek(out_off + got_row * hd * 2)
                     got = ofh.read(hd * 2)
-                assert got == want, f"PLE row {got_row} mismatch"
+                if got != want:
+                    raise RuntimeError(f"PLE row {got_row} does not match the decoded source")
             mm.close()
     log("verify: new-file headers, sizes and sampled PLE rows all exact; "
         "expert slabs were byte-checked in-stack")

scripts/test-changed.sh

@@ -265,6 +265,13 @@ for path in "${CHANGED[@]}"; do
             add_test tests/voice_pack_unit.bats
             add_test tests/scripts_syntax.bats
             ;;
+        # The KLD corpus re-chunker: its seam is its own (the campaign's
+        # one-token-series invariant is asserted there), so a change to it does
+        # not land on the generic scripts/* fallback below.
+        scripts/rechunk-kld-corpus.py)
+            add_test tests/qwen38_rechunk.bats
+            add_test tests/scripts_syntax.bats
+            ;;
         scripts/*)
             add_test tests/scripts_syntax.bats
             ;;
@@ -293,6 +300,14 @@ for path in "${CHANGED[@]}"; do
             add_test tests/caddyfile.bats
             add_test tests/deployment_scoping.bats
             ;;
+        # The GPU exporter is a host process; its seam pins the collector, the
+        # user unit, the deployer function, the planner route, the Prometheus
+        # scrape jobs and the host-system GPU panels — a cross-file contract, so
+        # the whole seam rides on any of its own files.
+        scripts/gpu-exporter.py|scripts/gpu-exporter.service)
+            add_test tests/gpu_exporter.bats
+            add_test tests/deployment_scoping.bats
+            ;;
         dankclaw/udev/*)
             # Host-level udev rules are applied by manual sudo install + udevadm
             # trigger, not dispatched as a service; nothing here is bats-testable.

serverAppConfigs-docs/Agent/Domain Docs.md

@@ -0,0 +1,55 @@
+---
+type: reference
+title: Domain Docs
+description: "Consumer rules for GLOSSARY.md and docs/adr/, and where this vault out-ranks them on operational facts."
+tags: [agent, glossary, adr, documentation]
+timestamp: 2026-10-20T00:00:00Z
+---
+
+# Domain Docs
+
+How the engineering skills (`/grill-with-docs`, `/domain-modeling`,
+`/improve-codebase-architecture`, `/to-spec`) should consume this repo's design
+vocabulary when exploring the codebase.
+
+## Before exploring, read these
+
+- **`GLOSSARY.md`** at the repo root
+- **`docs/adr/`**: read ADRs that touch the area you're about to work in
+
+If either doesn't exist, **proceed silently**. Don't flag their absence; don't
+suggest creating them upfront. `/domain-modeling` (reached via
+`/grill-with-docs` and `/improve-codebase-architecture`) creates them lazily
+when terms or decisions actually get resolved. As of 2026-10-20 neither exists;
+this page is the pointer, not a promise.
+
+## Ownership against this vault
+
+This repo already carries `serverAppConfigs-docs/` — the operational knowledge
+base and, per repo law, the owner of operational facts (endpoint shapes, Eras,
+Laws, runbooks). `GLOSSARY.md` / `docs/adr/` hold **design vocabulary and
+decisions**. Where a term is defined in both, the vault page that owns the fact
+wins — one fact, one owner. A glossary entry restating an endpoint number is
+the bug, not the second source.
+
+## Use the glossary's vocabulary
+
+When output names a domain concept (an issue title, a refactor proposal, a
+hypothesis, a test name), use the term as defined in `GLOSSARY.md`. Don't drift
+to synonyms the glossary explicitly avoids.
+
+If the concept you need isn't in the glossary yet, that's a signal: either
+you're inventing language the project doesn't use (reconsider) or there's a
+real gap (note it for `/domain-modeling`).
+
+## Flag ADR conflicts
+
+If output contradicts an existing ADR, surface it explicitly rather than
+silently overriding:
+
+> _Contradicts ADR-0007 (…), but worth reopening because…_
+
+## Related
+
+- [[Issue Tracker]] — where specs and tickets built on this vocabulary are published.
+- [[Agent Docs and Edits]] — the edit-safety rules that apply while touching any doc in this checkout.

serverAppConfigs-docs/Agent/Issue Tracker.md

@@ -0,0 +1,85 @@
+---
+type: reference
+title: Issue Tracker
+description: "How agent skills read and write Gitea issues here: credential-safe curl, label IDs, and wayfinding without sub-issues."
+tags: [agent, gitea, issues, triage, api]
+timestamp: 2026-10-20T00:00:00Z
+---
+
+# Issue Tracker
+
+Issues and specs for this repo live as Gitea issues in `dank/serverAppConfigs`
+on `http://192.168.0.143:3000` (Dankclaw). There is no `gh`/`glab` CLI here —
+the door is the GitHub-compatible REST API driven with `curl`. The
+mattpocock-lineage skills (`/triage`, `/to-tickets`, `/to-spec`, `/wayfinder`)
+read this page as their tracker contract. The git workflow around issues and
+PRs (branches, PR-only merges, attribution footer) is owned by
+[[Deployment Flow]]; this page owns only the API shape.
+
+## Auth
+
+The token lives in the git credential file `~/.config/secrets/gitea`: one
+line in git-credential URL form, `http://user:TOKEN@192.168.0.143`. Extract it
+without echoing:
+
+```bash
+tok=$(sed -nE 's#^http://[^:/@]+:([^@]+)@192\.168\.0\.143.*#\1#p' ~/.config/secrets/gitea | head -1)
+```
+
+**A token on a command line is world-readable in `/proc/<pid>/cmdline`** (the
+same leak class AGENTS.md records for HF tokens). Never pass it with `-H` —
+put it in a mode-600 curl config and pass `-K`:
+
+```bash
+cfg=$(mktemp); chmod 600 "$cfg"
+printf 'header = "Authorization: token %s"\n' "$tok" > "$cfg"
+# ... every curl below uses -K "$cfg"; rm -f "$cfg" when done
+```
+
+**GETs also accept HTTP Basic; writes do not** — a POST/PATCH with Basic auth
+is refused with `422 {"message":"token is required"}` (measured 2026-10-20).
+Use the `Authorization: token` header for everything.
+
+## Conventions
+
+`$API=http://192.168.0.143:3000/api/v1/repos/dank/serverAppConfigs`
+
+- **Create an issue**: `curl -s -K "$cfg" -X POST -H 'Content-Type: application/json' -d "$(jq -n --arg t "$TITLE" --rawfile b "$BODY" '{title:$t, body:$b}')" $API/issues`
+- **Read an issue**: `curl -s -K "$cfg" $API/issues/<number>` (fields: `number`, `title`, `body`, `labels[].name`, `state`)
+- **List issues**: `curl -s -K "$cfg" "$API/issues?state=open&limit=50"` — add `&labels=<id>` to filter
+- **Comment**: `curl -s -K "$cfg" -X POST -d "$(jq -n --rawfile b "$BODY" '{body:$b}')" $API/issues/<number>/comments`
+- **Apply labels**: `POST $API/issues/<number>/labels` with `{"labels":[<label-ID numbers>]}` — Gitea wants numeric label **IDs**, not names; resolve them from `GET $API/labels` (see [[Triage Labels]] for which labels exist)
+- **Remove a label**: `DELETE $API/issues/<number>/labels/<label-id>`
+- **Close**: `PATCH $API/issues/<number>` with `{"state":"closed"}`
+- **Blocking relationships**: this instance has no native sub-issues or dependencies — put `Part of #<parent>` / `Blocked by: #<n>, #<n>` lines at the top of the child body. A ticket is unblocked when every listed blocker is closed.
+- **Attribution footer (repo law)**: every issue body you open ends with `cwd: <working directory> · session: <omp session id>` — full rule in [[Deployment Flow]].
+
+**PRs as a request surface: no.** Issues and PRs have separate number spaces on
+Gitea; a bare `#42` is an issue, a PR is spelled "PR #42".
+
+## When a skill says "publish to the issue tracker"
+
+Create a Gitea issue as above.
+
+## When a skill says "fetch the relevant ticket"
+
+`GET $API/issues/<number>` and read `title` + `body` + `labels[].name` +
+comments.
+
+## Wayfinding operations
+
+Used by `/wayfinder`. The **map** is a single issue labelled `wayfinder:map`,
+holding the Notes / Decisions-so-far / Fog body.
+
+- **Map**: create an issue, apply the `wayfinder:map` label (create it via `POST $API/labels` `{"name":"wayfinder:map","color":"#6f42c1"}` if missing).
+- **Child ticket**: an issue carrying `Part of #<map>` at the top of its body, plus a `wayfinder:<type>` label (`research`/`prototype`/`grilling`/`task`).
+- **Blocking**: the `Blocked by:` body line (see Conventions).
+- **Frontier**: list open issues (`?state=open`), drop any with an open `Blocked by` target or an assignee; lowest `number` wins.
+- **Claim**: `POST $API/issues/<n>/assignees` with `{"assignees":["dank"]}` — actually assign it or it stays in the frontier; the session's first write.
+- **Resolve**: post the answer as a comment, `PATCH` to `closed`, then update the map issue's body (GET → edit Decisions-so-far → PATCH) with a context pointer.
+
+## Related
+
+- [[Triage Labels]] — the role strings these operations apply.
+- [[Domain Docs]] — what a skill must read before touching the codebase.
+- [[SSH and Remote Access]] — reaching the host when an issue needs live evidence.

serverAppConfigs-docs/Agent/OMP Harness.md

@@ -52,28 +52,31 @@ Where the contract lives:
 The arithmetic (the coupled contract every endpoint's maxTokens comment
 encodes). The authoritative `contextWindow`/`maxTokens` pair per model is on the
 endpoint page ([[frank-archon]], [[frank-dragoon]], [[frank-zealot]]); what
-follows is a **worked example** recomputed from the live files on 2026-10-18 —
-a snapshot, not fleet state — with windows 200,000 / 155,648 / 200,704 and
+follows is a **worked example** recomputed from the live files on 2026-10-21 —
+a snapshot, not fleet state — with windows 200,000 / 200,000 / 200,704 and
 maxTokens 16,384 / 45,056 / 16,384 (archon / dragoon / zealot):
 
 1. **Source trigger** = `thresholdPercent × source contextWindow`; at the live
-   95 % that is 190,000 (archon), 147,866 (dragoon), 190,669 (zealot). The
+   95 % that is 190,000 (archon and dragoon), 190,669 (zealot). The
    bundle clamps the percentage to 1–99 and converts it to a token threshold.
 2. **Output budget** = capped at the target model's `maxTokens` — every role
    here compacts to frank-zealot, so the budget is its 16,384.
-3. **REQUIREMENT**: prompt (≤ trigger) + budget ≤ the target's per-slot
-   window. **At 95 % this no longer holds**: 190,000 + 16,384 = 206,384 >
-   200,704. The registry's own comments design around an 85 % trigger (archon:
-   170,000 est × 1.03 + 16,384 ≈ 191,500 ≤ 200,704, `models.yml:49-56`), which
-   does hold. While `config.yml` and those comments disagree, treat 85 % as the
-   design point and re-run this arithmetic after ANY window change — a 400 from
-   the compaction target mid-conversation is the symptom.
+3. **REQUIREMENT**: prompt (≤ trigger) + budget ≤ the fitting window. For a
+   dragoon session the fitting window is the ENGINE ceiling, not a slot: the
+   190,000 trigger is 62,144 under the 262,144 ceiling, so even ×1.03 est
+   error plus the 45,056 request budget lands inside — that headroom is the
+   reason the ceiling moved to native on 2026-10-21. For a session compacting
+   INTO frank-zealot the window is its 200,704-token slot, and **at 95 % this
+   does not hold for archon/zealot sources**: 190,000 + 16,384 = 206,384 >
+   200,704. Treat 85 % as the design point until config.yml and the registry
+   comments agree, and re-run this arithmetic after ANY window change — a 400
+   from the compaction target mid-conversation is the symptom.
    (Historic 2026-10-05 pairs, at `thresholdPercent: 70`: 140,492 + 36,864 =
    177,356 ≤ 200,704 archon; 140,490 + 57,344 ≤ 200,700 dragoon; 140,492 +
    32,768 ≤ 200,704 zealot.)
 
 Procedure (recompute from the LIVE files every time — windows rotate with
-every swap; the block above is the 2026-10-18 state):
+every swap; the block above is the 2026-10-21 state):
 
 1. Read the `config.yml` compaction block + `models.yml` entries for source
    and target. Every endpoint's `contextWindow` comment carries its own
@@ -94,9 +97,10 @@ Known reconciliation trap: comments in models.yml have described compaction
 as running "on the dankserver endpoint" while `remoteEndpoint` pointed at
 dankclaw — the comment/config disagreed. The comments now name the real
 target (`compaction.remoteEndpoint` = dankclaw :7771). **The config is
-truth; fix comments in the same change.** A fresh instance of the same trap is
-open 2026-10-18: every `maxTokens` comment still says "compaction fires at
-85 % of the window" while `config.yml:84` sets `thresholdPercent: 95`.
+truth; fix comments in the same change.** The 85 %-comments vs 95 %-config
+disagreement is not academic: it is why long dragoon sessions kept drawing
+400s at the old 200,704 ceiling — the trigger fires late AND the est
+under-counts, and a window parked near the ceiling has no room for either.
 `maxTokens` never changes for a reslice — it caps output; `contextWindow` caps
 input. Boot-shape OOM laddering is a different problem
 ([[Llama Cpp Serving Sizing]]).

serverAppConfigs-docs/Agent/Triage Labels.md

@@ -0,0 +1,39 @@
+---
+type: reference
+title: Triage Labels
+description: "The five canonical triage roles mapped to this repo's Gitea label strings, plus the numeric-ID quirk."
+tags: [agent, gitea, triage, labels]
+timestamp: 2026-10-20T00:00:00Z
+---
+
+# Triage Labels
+
+The mattpocock-lineage skills speak in terms of five canonical triage roles.
+This page maps those roles to the actual label strings used in this repo's
+tracker ([[Issue Tracker]] owns the API shape).
+
+| Label in mattpocock/skills | Label in our tracker | Meaning                                  |
+| -------------------------- | -------------------- | ---------------------------------------- |
+| `needs-triage`             | `needs-triage`       | Maintainer needs to evaluate this issue  |
+| `needs-info`               | `needs-info`         | Waiting on reporter for more information |
+| `ready-for-agent`          | `ready-for-agent`    | Fully specified, ready for an AFK agent  |
+| `ready-for-human`          | `ready-for-human`    | Requires human implementation            |
+| `wontfix`                  | `wontfix`            | Will not be actioned                     |
+
+When a skill mentions a role (e.g. "apply the AFK-ready triage label"), use the
+corresponding label string from this table. Edit the "Label in our tracker"
+column to match whatever vocabulary you actually use.
+
+## Instance quirks (Dankclaw Gitea)
+
+- Labels are applied by **numeric ID**, never by name: `POST /issues/<n>/labels`
+  with `{"labels":[<id>]}`; resolve names via `GET /labels`.
+- The repo also carries the pre-existing `human-only` label from the manual era
+  (e.g. the podcast-destination issues). `ready-for-human` maps to itself; the
+  `(HUMAN ONLY)` title prefixes on existing issues stay as they are — the label
+  is what the skills read.
+- An issue with **no** triage label is simply untriaged; absence is not a state.
+
+## Related
+
+- [[Issue Tracker]] — the auth-safe curl shape that applies these labels.

serverAppConfigs-docs/Agent/index.md

@@ -6,6 +6,9 @@ docs get edited safely, and how the agent's home is deployed.
 - [[OMP Harness]] — The omp harness as configured here: compaction chain arithmetic, per-model sampler routing, and the context-lean audits.
 - [[Agent Docs and Edits]] — Two self-inflicted doc damage classes from parallel agent edits, with the audit checks and recovery order for each.
 - [[Command Center Dotfiles]] — How the dotfiles repo deploys: stow-equivalent packages, full-replica rsync, the pre-overwrite audit, transport gotchas.
+- [[Issue Tracker]] — How agent skills read and write Gitea issues here: credential-safe curl, label IDs, and wayfinding without sub-issues.
+- [[Triage Labels]] — The five canonical triage roles mapped to this repo's Gitea label strings, plus the numeric-ID quirk.
+- [[Domain Docs]] — Consumer rules for GLOSSARY.md and docs/adr/, and where this vault out-ranks them on operational facts.
 
 ## Related
 

serverAppConfigs-docs/Architecture/Container Network Namespaces.md

@@ -8,7 +8,7 @@ tags:
   - netavark
   - rootless
   - dankclaw
-timestamp: 2026-09-02
+timestamp: 2026-10-19
 ---
 
 # Container Network Namespaces
@@ -88,8 +88,53 @@ Verified outcomes of that recipe on 2026-09-02: from inside `hermes-dashboard`
 published) and `:9119` (its own published port) connect; `:8080` and `:8787`
 are **refused instantly** even though both listeners are bound to `0.0.0.0` in
 the host netns. Probes to `host.containers.internal` (`169.254.1.2`) from that
-network time out rather than refuse — the alias is an address on the *default*
-`podman` network, and this container is not on it.
+network time out rather than refuse — but see the 2026-10-19 re-measure below,
+where the same alias answers from another `dankclaw_default` container.
+
+### 2026-10-19: which published ports a rootless container can actually dial
+
+Probed from inside `open-notebook` (rootless, on `dankclaw_default` **and** the
+private `systemd-open-notebook`), each address aimed at a live listener:
+
+| Dial | Result | Mechanism |
+|---|---|---|
+| `192.168.0.143:3000` (Gitea) | **200** | published by a **rootless** container — rootless egress crosses the host netfilter where netavark installed that DNAT |
+| `192.168.0.143:7770` (`frank-dragoon`) | refused | the container is **rootless on podman's default `pasta` netns** (the root unit's `User=dank` runs `podman run`, so it lands in dank's storage). Pasta forwards the published port in the host netns — the host and the LAN both answer 200 — but installs no netavark DNAT for traffic arriving from a rootless bridge, so the same address is refused from a container. This is NOT a root/rootless rule-set split: `podman ps` as `dank` lists it |
+| `host.containers.internal:7770` (`169.254.1.2`) | **200** | the pasta forwarder is bound `0.0.0.0` on the host, so the gateway alias reaches it — and the alias is link-local, which is the dead end below |
+| `192.168.0.143:7771` (`frank-zealot`) | refused | host-netns listener, unpublished — the rule above, reconfirmed |
+| `10.89.1.1:7771` | refused | the bridge gateway address belongs to the rootlesskit netns, not to the host |
+| `host.containers.internal:7771` (`169.254.1.2`) | **200** | the gateway alias is the one address that carries a rootless container to a host-netns listener. Why `hermes-dashboard` timed out on this alias in 2026-09-02 while `open-notebook` answers today is **not established**; the difference to check first is the second network and where the default route lands |
+| `192.168.0.235:7770` (`frank-archon`) | **200** | a different machine: plain routing, no DNAT in the path |
+
+The consequence that changed designs: **a rootless container's menu of local model
+endpoints was only `frank-tts` (container DNS, same network) and `frank-archon` (LAN
+address on another host).** A `pasta` endpoint has no address an app container can
+use: the LAN address is refused, and the one alias that answers is link-local,
+which some applications refuse to store at all ([[Open Notebook]] meets exactly
+that refusal). Pasta cannot be *added to* either —
+
+```
+podman run --network pasta --network dankclaw_default …
+Error: cannot set multiple networks without bridge network mode, selected mode pasta
+```
+
+so the only shape that makes such an endpoint nameable is **moving it onto
+`dankclaw_default`** (`FRANK_DRAGOON_NETWORK` in `scripts/frank-dragoon.env`,
+2026-10-19). For frank-dragoon that is not an exposure change: the engine's
+unauthenticated token port binds the container's **own loopback**
+(`/proc/net/tcp` on 2026-10-19: `127.0.0.1:8730`, `0.0.0.0:8731`), so only the
+API port becomes name-resolvable, which is the same trust the published 7770
+already carries on the LAN. `frank-zealot` (7771) stays a host-netns binary and
+remains unreachable except through the link-local alias.
+
+The move is verified from the consumer side, so the table above reads as the
+**pre-move** census and not as today's menu: inside `open-notebook`,
+`getent hosts frank-dragoon-halogen` → `10.89.1.39`, `GET :8731/v1/models`
+lists both served models, and the engine's log carries the app's
+`POST /v1/embeddings 200` from that address (2026-10-19) — see
+[[Open Notebook]] for what runs over it. What the table still owns is the
+pasta rule itself: nothing about pasta's forwarding changed, the endpoint was
+moved out of it.
 
 ## Operational rules
 
@@ -98,9 +143,13 @@ network time out rather than refuse — the alias is an address on the *default*
   host — and never the reverse either: the deployer's health probe runs on the
   host, so it sees host-netns listeners that the container itself cannot dial.
 - To give a bridge-net container access to a host-netns listener, the options
-  are (a) move it to `Network=host`, or (b) publish the needed port. Option (b)
-  makes that port reachable from every netns and from the LAN — an exposure
-  change that needs operator approval before deployment, not a silent fix.
+  are (a) move it to `Network=host`, or (b) publish the needed port — but
+  publishing is advertised **only inside the Podman that owns the container**:
+  a root container's published port stays invisible to a rootless consumer
+  (2026-10-19 table above), so the fix must be made on the same root/rootless
+  side as the consumer. Either way it is an exposure change — a published port
+  also answers on the LAN — and needs operator approval before deployment, not
+  a silent fix.
 - `chrome-devtools-protocol` is intentionally `Network=host` with a loopback-only
   bind so the browser tool stays unreachable from the LAN; do not "tidy" it onto
   a bridge network — its two consumers (gateway, webui) are host-netns and reach

serverAppConfigs-docs/Architecture/Quadlet Lifecycle.md

@@ -130,10 +130,19 @@ Quickest unblock: `podman compose up -d --force-recreate <svc>`. Durable fix
 
 ## 4. Podman 5.x quadlet v1 generator quirks (verified live 2026-08-28)
 
-- **Hard-fail keys** — the whole unit silently fails to generate
-  (`systemctl --user cat <unit>` shows "could not be found"): any
-  dash-prefixed `[Container]` option (`--shm-size=…` → `unsupported key …
-  in group 'Container'`); `Command=` is unsupported, use `Exec=`.
+- **Hard-fail keys abort the WHOLE BATCH, not one unit** (podman 5.7.0,
+  live 2026-10-21): one unsupported key — e.g. `HostAddr=` — makes the
+  generator log `unsupported key … in group 'Container'` plus
+  `processing encountered some errors` and generate NOTHING for that
+  manager. The running containers keep going as orphans, so the failure
+  first appears on the next deploy as `Unit <x>.service not found` for a
+  service that is visibly up. Other offenders: any dash-prefixed
+  `[Container]` option (`--shm-size=…`), `Command=` (use `Exec=`).
+  The seam `tests/quadlet_image_pins.bats` fails the build on any
+  generator-rejected key in any host's units.
+  Also: an image whose ENTRYPOINT is the binary takes FLAGS ONLY in
+  `Exec=` — repeating the binary makes it a positional arg
+  (`unexpected /bin/blackbox_exporter`, live 2026-10-21).
 - **HealthCmd space-splitting:** the v1 generator splits `HealthCmd` on
   spaces into the healthcheck argv; a quoted probe
   `/bin/sh -c "pg_isready …"` lands as argv token `"pg_isready` →
@@ -148,6 +157,16 @@ Quickest unblock: `podman compose up -d --force-recreate <svc>`. Durable fix
   "unsupported key"`, `systemctl --user cat probe.service` (shows the
   generated ExecStart verbatim), then remove + reload.
 
+## 4a. Image pins (fleet law, 2026-10-21)
+
+Every registry image in a quadlet is digest-pinned (`tag@sha256:…`);
+locally built images (`localhost/*`, `franksdank/*`) are exempt — their
+build is the pin. A rolling tag lets a rebuild move under a running
+service with nobody approving it, and it makes a CVE audit ungradeable.
+Gate: `tests/quadlet_image_pins.bats`. Where upstream publishes no version
+tags (copyparty-ac stops at 1.19.15), pin `:latest@sha256:` and name the
+version the config label carries in the comment beside it.
+
 ## 5. Rootless Quadlet log retrieval
 
 Step 0 — establish ownership: `systemctl --user status <name>.service`

serverAppConfigs-docs/Architecture/Stale Signal Audit.md

@@ -116,6 +116,20 @@ as working when they could never report up. **Clean cutover includes prose** —
 docs, unit docstrings, and the repo's rule file (the most expensive place to
 be stale).
 
+## Three rules that outlive the incident that taught them
+
+* **A target can read down beside a healthy service.** Read `lastError` from
+  `/api/v1/targets` before believing an outage — llama.cpp refuses `/metrics` at the
+  protocol layer without `--metrics` (501) while `/health` answers 200 for weeks.
+* **Alert state lives where the tool says it does.** Prometheus keeps rule state in
+  process memory — a restart re-stamps `activeAt`, so a "fresh" alert after a reboot is
+  not evidence of a fresh fault. Alertmanager **does** persist (`--storage.path` on a
+  host volume: silences + notification log, [[Alertmanager]]).
+* **Never quote a candidate arm's flags or VRAM as fleet state.** A stopped production
+  unit (`failed` after `stop-sigterm timed out. Killing` — the known shutdown shape,
+  [[frank-zealot]]) beside an answering port means the metric measured a scratch boot;
+  the process shape can change between two censuses ten minutes apart.
+
 ## Order and verification
 
 1. Enumerate the surfaces (status board, metrics targets, alert rules, test

serverAppConfigs-docs/Dankclaw/ComfyUI Qwen-Image Workflows.md

@@ -110,9 +110,9 @@ only `models`, `input`, `output`, `custom_nodes` and the healthcheck file
 
 ## Recommended additions
 
-Quantized preferred, sized for the 8060S iGPU (GTT-backed — `/system_stats`
-reports 122.4 GB of device VRAM on `cuda:0`, `curl http://127.0.0.1:8188/system_stats`
-2026-10-18; the RTX 3090 is frank-zealot's). All repos verified 2026-10-05 and
+Quantized preferred. The iGPU's GTT aperture is not free RAM beside
+frank-dragoon — size every pick against *What actually fits beside
+frank-dragoon* below (the RTX 3090 is frank-zealot's). All repos verified 2026-10-05 and
 all four still resolve today (`huggingface.co/lightx2v/Qwen-Image-Lightning`
 `huggingface.co/unsloth/Qwen-Image-Edit-2511-GGUF`
 `huggingface.co/Comfy-Org/Qwen-Image-DiffSynth-ControlNets`
@@ -133,8 +133,34 @@ sha256 checks) or a plain `hf download` with the token in the environment —
 never on the command line.
 
 Skip list: the original `city96/Qwen-Image-gguf` conversions (superseded by
-the 2.1 files already on disk), and any BF16 of #2/#4 (the iGPU does not need
-them at GTT capacity, and they double the disk bill).
+the 2.1 files already on disk), and any BF16 of #2/#4 — they double the disk
+bill, and see *What actually fits beside frank-dragoon* for why raw GTT size
+is not the real budget.
+
+## What actually fits beside frank-dragoon
+
+The 122 GB `/system_stats` figure is the GTT **aperture**, not free memory: on
+an APU the aperture and `MemAvailable` are the same physical RAM, and
+frank-dragoon pins tens of GiB of it. Measured 2026-10-21 with frank-dragoon
+live: `MemAvailable` 15.3 GiB, iGPU busy 1.75 GiB — ComfyUI itself idles at
+~10 MB, so the budget for a generation run is roughly what `free` says.
+
+Weights must land inside that budget with slack for compute buffers and
+activations (the mmproj-class lesson: price a model at ~1.5× its file set):
+
+| Pipeline (weights) | Fits beside frank-dragoon? |
+|---|---|
+| Qwen-Image 2.1 int8_convrot + w4a8 + bf16 VAE (~14.2 GB) — the two proven workflows | **No** — thrash-or-fail; do not queue it while the endpoint serves |
+| GGUF Q8_0 + w4a8 + small VAE (~13.3 GB) | No, same reason |
+| Any BF16 combination | No |
+| SDXL-Turbo / SD 1.5-class (~2–7 GB) | Yes, with real headroom |
+
+**The law: one process owns the memory — same rule as the 3090 bench law.**
+For a Qwen-Image render: stop and mask frank-dragoon
+(`sudo systemctl stop frank-dragoon` + `mask` — the mask stops
+`Restart=always` from firing mid-render), generate, unmask, verify
+`curl 192.168.0.143:7770/health`. The proven workflows above then run with
+the whole machine. Do not treat `/system_stats`'s 122 GB as an invitation.
 
 ## See Also
 

serverAppConfigs-docs/Dankclaw/ComfyUI.md

@@ -129,6 +129,12 @@ bind-mounted to `/usr/local/bin/comfyui-healthcheck.py` and run as `HealthCmd`
 - Do not let pip reinstall the torch family. The Containerfile filters it out on purpose.
 - The base image is about 32 GiB (`podman image inspect localhost/comfyui-rocm:gfx1151` → 33,765,227,471 B ≈ 31.4 GiB, 2026-10-18). A code update means a rebuild, because the code is baked in.
 - The empty-models note from the 2026-09-16 era is retired: `/home/dank/comfyui-data/models` now holds the Qwen-Image 2.1 payload — three `diffusion_models`, three `text_encoders`, two VAEs (~35 GB, `ls -l` 2026-10-18), listed in [[ComfyUI Qwen-Image Workflows]]. New model classes (LoRA, ControlNet) still need their directories created first: `models/lora` and `models/controlnet` do not exist yet.
+- **The 122 GB `/system_stats` VRAM figure is the GTT aperture, not free
+  memory.** On the APU it is system RAM, and frank-dragoon pins most of it
+  (`MemAvailable` 15.3 GiB with the endpoint live, measured 2026-10-21). A
+  Qwen-Image-class render beside the running endpoint is thrash-or-fail; the
+  stop-mask-render-verify procedure and the fit table are in
+  [[ComfyUI Qwen-Image Workflows]] → What actually fits beside frank-dragoon.
 
 ## See Also
 

serverAppConfigs-docs/Dankclaw/Frank TTS Engine.md

@@ -1,35 +1,36 @@
 ---
 type: reference
-description: "The engine behind the fleet's speech endpoint: its runtime, private bridge, and the surface it publishes."
+description: "The engine behind the fleet's speech endpoint: its Vulkan build on the iGPU, its private bridge, and what it publishes."
 tags:
   - dankclaw
   - tts
   - voice
   - quadlet
-  - cpu
-timestamp: 2026-10-18
+  - vulkan
+timestamp: 2026-10-19
 ---
 
 # 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.
+`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)** loaded once and synthesizing from there — **on the gfx1151 iGPU** (ggml's Vulkan backend, `--device Vulkan0`) since 2026-10-19, and in host RAM before that. 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 when asked, and owns the timeout budget. This page is the engine runbook; the endpoint's contract lives with its own page.
 
-**Deployed 2026-10-18.** The chain ran in the order at the bottom of this page — fetch (1.4 GiB, byte + LFS oid verified, 18 s), image build against the pinned commit, unit + network install, container-health gate, warm pass — and the live state still reads the way this page describes it: unit `active` with no drop-ins, container healthy 31 s after the build, **4.0 GiB** resident on a host that kept 17 GiB available, `3 voice(s) registered and warm` in the journal, and no published port anywhere. Two things the first real boot taught: the warm hook's registration body must reach curl through a **file**, not an argument (Troubleshooting), and `STEP 3/13 RUN useradd` is the first honest proof of the image's non-root user.
+**Deployed 2026-10-18, cut over to the iGPU on 2026-10-19.** The first chain ran in the order at the bottom of this page — fetch (1.4 GiB, byte + LFS oid verified), image build against the pinned commit, unit + network install, container-health gate, warm pass — and the live state still reads the way this page describes it: unit `active` with no drop-ins, container healthy shortly after the build, `3 voice(s) registered and warm` in the journal, and no published port anywhere. Two things the first real boot taught: the warm hook's registration body must reach curl through a **file**, not an argument (Troubleshooting), and `STEP 3/13 RUN useradd` is the first honest proof of the image's non-root user.
 
 **Host:** Dankclaw (`192.168.0.143`), rootless Podman, user `dank` — **Port:** 8880, **never published** — **Network:** the private `systemd-frank-tts-engine` bridge (10.89.5.0/24) and no other — **Deployer:** `frank-tts-engine` — **Consumers:** `frank-tts` (7772) and, through it, every voice request in the fleet including [[Open Notebook]]'s podcast renders.
 
-## Facts (verified 2026-10-18 against the pinned upstream commit, the Hub, and the CPU trial on this host)
+## Facts (verified 2026-10-18 against the pinned upstream commit, the Hub and the CPU trial; the device rows re-verified on the live iGPU shape 2026-10-19)
 
 | 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 |
+| 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=ON -DGGML_METAL=OFF -DGGML_SYCL=OFF -DGGML_RPC=OFF && cmake --build build -j 8`. **`GGML_VULKAN=ON` since 2026-10-19**, and that door needs three packages in the build stage: `libvulkan-dev`, `spirv-headers`, and **`glslc`** — which Ubuntu's `glslang-tools` does NOT ship (it ships `glslangValidator`, and `find_package(Vulkan COMPONENTS glslc REQUIRED)` fails without the package). The archive's `glslc` is 2023.8: `GL_KHR_cooperative_matrix` compiles, the coopmat2 / integer-dot / bf16 / micro-float shader families do not. `GGML_BLAS=OFF` is **forced**: Dankclaw has `libopenblas.so.0` and no BLAS dev headers, so upstream's own `Dockerfile` and `buildcpu.sh` (both 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), `libvulkan1` + `mesa-vulkan-drivers` (the loader and the RADV ICD — a loader with no ICD enumerates ZERO devices, and the server then dies in device lookup after both GGUFs have been read), uid **10000**, `LD_LIBRARY_PATH=/app` because ggml builds shared by default and the link-time RPATH names the build tree. **No NVIDIA ICD on purpose**: exactly one Vulkan device in the enumeration is what makes the name `Vulkan0` safe to write down |
 | 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 |
+| Device | `--device Vulkan0`: the gfx1151 iGPU, **shared with [[frank-dragoon]] as a co-tenant, never a handover**. Proven on the live pair, not inferred: `fuser -v /dev/dri/renderD129` lists `tts-server` beside `flash_serve`. Both gates (the RADV heap and dragoon's contention) are §5 of `report/tts-npu-spike-verdict-2026-10-19.md`, which also carries the change surface. **Rollback: `QWENTTS_DEVICE=` (empty) in `scripts/frank-tts-engine.env`, redeploy this one service** — the entrypoint then passes no `--device` at all, which is the CPU shape, no rebuild, nothing else restarts |
+| Memory | **1.7 GiB host RSS** since the iGPU cutover — the weights ride the device. 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 the iGPU measures **0.20** (11.04 s of audio in 2.23 s) with `frank-dragoon` live on the same card, so a live stream has room to spare; a second concurrent synthesis would share the device with the first and make the caller behind it wait out the whole first utterance, so the FIFO stays a decision, not an accident |
 | 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 |
@@ -37,18 +38,11 @@ timestamp: 2026-10-18
 
 ## 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 , which is the source of these numbers):
+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. On that criterion the resident `tts-server` (arm A) beat the mainline per-request CLI path (arm B) on this box the same day, and the deciding property was **spread**: the resident server repeats the same first-audio latency every run, while the CLI path varies enough that some runs fall behind real time and a live listener hears the stream stall mid-sentence. That A/B was a CPU measurement and the endpoint has since moved to the iGPU, so the shape of the argument is what is kept here; no page carries its numbers any more, and they are not worth re-deriving.
 
-| 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 rollback to the other backend 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.
 
-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
+## Four laws this service lives under
 
 **1. The registry law → the unit warms at boot.** The voice registry is **memory only**: a restart forgets every voice, and re-registering one does **not** warm it — only synthesizing does. A boot that registers nothing leaves the façade answering 400 for every name, which is why `frank-tts-engine.container` carries
 
@@ -64,10 +58,12 @@ frank-tts-engine-warm: voice narrator1 cold=1402ms warm=1812ms
 frank-tts-engine-warm: 3 voice(s) registered and warm
 ```
 
-**2. The thread law → nothing is ever pinned.** `tts-server` in this build has **no `-t`/`--threads` flag**: `src/backend.h` computes the CPU thread count as `std::thread::hardware_concurrency() / 2` (its comment: GEMM shares SIMD units across hyperthreads). Thread count therefore follows what the kernel *reports*, not what a cgroup *allows* — so `CPUQuota=`, `CPUAffinity=`, `taskset` or a slice silently changes the engine's GEMM tiling and its timings, with no log line. Nothing in this fleet pins this container. If a neighbour starves it, fix the neighbour.
+**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 pool sizes and its timings, with no log line. The rule did not retire with the iGPU cutover: the binary still sizes those pools from what the kernel says, whatever the device ends up doing with the matmuls. 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.
 
+**4. The device law → the card is shared, and the rollback is one line.** Synthesis computes on the gfx1151 **beside** [[frank-dragoon]], so a change to either tenant is a change to both. Two gates decide that pair, and both passed on 2026-10-19 with the other tenant live: the RADV heap a rootless container tenant is actually handed (not the ~2 GiB DRM carve-out), and dragoon's own first-token and decode rates with a synthesis in flight — unchanged. Their numbers, the recipe that measures them, and the full change surface are §5 of `report/tts-npu-spike-verdict-2026-10-19.md`; do not re-derive them here. What belongs on this page is the move: `QWENTTS_DEVICE=` (empty) in `scripts/frank-tts-engine.env`, re-deploy this one service, and synthesis is back on CPU — no rebuild, and dragoon never restarts.
+
 ## The voice registry contract
 
 A voice becomes known to the engine through `POST /v1/audio/voices`, and only these shapes are accepted:
@@ -97,9 +93,9 @@ The **façade** on 7772 is the pair's public surface and carries the probe. Note
 | `dankclaw/voiceservice/Containerfile.engine` | two-stage build of the pinned commit, proven cmake line, digest-pinned base, ships both scripts |
 | `dankclaw/voiceservice/tts-engine-start.sh` | image entrypoint (`/app/start.sh`): env → flags, refuses to boot without weights |
 | `dankclaw/voiceservice/tts-engine-warm.sh` | boot warmer (`/app/warm-voices.sh`): register from `reference.wav` (body via a temp file), speak a fixed sentence twice, report cold/warm |
-| `dankclaw/voiceservice/quadlet/frank-tts-engine.container` | the unit: bridge only, no publish, env file, two read-only mounts, health probe, warm hook, `Restart=always` |
+| `dankclaw/voiceservice/quadlet/frank-tts-engine.container` | the unit: bridge only, no publish, env file, two read-only mounts, render access (`AddDevice=/dev/dri` + `GroupAdd=keep-groups`), health probe, warm hook, `Restart=always` |
 | `dankclaw/voiceservice/quadlet/frank-tts-engine.network` | the private 10.89.5.0/24 bridge, with the subnet registry |
-| `scripts/frank-tts-engine.env` | paths and numbers only, with the thread law and the registry law in its header |
+| `scripts/frank-tts-engine.env` | paths and numbers only, with the thread law, the registry law and the device 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 |
@@ -118,6 +114,25 @@ still open.
 6. **Then the façade on 7772** (its own page), after the engine answered — that order is the whole point of step 6: publishing the façade in front of a dead engine would make every consumer fail at the first voice line.
 7. **Open:** [[Open Notebook]] is still not installed, so nothing renders a podcast yet; the voice leg it waits on now exists.
 
+### 2026-10-19 — the iGPU cutover (PR #34, `6248f02`)
+
+1. **Configure gate before touching anything** — the flag set, configured inside the
+   digest-pinned base on Dankclaw: `Found Vulkan: … found components: glslc` then
+   `Including Vulkan backend`. That probe is what caught `glslc` missing from
+   `glslang-tools`; the Containerfile's flag comment carries the finding.
+2. **Deploy** — `./scripts/deploy.sh dankclaw --service frank-tts-engine`: image rebuild
+   (the `cfhash` moved), unit reinstall, health gate, warm pass
+   (`3 voice(s) registered and warm`), Playwright e2e 33/33.
+3. **Prove the device, not the flag** — `sudo fuser -v /dev/dri/renderD129` lists
+   `tts-server` next to dragoon's `flash_serve`. Do this instead of reading the log: the
+   engine prints nothing about which backend it chose, so argv (`--device Vulkan0`) proves
+   intent and the render-node holder list proves use.
+4. **Consumer path** — one `/v1/audio/speech` per voice through the façade on 7772; all
+   three answered with audio. The RTF figure in the Facts table comes from one engine-direct
+   WAV, where the duration is exact.
+5. **Co-tenancy gate** — §5 of the verdict report: dragoon's first token and decode
+   unchanged with a 16.9 s synthesis occupying the card.
+
 ## Troubleshooting
 
 | Symptom | Meaning | Move |
@@ -131,3 +146,5 @@ still open.
 | `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  |
 | 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 |
+| Unit restarts every 10 s and the log ends on a **device** error *after* both GGUFs were read | the image has the Vulkan loader but no ICD, or the container has no render node — the device name then resolves to nothing | `podman exec frank-tts-engine ls /dev/dri` (it must see `renderD129`) and `podman exec frank-tts-engine dpkg -l \| grep -E 'mesa-vulkan\|libvulkan1'`; re-deploy to rebuild the image, or set `QWENTTS_DEVICE=` and re-deploy for the CPU shape |
+| `frank-dragoon` slows while TTS speaks | the contention premise broke — a Mesa bump, a third GPU tenant, a bigger synthesis | `QWENTTS_DEVICE=` + re-deploy this service, then re-run the gate recipe in §5 of `report/tts-npu-spike-verdict-2026-10-19.md` before putting it back |

serverAppConfigs-docs/Dankclaw/Frank TTS.md

@@ -21,7 +21,7 @@ never learn a path.
 **Deployed 2026-10-18** — `./scripts/deploy.sh dankclaw --service frank-tts`
 both units `active`, no drop-ins, and the homepage card's `wip` gate came off in
 the same change. Probes on the deployed endpoint: `/health` answers
-`{"status":"ok","backend":"omni-http","voices":["narrator1","narrator2","narrator3"]}`
+`{"status":"ok","backend":"omni-http","voices":["dr.kern","garrickhagon","jeffhays","vaati","wilwheaton"]}`
 and two different voices rendered the same sentence into **different** bytes
 (24 kHz mono PCM16, 4.24 s, healthy RMS) — so name resolution is real, not a
 pass-through of one default. The operator harness routes its `speech` role here;
@@ -32,7 +32,7 @@ render needs the app installed, not this endpoint.
 | --- | --- |
 | Host | Dankclaw (`192.168.0.143`), rootless podman, user unit `frank-tts.service` |
 | Port | **7772**, published (`PublishPort=7772:7772`) — the rest of the `frank-*` port family is in [[Dankclaw Stack]] |
-| Routes | `GET /health`, `GET /v1/audio/voices`, `POST /v1/audio/speech`; everything else 404, and speech is POST-only |
+| Routes | `GET /health`, `GET /v1/audio/voices`, `POST /v1/audio/speech`; everything else 404, and speech is POST-only. The request's `model` field is **ignored** (measured 2026-10-19: `voxcpm2` and `tts-1` both synthesize the same way) — the voice comes solely from `voice`, so a consumer that must name a model may name it anything |
 | 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 |
@@ -42,8 +42,8 @@ render needs the app installed, not this endpoint.
 
 ## 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
+A voice **is** a directory name. `voice=wilwheaton` resolves to
+`/voices/wilwheaton/reference.wav`, and that file — not a manifest, not a config
 entry — is what makes the name real. omp's TTS device may send `voice_id`; the
 shim accepts either. A call that sends **neither** — the harness's normal shape,
 because no harness setting carries a voice for this transport — speaks
@@ -59,10 +59,11 @@ 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.
+census. As of 2026-10-20 the live packs are `dr.kern`, `garrickhagon`,
+`jeffhays`, `vaati`, `wilwheaton`. [[Open Notebook]]'s `dank-duo` profile speaks
+`wilwheaton` (Frank) and `vaati` (Comrade), and `DEFAULT_VOICE` is `wilwheaton`.
+Renaming a pack that a speaker profile names breaks episode rendering, not just
+speech. A personal voice gets the person's name, lowercase.
 
 ## Voice packs
 
@@ -113,16 +114,19 @@ shows up as a failed synthesis, never as a down probe.
 
 ## Where the engine computes
 
-CPU, and only CPU is compiled in: `Containerfile.engine` builds `qwentts.cpp` with
-`-DGGML_VULKAN=OFF` written out explicitly, so the container carries `libggml-cpu` and no
-other backend. The realistic accelerator is the gfx1151 iGPU behind that flag — plus
-`/dev/dri` passthrough, the ComfyUI pattern — on the same payload and the same pinned
-commit, and the intended shape is **co-tenancy**: the engine resident on the card beside
-`frank-dragoon`, not a handover. Memory is not what decides that; shader contention is, and
-the census plus both gates are in `report/tts-npu-spike-verdict-2026-10-19.md` §5.
-**The Strix Halo NPU is not a door at all**: XDNA2 executes only precompiled AIE
-partition programs, and AMD's own Linux runtime opens `/dev/accel/accel0`, succeeds at the
-ioctls, then declines this model family's graph without emitting a single log line. The
+The **gfx1151 iGPU**, as a co-tenant beside `frank-dragoon`: the Vulkan build of
+`qwentts.cpp` with `--device Vulkan0`, and `/dev/dri` handed to the engine container. That is
+the shape since 2026-10-19. The flag, the device name, the render-node trap on this hybrid box
+and the one-line CPU rollback are owned by [[Frank TTS Engine]] — read that page before
+touching either tenant, because a change to one is a change to both. Co-tenancy was gated with
+`frank-dragoon` live on the card (its first token and decode rates unchanged with a synthesis
+in flight); both gate recipes are §5 of `report/tts-npu-spike-verdict-2026-10-19.md`.
+
+**The NPU is a door only for a model the vendor has already compiled for it.** XDNA2 runs nothing but
+precompiled AIE partition programs, and AMD's own Linux runtime opens `/dev/accel/accel0`, succeeds at the
+ioctls, then declines this model family's graph without emitting a single log line. That is why TTS stays on
+the GPU — and it is not a general veto on the device: halogen ships its own precompiled catalog (embeddings,
+decisions, rerankers) that does run there, which is what [[frank-dragoon]]'s NPU-lane section is about. The
 measured record and the model-side contract live in `report/` at the repo root
 (`tts-npu-spike-verdict-2026-10-19.md`).
 
@@ -218,5 +222,5 @@ harness bundle and measured the day of the flip:
 | Endpoint answers, synthesis fails | the engine: `podman healthcheck run frank-tts-engine`, then `systemctl --user status frank-tts-engine.service` |
 | First request of the day is ~0.6 s slower than the rest — or every name returns 400 | the warm pass did not run; it carries `-`, so it cannot fail the unit. `journalctl --user -u frank-tts-engine` for the warmer's lines, then `podman exec frank-tts-engine /app/warm-voices.sh` — the registry is memory-only (law 1 of [[Frank TTS Engine]]) |
 | The unit never appears after a deploy | the generator dropped it: `frank-tts-engine.network` is missing from `~/.config/containers/systemd/` |
-| A consumer rejects `narrator1` by listing 29 names (`af_heart … bm_fable`) and no request ever reaches this endpoint | that consumer is synthesizing **in the browser** with Kokoro.js, whose voice pack is fixed — OpenWebUI 0.11.4 ships it as the `browser-kokoro` TTS engine; see [[OpenWebUI]] |
+| A consumer rejects `wilwheaton` by listing 29 names (`af_heart … bm_fable`) and no request ever reaches this endpoint | that consumer is synthesizing **in the browser** with Kokoro.js, whose voice pack is fixed — OpenWebUI 0.11.4 ships it as the `browser-kokoro` TTS engine; see [[OpenWebUI]] |
 ---