@zerwiz/ymir 0.1.4 → 0.1.7

package/.agents/skills/galdr-ymirsystem/assets/smidja.md

@@ -0,0 +1,180 @@
+# Smíðja — the smithy (agent factory)
+
+Load this when working with the smithy: installing it, configuring its roster,
+running a chain, reading its trace, or wiring it into Hlidskjalf.
+
+- **Norse:** **Smíðja** = the smithy (the workshop). Its orchestrator seat is
+  **Völundr**, the master smith — *Kaia's seat inside the factory* (Kaia decides
+  *what* is forged; Völundr decides *how* the smithy runs). Its trace UI is
+  **Smíðja's eye**.
+- **Registry:** `.agents/assets/agents/naming.md`, `docs/lore.md` §XI/§XIII.
+- **Skill (adopted upstream):** `.agents/skills/smidja-factory/` (internals + cookbooks +
+  references + `apps/visualizer/` + sibling skills `smidja-launcher`, `smidja-start`,
+  `smidja-instructions`, `volundr`).
+
+**Two layouts, one smithy — do not confuse them.** A *target* repo the smithy is
+installed into gets the stamped `smidja/` tree (what `install.py` writes). **In
+Ymir itself the instance lives at `apps/smidja/`** — it moved out of the repo root
+so the smithy sits with the other apps, and its runtime data
+(`apps/smidja/smidja_data/`, gitignored) may also live at `$YMIR_HOME/smidja/`,
+which the runtime prefers when it exists. Every path in *this* repo points at
+`apps/smidja/`. The monorepo tracks neither the factory nor the engine: the
+factory is cloned from `zerwiz/smidja` into `apps/smidja-factory` by the
+installer's `apps` step, and the engine is stamped into `apps/smidja` from that
+clone's `templates/smidja` — exactly as `install.py` does for a target repo.
+
+## What it is
+
+*Agents plus code*: deterministic Python scripts own sequencing, retries, and
+acceptance; coding agents (Pi) work inside bounded **phases**; typed JSON
+**envelopes** carry context between them; everything streams into **SQLite** so it
+can be watched. *Agent proposes, code disposes.*
+
+## Install into a repo (idempotent)
+
+```bash
+cd <repo-root>            # e.g. $YMIR_ROOT
+uv run .agents/skills/smidja-factory/scripts/install.py
+```
+
+Stamps `smidja/` (the starter smithies + `smidja_modules/`), the prompt and harness
+engineering dirs, `smidja/smidja_smidja_config/smidja.config.yaml`, `.env.sample`,
+`justfile`, and `.gitignore` entries. Existing files are skipped unless `--force`.
+
+Not writable, it fails plainly: a `PermissionError` never escapes as a traceback —
+the script checks the target and returns exit 1 with the reason, so a failed
+stamp is legible rather than a stack of Python.
+
+There is **no separate CLI install**: the launcher `scripts/smidja` belongs to the
+`~/command` provenance repo; in Ymir use the `justfile` recipes or `uv run
+smidja/smidja_*.py` directly.
+
+## Roster & models — through pi's `models.json`
+
+- The roster: `smidja/smidja_smidja_config/smidja.config.yaml`. `defaults.model`
+  and each agent's `model:` are **`provider/id`**, resolved by **pi** from
+  `~/.pi/agent/models.json`. List what resolves with `pi --list-models`.
+- They are written as env-expandable placeholders so one backend can be chosen
+  without editing the roster: `${SMIDJA_LOCAL_MODEL:-…}` and per-role
+  `${SMIDJA_<ROLE>_MODEL:-…}`. `just` loads `.env` (`set dotenv-load`).
+- Example local model (llama.cpp router on `:8080`):
+  `llama-cpp/qwen3.6-35b-a3b@iq3_s`. Verify one-shot:
+  `pi -p --no-session --model "llama-cpp/qwen3.6-35b-a3b@iq3_s" "reply OK"`.
+- Keys: the starter roster names cloud providers (`google`, `fireworks`, `openai`)
+  → `OPENROUTER_API_KEY` / `FIREWORKS_API_KEY` / `OPENAI_API_KEY` in `.env`. A local
+  llama roster needs no key.
+
+## Run
+
+```bash
+# via justfile (repo root)
+just demo                       # two cheap read-only runs (scout), end to end
+just prompt "summarize this repo"
+just scout "where is auth handled"
+just sdlc "add a /health endpoint"
+just sessions                   # last 10 runs
+just phases <smidja_id>         # phase status in sequence
+just tail   <smidja_id>         # live event tail
+just procs  <smidja_id>         # live pids
+
+# raw
+uv run apps/smidja/smidja_prompt.py --agent scout "…"
+uv run apps/smidja/smidja_scout.py "…"
+```
+
+The watch recipes use **`python3 -c`** over the SQLite db (the `sqlite3` CLI is not
+installed on this machine) — do not reintroduce `sqlite3`.
+
+## The trace
+
+- DB: **`$YMIR_HOME/smidja/smidja.db`** (WAL; read-only readers never block a run).
+  `0003-private-data-separation` moved it out of the checkout; an in-repo
+  `apps/smidja/smidja_data/smidja.db` is the fallback. Created at the first run
+  (`bin/smidja-bootstrap.sh`); `scripts/start.sh` resolves the same pair.
+- Tables: `sessions` (`smidja_id, smidja_name, request, status, engineer,
+  started_at, ended_at, total_tokens, total_cost, archived`), `phases`
+  (`phase_id, smidja_id, seq, name, kind, owner, description, status, attempt,
+  retries, error, …`), `events` (`event_id, smidja_id, phase_id, parent_id, type,
+  name, payload_json, tokens, …`), `gate_results`, `envelopes`, `agent_sessions`,
+  `processes`.
+
+## Smíðja's eye — the trace visualizer
+
+- **Open at `http://127.0.0.1:8437/`.** One Bun server serves both the read-only
+  API (`bun:sqlite` over the trace db) **and** the built Vue UI from
+  `apps/visualizer/dist`. A Vite dev server on `:8438` is opt-in
+  (`SMIDJA_VIZ_DEV=1`) and is not needed for use.
+- **The carved cloth (2026-09-13).** The default theme is **fensalir** — the
+  landing page's stone/bone/bronze/blood and its three faces (Cormorant display,
+  Newsreader UI, IBM Plex Mono data), cut into `src/style.css` `:root` and into the
+  components' role colours (`var(--accent)`, `var(--green)`, `color-mix(…)`). The
+  titlebar toggle cycles **fensalir → classic → high-contrast**; `classic` (the
+  preserved deep-space look) and `high-contrast` (WCAG AAA) are deliberate
+  overrides and **win when chosen** — the cloth is the default, not a cage. A
+  saved `neutral` from an older build resolves to fensalir. The categorical
+  palettes (event dots, agent lanes in `src/lib/events.ts`) are data, not chrome,
+  and were re-cut onto the cloth while staying mutually distinct.
+- `scripts/start.sh` raises it (`CMD_DB=$YMIR_HOME/smidja/smidja.db`, else the
+  in-repo fallback; `PORT=8437`); `scripts/stop.sh` lowers it. Port overrides:
+  `SMIDJA_VIZ_API_PORT`.
+- Served under Hlidskjalf's **Sessions** gate via **Open visualizer**
+  (`VITE_VISUALIZER_URL`, default `http://127.0.0.1:8437`).
+- **Shared login, verified live (added 2026-09-13).** The server exposes
+  `GET /api/auth`, which forwards the browser's cookie to the gate's
+  `/api/session` and returns `{authed, login}`; `App.vue` shows a "Sign in" link
+  (to the gate) or "ᛉ <login>" from that live answer. It **never** reads a
+  session file — a token on disk would let a user look logged in when they are not.
+- **The Hall door (added 2026-09-13).** `App.vue`'s topbar carries a **To the
+  Hall** pill (rune Othala ᛟ, `.hall-btn`) beside the theme toggle: a new tab to
+  the Óðrerir Live Hall — `http://localhost:4322` when
+  `window.location.host` starts with `localhost`/`127.0.0.1`, otherwise
+  `https://hall.ymir.zerw.org`. It is a **plain anchor, not a `/api/desktop`**
+  launcher: the Hall is the landing's live board, not one of the three apps the
+  gate raises. Same door in Hlidskjalf's and Sessrúmnir's chrome.
+- See `docs/lore.md` §XIII.
+
+## In Hlidskjalf (the gate API)
+
+`apps/hlidskjalf/server` exposes the trace read-only:
+`/api/smidja/health · /api/smidja/sessions · /api/smidja/sessions/:id ·
+/api/smidja/decisions · /api/smidja/stats`. Four gates render it: **Sessions**,
+**Trace**, **Decisions**, **Stats**. Smíðja loads on its own track and is polled
+every 5s, so a finished run appears without a reload.
+
+## The observer (Huginn) — self-contained
+
+`bin/nornir-job-observer.sh` runs on the Nornir schedule (06:00). It reads **only
+Ymir's own runtime** — `docs/masterplan.md`, `.agents/agents`, `.agents/memory/well`,
+`workspace/memory/runes_audit.md`, **`$YMIR_HOME/smidja/smidja.db`**, and the
+read-only external worktree root — and writes only `state/observer.log` + Runes.
+There is **no `~/command` connection** anywhere in Ymir. Rune sources:
+`ymir.orders · ymir.agents · ymir.well · ymir.runes · smidja.runs ·
+yggdrasil.worktrees`. See `assets/nornir-jobs.md`.
+
+## Smoke test
+
+```bash
+SMIDJA_LOCAL_MODEL=llama-cpp/qwen3.6-35b-a3b@iq3_s \
+  uv run apps/smidja/smidja_prompt.py --agent scout \
+  "Reply with a single line: which top-level directories exist in this repo. Change nothing."
+```
+
+Expected: `2/2 phases passed`, a `smidja_id`, and the DB written. Then
+`just sessions` and `just phases <id>` read it, and
+`curl -s localhost:8437/api/health` reports `"sessions": N`.
+
+## Gotchas
+
+1. **`sqlite3` CLI is absent** — use `python3 -c` (the justfile already does).
+2. **Local models are served by the llama.cpp router `:8080`**, addressed as
+   `llama-cpp/<id>`; LM Studio `:1234` may be down. Confirm with `pi --list-models`.
+3. **The visualizer's local `node_modules` may be a partial bun install** — the API
+   still serves the prebuilt `dist/`, so open `:8437`, not `:8438`.
+4. **Never edit `apps/smidja/smidja_data/sessions/`** — it is the run record.
+5. **Protected files** (`apps/smidja/smidja_modules/`, `apps/smidja/smidja_*.py`, the config)
+   are enforced by `smidja_modules/permissions.py`; agents roll back unauthorized
+   changes. The smithy moved from the repo root `smidja/` to `apps/smidja/`
+   (Amendment C); `bin/smidja-bootstrap.sh` searches both so a stale layout cannot
+   break the DB seed again.
+6. New skills synthesized for the smithy are validated in Utgard (Gungnir, W0007)
+   before production.

