docs: the vault and AGENTS.md describe two Dankclaw endpoints

halogen-flash-server is ACTIVE again with its 2026-09-16 measured ledger (budget
33.5 GiB against a need of 27.2 — no clamp — and 14.7 GiB left for everything
else), ik_llama.cpp is retired with its measurements kept as the record of why,
and the new frank-small runbook covers the -mtp file, the 64 KiB/token KV
arithmetic, the MTP contract, and the reasoning_effort trap that cost me every
subagent on the endpoint.

AGENTS.md: topology, Active Services, runbook index, and three new llama.cpp
lessons (MTP is a property of the file; --jinja is what `tools` needs; a model's
template can reject the harness's thinking level). Three pre-existing defects
found while editing it: a truncated sentence mid-file, a harness path that does
not exist on either server, and the benchmarking stop/mask recipe still calling
frank-large a root unit.

Truthfulness notes worth keeping: the co-tenant stall NOTE prints again, so the
claim that it "no longer prints" is gone and the three observed block counts are
recorded instead of a guessed threshold; and the Observability page says out
loud why frank-large has no scrape job rather than leaving a silent absence.
This commit is contained in:
Frank
2026-09-16 14:52:51 -07:00
parent 40850bbc8f
commit 49e8dfff66
8 changed files with 565 additions and 153 deletions
+28 -20
View File
@@ -58,25 +58,30 @@ on the selected host. The following files select the corresponding service:
- Documentation, tests, deployment tooling, and unrelated container changes
do not select either inference service.
The target-side `scripts/deploy-remote.sh` relinks the selected unit into
`/etc/systemd/system/`, reloads systemd, enables it, restarts it, and waits for
that service's health endpoint (`http://127.0.0.1:7770/health` for the two
inference services; `/v1/version` for the NPU sight+sound endpoint — FLM has no
`/health` route). The wait budget is 20 minutes because cold model loads can be
slow. A failed handler does not advance its per-service state.
The target-side `scripts/deploy-remote.sh` installs the selected service: for a
**root unit** it relinks the repo file into `/etc/systemd/system/`, reloads
systemd, enables it and restarts it (frank-small); for a **Quadlet** it retires
the predecessor, stops the service's own unit, waits for the published port to
clear, installs the `.container` and restarts the generated unit (frank-large).
Each handler then waits on that service's health endpoint —
`http://127.0.0.1:7770/health` for frank-large, `http://127.0.0.1:7771/health`
for frank-small. The wait budget is 20 minutes because cold model loads are
slow: halogen pins ~68 GiB of weights before it serves anything. A failed
handler does not advance its per-service state.
## Unit and artifact paths
Both units point into the stable target checkout:
The units point into the stable target checkout:
```text
/home/dank/serverAppConfigs/scripts/frank-medium.service
/home/dank/serverAppConfigs/scripts/frank-large.service
/home/dank/serverAppConfigs/scripts/frank-small.service
```
The unit files and serve scripts validate their model/runtime artifacts before
starting. Keep `REMOTE_DIR` stable; moving the checkout requires updating both
the unit absolute paths and the deployment tests in the same change.
starting. `frank-large` is a Quadlet under `dankclaw/frank-large/quadlet/`
rather than a unit in `scripts/`; `frank-small` keeps the unit/env/serve trio
above. Keep `REMOTE_DIR` stable; moving the checkout requires updating both the
unit absolute paths and the deployment tests in the same change.
## NPU unit
@@ -105,23 +110,26 @@ change in that service's inputs.
If the LLM handler fails after the target pull:
1. Inspect `sudo journalctl -u frank-medium -n 200` or
`journalctl -u frank-large -n 200`.
2. Confirm the model files, custom runtime binary, and chat template are
readable by `dank`.
1. Inspect `journalctl -u frank-small -n 200` (root unit) or
`journalctl --user -u frank-large -n 200` (rootless Quadlet).
2. Confirm the model files, the runtime binary and (for frank-large) the
container image are present and readable by `dank`.
3. Retry only the affected service:
```bash
./scripts/deploy.sh dankserver --service frank-medium
# or
./scripts/deploy.sh dankclaw --service frank-large
./scripts/deploy.sh dankclaw --service frank-small
```
4. Verify the matching health endpoint before declaring recovery.
Do not stop the other host's inference service during recovery. For benchmark
work, follow the separate stop/benchmark/restart procedure in [[Testing Policy]]
and the repository rules.
Do not stop the other host's inference service during recovery. The two
Dankclaw endpoints are independent processes on different devices: restarting
frank-large does not disturb frank-small, and the reverse holds too — with one
exception worth knowing, that the deployer waits for port 7770 to be released
before it starts the replacement container. For benchmark work, follow the
separate stop/benchmark/restart procedure in [[Testing Policy]] and the
repository rules.
## See Also