package/.agents/skills/galdr-ymirsystem/schemas/toon-schemas.md

@@ -0,0 +1,190 @@
+# Galdr Tool Schemas — TOON Output Formats
+
+Galdr references these TOON (Token-Oriented Object Notation) schemas per tool type. All output converts to TOON at the output boundary; internal logic remains on JSON.
+
+## 1. Smíðja Orchestrator Schema
+
+```toon
+smidja:
+  status: open|closed|in-progress
+  phase: <phase-name>
+  progress: integer 0-100
+  next_action: string
+  utgard_sandbox: boolean
+  worktree: string
+  phase_complete: boolean
+```
+
+**Usage**: Python smidja scripts (`smidja_*.py`) — status, phase, progress tracking, utgard sandbox flag, worktree branch, phase completion.
+
+## 2. Brokk Crew Schema
+
+```toon
+crew:
+  status: active|paused|completed
+  agent_role: developer|marketer|researcher
+  worktree: string
+  utgard: boolean
+  sandboxed: boolean
+  session_id: string
+```
+
+**Usage**: Brokk Allfather communications — crew status, agent role, worktree branch, utgard flag, sandboxed flag, session identification.
+
+## 3. Galdr Skill Generator Schema
+
+```toon
+skill:
+  name: string Norse-skill-name
+  category: feature|bug|infrastructure|compliance|system
+  toon_output: boolean
+  principles: [1,2,3,4,5,6,7,8,9,10]
+  compliance_status: validated|pending
+  eindri_role: developer|marketer|researcher|none
+  utgard_sandbox: true
+```
+
+**Usage**: Galdr-crafter generated skills — skill name with Norse naming, category, TOON output flag, all 10 principles list, compliance status, Eindri role assignment, utgard sandbox flag.
+
+## 4. Eindri Sub-Agent Profile Schemas
+
+### Developer Profile
+```toon
+eindri:
+  role: developer
+  capabilities:
+    - code_synthesis
+    - refactoring
+    - test_writing
+    - cli_tools
+    - package_management
+  tools:
+    - Yggdrasil
+    - herder
+    - hermes_runner
+    - vector_db
+    - supabase
+  workspace_patterns:
+    - development/
+    - .agents/tools/
+    - .agents/skills/
+  security:
+    runs_in_utgard: true
+    utgard_network: none
+    utgard_resource_caps: true
+    yggdrasil_worktree: true
+    sandboxed: true
+```
+
+**Usage**: Galdr compliance checking — verifying new skills are compatible with developer Eindri worker profiles.
+
+### Marketer Profile
+```toon
+eindri:
+  role: marketer
+  capabilities:
+    - content_creation
+    - seo_optimization
+    - social_copy
+    - campaign_planning
+    - market_research
+  tools:
+    - vector_db
+    - supabase
+    - hermes_runner
+    - herder
+    - Yggdrasil
+  workspace_patterns:
+    - marketing/
+    - .agents/assets/templates/
+    - .agents/skills/
+  security:
+    runs_in_utgard: true
+    utgard_network: none
+    utgard_resource_caps: true
+    yggdrasil_worktree: true
+    sandboxed: true
+```
+
+**Usage**: Galdr compliance checking — verifying new skills compatible with marketer Eindri worker profiles.
+
+### Researcher Profile
+```toon
+eindri:
+  role: researcher
+  capabilities:
+    - rag_search
+    - web_search
+    - analysis
+    - summarization
+    - entity_extraction
+  tools:
+    - vector_db
+    - hermes_runner
+    - herder
+    - Yggdrasil
+    - supabase
+  workspace_patterns:
+    - development/
+    - .agents/memory/
+    - .agents/assets/templates/
+  security:
+    runs_in_utgard: true
+    utgard_network: none
+    utgard_resource_caps: true
+    yggdrasil_worktree: true
+    sandboxed: true
+```
+
+**Usage**: Galdr compliance checking — verifying new skills compatible with researcher Eindri worker profiles.
+
+## 5. Norse Aett Naming Schema
+
+```toon
+naming:
+  aett: galdr|val|skyr|bifr|heimd|gjallar|mimir|yggd
+  pattern: <aett>-<verb|noun|adjective>
+  validity: follows_Norse_mythology_convention
+  rejection_reason: if_not_following_aett_pattern
+```
+
+**Usage**: Galdr-crafter skill naming — ensuring new skill names follow the Norse aett pattern.
+
+## 6. Session Integration Schema
+
+```toon
+session:
+  hook: boolean (primary|secondary|none)
+  hook_installed: boolean
+  skill_loaded: boolean
+  ambient_context: boolean
+  context_richness: integer 1-10
+  last_session_start: ISO8601-timestamp
+```
+
+**Usage**: Galdr skill integration tracking — whether primary session hook or secondary skill is loaded, ambient context richness score, last session start timestamp.
+
+## 7. Compliance Gate Results Schema
+
+```toon
+compliance:
+  toe_output_test: pass|fail (with token_savings_percentage)
+  principle_compliance: pass|fail (per_principle)
+  norse_name_validity: valid|invalid (with_aett_pattern)
+  frame_integration: integrated|pending (with_skill_path)
+  mimirsbrunn_observation: observed|pending (with_episode_id)
+  eindri_compatibility: compatible|incompatible (with_profile_reference)
+  utgard_sandbox: compliant|non-compliant (with_declarations)
+```
+
+**Usage**: Galdr-compliance checker output — all five gate results with detailed per-principle assessment.
+
+## Conversion Rules
+
+1. **JSON → TOON**: At output boundary only; internal logic remains JSON
+2. **Token savings**: ~40% reduction versus equivalent JSON
+3. **Minimal schemas**: Default to 3-4 fields, not 10+
+4. **Empty states**: Always show total size "(truncated, N chars total)"
+5. **Help hints**: Include "--full" escape hatch reference
+6. **Error format**: Structured errors in TOON, never raw stack traces
+7. **Exit codes**: 0 = success (including no-ops), 1 = error, 2 = usage error

package/.agents/skills/galdr-ymirsystem/scripts/README.md

@@ -0,0 +1,45 @@
+# Galdr Scripts — compliance and TOON tooling
+
+Executable checks for the Galdr/Tyr gates. Both are Galdr-style: TOON output on
+stdout, structured errors, no prompts, `--version` fast path, idempotent.
+
+```
+scripts[2]{file,purpose}:
+  "toon-check.py","validate TOON blocks (header count/fields vs rows; ... = elided)"
+  "compliance-check.sh","run all gates: toon, naming, mocks, syntax, json, sync"
+```
+
+## Usage
+
+```
+python3 .agents/skills/galdr-ymirsystem/scripts/toon-check.py <file-or-dir> [...] [--quiet] [--json]
+bash    .agents/skills/galdr-ymirsystem/scripts/compliance-check.sh [--quiet] [--json]
+```
+
+Exit codes: `0` success, `1` violations, `2` usage error.
+
+## What compliance-check.sh enforces
+
+```
+checks[8]{id,what}:
+  "toon","TOON blocks valid in galdr SKILL.md + assets + tyr SKILL.md + AGENTS.md"
+  "naming","no imported terms (Allfather/Yggdrasil/Eindri) in AGENTS.md + bin/ (observer exempt)"
+  "mocks","no mock/stub/placeholder/TODO in the shipped runtime (bin/)"
+  "syntax","bash -n on bin/*.sh; node --check on .opencode/plugins/*.js"
+  "json","every runtime JSON parses"
+  "sync","galdr-ymirsystem/assets mirrors tyr-check/assets"
+```
+
+## TOON block convention
+
+```
+type[count]{field1,field2}:
+  "value","value"
+```
+
+A row of `...` marks an elided excerpt and is reported `ELIDED` (not a failure).
+
+## Maintaining this
+
+- **Owner:** Brokk. **Router:** `.agents/skills/galdr-ymirsystem/SKILL.md`.
+- Extend a gate by adding to `compliance-check.sh` and a row to its `checks` block.

package/.agents/skills/galdr-ymirsystem/scripts/bench-one.sh

@@ -0,0 +1,248 @@
+#!/usr/bin/env bash
+# bench-one.sh — benchmark ONE local GGUF model, end to end, portably.
+#
+# It starts its OWN throwaway single-model llama-server on a scratch port,
+# measures it, and kills it. It never touches a running service, and it needs
+# nothing from the testing host but a llama-server binary and a .gguf.
+#
+# Usage:
+#   bench-one.sh <model.gguf | model-id> [options]
+#
+# Options:
+#   --ctx N         context to load            (default 32768)
+#   --kv TYPE       KV cache type for BOTH k and v (default f16; q8_0 halves it)
+#   --ngl N         layers on GPU              (default 999 = as many as fit)
+#   --batch N       batch and ubatch           (default 2048)
+#   --threads N     CPU threads                (default: all cores)
+#   --device NAME   pin a device (CUDA0, Vulkan0, …)
+#   --server PATH   llama-server binary        (default $LLAMA_SERVER, else PATH)
+#   --port N        scratch port               (default: a free one)
+#   --prompt FILE   request JSON               (default: built-in ~2k-token prompt)
+#   --max-tokens N  completion length          (default 128)
+#   --keep          leave the server running after the run
+#   -h, --help      this text
+#
+# A bare model-id is only a convenience: if `llama-models` is on PATH (a machine
+# registry from a Ymir host) its gguf/ctx/kv are read READ-ONLY so the bench
+# matches what that host would serve. With no registry, pass a path to a .gguf.
+#
+# The 8 rules this follows are in ../SKILL.md; the measurements you take belong
+# in YOUR host's Hoard (../METHOD.md → "Where the data lives").
+set -euo pipefail
+
+CTX=32768; KV=f16; NGL=999; BATCH=2048; THREADS=""; DEVICE=""; SERVER=""
+PORT=""; PROMPT_JSON=""; MAX_TOKENS=128; KEEP=0; MODEL=""
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --ctx)        CTX=$2; shift 2 ;;
+    --kv)         KV=$2; shift 2 ;;
+    --ngl)        NGL=$2; shift 2 ;;
+    --batch)      BATCH=$2; shift 2 ;;
+    --threads)    THREADS=$2; shift 2 ;;
+    --device)     DEVICE=$2; shift 2 ;;
+    --server)     SERVER=$2; shift 2 ;;
+    --port)       PORT=$2; shift 2 ;;
+    --prompt)     PROMPT_JSON=$2; shift 2 ;;
+    --max-tokens) MAX_TOKENS=$2; shift 2 ;;
+    --keep)       KEEP=1; shift ;;
+    -h|--help)    sed -n '2,30p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;;
+    -*)           echo "unknown option: $1 (try --help)" >&2; exit 2 ;;
+    *)            MODEL=$1; shift ;;
+  esac
+done
+[ -n "$MODEL" ] || { echo "usage: bench-one.sh <model.gguf|model-id> [options]  (--help)" >&2; exit 2; }
+
+# ---- resolve the server --------------------------------------------------
+if [ -z "$SERVER" ]; then SERVER="${LLAMA_SERVER:-$(command -v llama-server || true)}"; fi
+[ -n "$SERVER" ] && [ -x "$SERVER" ] || {
+  echo "✗ no llama-server found. Install one, or pass --server PATH (or set \$LLAMA_SERVER)." >&2; exit 1; }
+
+# ---- resolve the model ---------------------------------------------------
+GGUF="$MODEL"
+if [ ! -f "$GGUF" ]; then
+  if command -v llama-models >/dev/null 2>&1; then
+    g=$(llama-models get "$MODEL" gguf 2>/dev/null || true)
+    md=$(llama-models defaults 2>/dev/null | cut -d'|' -f2)
+    [ -n "$g" ] && GGUF="$md/$g"
+    # only adopt registry values the user did not set explicitly
+    [ "$CTX" = "32768" ] && { v=$(llama-models get "$MODEL" ctx); [ -n "$v" ] && CTX=$v; }
+    [ "$KV" = "f16" ]   && { v=$(llama-models get "$MODEL" kv);  [ -n "$v" ] && KV=$v; }
+    [ "$NGL" = "999" ]  && { v=$(llama-models get "$MODEL" ngl); [ -n "$v" ] && NGL=$v; }
+    [ -z "$THREADS" ]   && { v=$(llama-models get "$MODEL" threads); [ -n "$v" ] && THREADS=$v; }
+  fi
+fi
+[ -f "$GGUF" ] || { echo "✗ not a file and not a known model id: $MODEL" >&2; exit 2; }
+# --- portable primitives -----------------------------------------------------
+# This script ships standalone, so it carries its own OS handling rather than
+# depending on a Ymir checkout. macOS/BSD differ on all three counts below.
+cpu_count() {
+  if command -v nproc >/dev/null 2>&1; then nproc
+  elif command -v sysctl >/dev/null 2>&1 && sysctl -n hw.ncpu >/dev/null 2>&1; then sysctl -n hw.ncpu
+  elif command -v getconf >/dev/null 2>&1; then getconf _NPROCESSORS_ONLN 2>/dev/null || printf '4'
+  else printf '4'; fi
+}
+now_ns() {  # epoch milliseconds*1e6; BSD date has no %N
+  local s n
+  s=$(date +%s 2>/dev/null) || s=0
+  n=$(date +%N 2>/dev/null)
+  case "$n" in ''|*[!0-9]*) n=000000000 ;; esac
+  printf '%s%s' "$s" "$n"
+}
+gpu_tool() {  # nvidia | rocm | none
+  if command -v nvidia-smi >/dev/null 2>&1; then printf 'nvidia'
+  elif command -v rocm-smi >/dev/null 2>&1; then printf 'rocm'
+  else printf 'none'; fi
+}
+gpu_name() {
+  case "$(gpu_tool)" in
+    nvidia) nvidia-smi --query-gpu=name --format=csv,noheader 2>/dev/null | head -1 ;;
+    rocm)   rocm-smi --showproductname 2>/dev/null | head -2 | tr '\n' ' ' ;;
+    *)      uname -s 2>/dev/null | grep -q Darwin && printf 'Apple (unified memory)' || printf 'cpu-only' ;;
+  esac
+}
+[ -n "$THREADS" ] || THREADS=$(cpu_count)
+[ -n "$PORT" ] || PORT=$(( (RANDOM % 800) + 9200 ))
+
+TMP=$(mktemp -d "${TMPDIR:-/tmp}/bench.XXXXXX")
+LOG="$TMP/server.log"; SRV_PID=""
+cleanup() {
+  # Signal ONLY the server this script started — never anyone else's.
+  if [ "$KEEP" = "0" ] && [ -n "$SRV_PID" ] && kill -0 "$SRV_PID" 2>/dev/null; then
+    kill "$SRV_PID" 2>/dev/null || true
+    for _ in 1 2 3 4 5 6 7 8 9 10; do kill -0 "$SRV_PID" 2>/dev/null || break; sleep 1; done
+    kill -0 "$SRV_PID" 2>/dev/null && echo "  ⚠ bench server pid $SRV_PID ignored SIGTERM" >&2
+  fi
+  rm -rf "$TMP"
+}
+trap cleanup EXIT
+command -v curl >/dev/null || { echo "✗ curl is required" >&2; exit 1; }
+
+gpu_mem() {  # device memory in use (MiB), or "?" when the host does not expose it
+  case "$(gpu_tool)" in
+    nvidia) nvidia-smi --query-gpu=memory.used --format=csv,noheader,nounits 2>/dev/null | head -1 || printf '?' ;;
+    rocm)   rocm-smi --showmemuse 2>/dev/null | grep -oE '[0-9]+' | head -1 || printf '?' ;;
+    *)      printf '?' ;;
+  esac
+}
+
+echo "=== [1/7] server ==="
+echo "  $SERVER"
+DEVS=$("$SERVER" --list-devices 2>&1 | grep -icE "CUDA|Vulkan|ROCm|Metal" || true)
+if [ "$DEVS" -eq 0 ]; then
+  echo "  ⚠ this build reports NO GPU device — you are about to measure the CPU."
+  echo "    That is a valid CPU test; it is not a GPU measurement."
+else
+  "$SERVER" --list-devices 2>&1 | grep -iE "CUDA|Vulkan|ROCm|Metal" | sed 's/^/  /'
+fi
+echo "=== [2/7] configuration ==="
+echo "  model: $GGUF"
+echo "  ctx=$CTX  kv=$KV (both K and V)  ngl=$NGL  batch=$BATCH  threads=$THREADS${DEVICE:+  device=$DEVICE}"
+echo "  note: keep K and V identical. A build that lacks the kernel for your KV"
+echo "        type can silently move attention to the CPU (see ../METHOD.md)."
+echo "  VRAM in use before start: $(gpu_mem) MiB"
+
+echo "=== [3/7] start a throwaway server on :$PORT ==="
+ARGS=(-m "$GGUF" -ngl "$NGL" --flash-attn on
+      --cache-type-k "$KV" --cache-type-v "$KV"
+      -c "$CTX" -b "$BATCH" -ub "$BATCH" -t "$THREADS" --jinja --temp 0 --seed 42
+      -np 1 --host 127.0.0.1 --port "$PORT")
+[ -n "$DEVICE" ] && ARGS+=(--device "$DEVICE")
+"$SERVER" "${ARGS[@]}" > "$LOG" 2>&1 &
+SRV_PID=$!
+for i in $(seq 1 120); do
+  sleep 2
+  grep -qE "model loaded|server is listening" "$LOG" 2>/dev/null && { echo "  loaded in $((i*2))s (pid $SRV_PID)"; break; }
+  grep -qE "out of memory|failed to allocate|error loading model" "$LOG" 2>/dev/null && {
+    echo "✗ failed to load — lower --ctx, use a smaller --kv, or lower --ngl. Last lines:" >&2
+    tail -6 "$LOG" >&2; exit 1; }
+  kill -0 "$SRV_PID" 2>/dev/null || { echo "✗ server exited during load:" >&2; tail -8 "$LOG" >&2; exit 1; }
+done
+grep -qE "model loaded|server is listening" "$LOG" || { echo "✗ timed out waiting for load" >&2; tail -8 "$LOG" >&2; exit 1; }
+echo "  VRAM after load: $(gpu_mem) MiB"
+
+echo "=== [4/7] verify the loaded context (from the server, not the flags) ==="
+curl -s "http://127.0.0.1:$PORT/props" | python3 -c "
+import sys, json
+try:
+    d = json.load(sys.stdin)
+    g = d.get('default_generation_settings', {})
+    print('  n_ctx:', g.get('n_ctx'))
+except Exception: print('  (/props unreadable — record the configured ctx instead)')" 2>/dev/null || true
+
+echo "=== [5/7] build the timed request ==="
+if [ -n "$PROMPT_JSON" ]; then REQ="$PROMPT_JSON"; echo "  using $PROMPT_JSON"
+else
+  REQ="$TMP/req.json"
+  python3 - "$REQ" "$MAX_TOKENS" <<'PYEOF'
+import json, sys
+body = "def f(n):\n    return n if n < 2 else f(n-1) + f(n-2)\n"
+text = (body * 330)
+json.dump({"model": "local",
+           "messages": [{"role": "user",
+                         "content": "Explain this code in full detail, including time and space complexity.\n\n" + text}],
+           "max_tokens": int(sys.argv[2]), "temperature": 0, "seed": 42, "stream": False},
+          open(sys.argv[1], "w"))
+print("  built a prompt of roughly", len(text)//4, "tokens")
+PYEOF
+fi
+
+echo "=== [6/7] warm the GPU, then time a cold-context run ==="
+python3 -c "
+import json; json.dump({'model':'local','messages':[{'role':'user','content':'hi'}],'max_tokens':8,'temperature':0}, open('$TMP/warm.json','w'))"
+curl -s "http://127.0.0.1:$PORT/v1/chat/completions" -H 'Content-Type: application/json' -d @"$TMP/warm.json" -o /dev/null
+case "$(gpu_tool)" in
+  nvidia) nvidia-smi --query-gpu=clocks.sm,power.draw --format=csv,noheader | sed 's/^/  after warm: /' ;;
+  *)      echo "  (no NVIDIA telemetry on this host — util/power will be omitted)" ;;
+esac
+( case "$(gpu_tool)" in
+    nvidia) for i in $(seq 1 120); do
+              nvidia-smi --query-gpu=utilization.gpu,power.draw,memory.used --format=csv,noheader >> "$TMP/gpu.txt"
+              sleep 1
+            done ;;
+  esac ) & SAMPLER=$!
+T0=$(now_ns)
+curl -s -m 1800 "http://127.0.0.1:$PORT/v1/chat/completions" -H 'Content-Type: application/json' -d @"$REQ" -o "$TMP/out.json"
+T1=$(now_ns)
+kill "$SAMPLER" 2>/dev/null || true; wait "$SAMPLER" 2>/dev/null || true
+
+echo "=== [7/7] results ==="
+python3 - "$TMP/out.json" "$T1" "$T0" "$CTX" "$KV" "$TMP/gpu.txt" <<'PYEOF'
+import json, os, sys
+out, t1, t0, ctx, kv, gpufile = sys.argv[1:7]
+try:
+    d = json.load(open(out))
+except Exception:
+    print("  ✗ no parseable response — check the server log"); raise SystemExit(0)
+if "error" in d:
+    print("  ✗ server error:", str(d["error"])[:300]); raise SystemExit(0)
+t = d.get("timings", {}) or {}
+wall = (float(t1) - float(t0)) / 1e9
+pt = (d.get("usage") or {}).get("prompt_tokens")
+print(f"  wall           : {wall:.1f}s")
+print(f"  prompt_tokens  : {pt}")
+print(f"  prefill        : {t.get('prompt_per_second', 0):.1f} t/s")
+print(f"  decode         : {t.get('predicted_per_second', 0):.1f} t/s")
+print(f"  cache_n        : {t.get('cache_n')}   (0 = true cold prefill)")
+if os.path.exists(gpufile):
+    rows = [l.strip().split(', ') for l in open(gpufile) if l.strip()]
+    if rows:
+        util = max(int(r[0].split()[0]) for r in rows)
+        vram = max(int(r[2].split()[0]) for r in rows)
+        pwr  = max(float(r[1].split()[0]) for r in rows)
+        print(f"  peak GPU       : {util}% util, {vram} MiB, {pwr:.0f} W")
+        if util < 50:
+            print("  ⚠ utilisation stayed under 50% — the GPU never ramped, or the run was CPU-bound.")
+print()
+print("  RECORD THIS (your host's Hoard — see ../METHOD.md):")
+print(f"    model=<name> quant=<quant> ctx={ctx} kv={kv} "
+      f"prefill={t.get('prompt_per_second',0):.1f} decode={t.get('predicted_per_second',0):.1f} "
+      f"prompt_tokens={pt} wall={wall:.1f}s")
+print("  Always record the context the run was measured at.")
+PYEOF
+
+if [ "$KEEP" = "1" ]; then echo "=== --keep: server left running on :$PORT (pid $SRV_PID) ==="; exit 0; fi
+echo "=== teardown ==="
+kill "$SRV_PID" 2>/dev/null || true; wait "$SRV_PID" 2>/dev/null || true; SRV_PID=""
+sleep 1
+echo "  VRAM after: $(gpu_mem) MiB"