@zenera/cli 1.1.23 → 1.1.25

package/templates/editor/.github/skills/zen-sandbox-capacity/references/loadtest.md

@@ -0,0 +1,181 @@
+# Load-testing: separating the machine from the endpoint
+
+`preflight_sandbox.sh` answers a static question — does the arithmetic fit. This
+answers a different one: the batch is slow or dying and you do not yet know
+what is causing it. It costs minutes rather than seconds, so reach for it only
+when the gate has already passed and the symptom is still there.
+
+The method below is written from a run that did work. It is a method, not a
+script to paste: the commands and the index names belong to whatever project
+you are in. Build the harness to fit, and throw it away afterwards.
+
+## Two hypotheses, and why you cannot tell them apart by staring
+
+A slow or killed batch has two plausible causes and they present identically at
+the call site — a long wall clock, then a timeout:
+
+|        | Hypothesis                                    | What it predicts                                                        |
+| ------ | --------------------------------------------- | ----------------------------------------------------------------------- |
+| **H1** | The podman VM is under-provisioned            | Latency depends on _where_ the command runs, and not on what kind it is |
+| **H2** | The embedding or model endpoint is throttling | Latency depends on _what kind_ of call it is, and not on where it runs  |
+
+They are distinguishable because they are separable. H1 lives in the container
+boundary, H2 lives in the network call, and a single 2x2 tells you which line
+the variance sits on.
+
+## The 2x2
+
+Two factors, crossed, at several concurrencies:
+
+- **where** — `host` (the command run directly) against `container`
+  (the same command inside the sandbox)
+- **kind** — `local` (touches only the index, makes no network call) against
+  `embed` (makes a provider call)
+
+Pick two or three probes of each kind. For a `zen rag` index these fall out
+naturally:
+
+| Probe    | kind  | Why it is in the set                                                   |
+| -------- | ----- | ---------------------------------------------------------------------- |
+| `stats`  | local | Opens the index and reads the manifest; nearly no work                 |
+| `grep`   | local | Reads the whole index through the page cache; the heaviest local probe |
+| `list`   | local | Walks the node table                                                   |
+| `search` | embed | The query is embedded before anything is read                          |
+| `schema` | embed | A second embed path, to show the first was not a fluke                 |
+
+Run each cell at concurrency 1, 2, 4 and 8, several replicas each, and write one
+row per run. Concurrency 1 is not optional: it is the baseline every other row
+is read against, and it is also the figure `--peak-rss` wants.
+
+A useful row shape, and one that a later `awk` can group without parsing:
+
+```
+probe,kind,where,concurrency,replica,seconds,exit_code
+```
+
+Keep `exit_code`. A cell that got faster because half its replicas were killed
+at 137 is not a fast cell, and a mean that silently includes them will tell you
+the opposite of the truth.
+
+## Reading the grid
+
+Compare means within a `probe`, across `where` and `concurrency`:
+
+- **container rows slow, host rows fast** — H1, the podman VM
+- **both slow, but only on `kind=embed`** — H2, the embedding API
+- **both slow, including `kind=local`** — neither: the index itself
+- **container rows carry the non-zero exit codes** — H1, and specifically memory;
+  go back to the gate and read `admission` rather than running anything else
+
+The run this skill was written from produced the first of those, unambiguously:
+`grep` at concurrency 8 took 5.5 s on the host and 105-118 s in the container,
+with three of the eight replicas exiting 137.
+
+## When the finger points at the endpoint
+
+If the grid implicates `kind=embed`, test the endpoint on its own before
+believing it. Drive one model reference at rising concurrency — 1, 2, 4, 8, 16 —
+and classify each reply rather than timing it alone:
+
+```
+ref,concurrency,replica,seconds,exit_code,verdict
+```
+
+Classify from the reply body, in this order, because a throttle can arrive
+wearing a 200:
+
+| verdict     | Recognised by                                                           |
+| ----------- | ----------------------------------------------------------------------- |
+| `throttled` | `429`, `RESOURCE_EXHAUSTED`, `rate limit`, `quota`, `too many requests` |
+| `refused`   | the model declined the request                                          |
+| `blocked`   | a safety or policy filter fired                                         |
+| `no-answer` | empty body, or a body with no content                                   |
+| `ok`        | a substantive reply                                                     |
+| `other`     | anything left                                                           |
+
+Keep the raw replies on disk. A verdict you cannot go back and check is a guess
+with a column heading.
+
+Then:
+
+- **mean flat as concurrency rises, nothing `throttled`** — H2 is out. The
+  endpoint is not your problem; go back to H1.
+- **mean climbing, nothing `throttled`** — the endpoint serialises. Lower
+  concurrency will not lose you throughput, so lower it.
+- **anything `throttled`** — H2 confirmed. Stop here.
+
+A confirmed throttle is the end of this document's usefulness. Rate limits are a
+provider matter — quota, region, a different reference, a backoff — and nothing
+in this skill or in the sandbox will move them. Hand it off; do not spend a
+fine-tuning round on it.
+
+The run this skill was written from found embedding calls roughly 2x slower at
+concurrency 8 and **zero** throttled replies. That is what refuted H2, and it is
+the reason the sentence about provider tolerance in `zen-finetune` is not the
+whole story.
+
+## A skeleton
+
+Substitute your own index names and model reference. Keep the structure — the
+value is in the grid, not in the timing code.
+
+```bash
+#!/usr/bin/env bash
+set -eu
+stamp="$(date +%Y%m%d-%H%M%S)"
+out=".tmp/loadtest/rag-${stamp}.csv"
+mkdir -p "$(dirname "$out")"
+echo "probe,kind,where,concurrency,replica,seconds,exit_code" > "$out"
+
+INDEX=@INDEX@                        # e.g. docs
+IMAGE="$(zen sandbox status | awk '$1 == "image" { print $2 }')"
+
+run_one() {                          # probe kind where concurrency replica
+    case "$1" in
+        stats)  cmd="zen rag $INDEX stats" ;;
+        grep)   cmd="zen rag $INDEX grep zzzz-not-present" ;;
+        search) cmd="zen rag $INDEX search 'how does this work'" ;;
+    esac
+    start="$(date +%s)"
+    if [ "$3" = host ]; then
+        sh -c "$cmd" > /dev/null 2>&1 || true
+        rc=$?
+    else
+        podman run --rm -v "$PWD:/work:ro" -w /work --entrypoint="" \
+            "$IMAGE" sh -c "$cmd" > /dev/null 2>&1 || true
+        rc=$?
+    fi
+    echo "$1,$2,$3,$4,$5,$(($(date +%s) - start)),$rc" >> "$out"
+}
+
+for c in 1 2 4 8; do
+    for where in host container; do
+        for spec in "stats local" "grep local" "search embed"; do
+            set -- ${=spec}          # zsh does not split unquoted expansions
+            for r in $(seq 1 "$c"); do run_one "$1" "$2" "$where" "$c" "$r" & done
+            wait
+        done
+    done
+done
+
+echo "wrote $out"
+```
+
+Two things this deliberately does not do, and neither should yours:
+
+- It does not use `python3 -c`, `node -e` or any other inline interpreter. That
+  is a house rule, and a load test is not an exemption from it.
+- It does not mutate the machine. If the answer is "resize", say so and let a
+  person run `podman machine set` — see the main skill for why stopping the
+  machine is not free.
+
+Whole-second timing is coarse for the fast cells. If you need better, use a
+timing utility the image already has; do not reach for an inline interpreter to
+get microseconds you will not read.
+
+## Afterwards
+
+Whatever the grid says, write the finding down where the next round will see it,
+together with the machine spec it was measured on. A load test that is not
+recorded next to its `vm memory` figure will be re-run by the next person from
+scratch, because they will have no way to know whether it still applies.

package/templates/editor/.github/skills/zen-sandbox-capacity/scripts/preflight_sandbox.sh

@@ -0,0 +1,457 @@
+#!/usr/bin/env bash
+#
+# Whether this machine can run the batch you are about to start.
+#
+#   preflight_sandbox.sh --concurrency 8      the gate: exit 0 fits, 1 does not
+#   preflight_sandbox.sh --skip-probe         the free half, in about a second
+#   preflight_sandbox.sh --peak-rss 912       use a figure you measured yourself
+#
+# Containers do not run on the host. On macOS they run inside one podman virtual
+# machine whose memory is fixed, is not the host's, and is 2 GiB by default — so
+# eight concurrent containers over a multi-gigabyte index thrash and are killed
+# while the host sits nearly empty. The symptom is exit 124, which everybody
+# already has a theory about, so the VM is the last thing anyone looks at.
+#
+# Two bounds are reported, because they fail for different reasons:
+#
+#   admission     concurrency x sandbox.memory <= vm_memory
+#                 what podman will permit to be allocated. Static and free.
+#   working set   largest_index + concurrency x peak_rss + 1 GiB <= vm_memory
+#                 what the work actually wants. The index is counted once: it
+#                 is page cache in the VM and every container shares it.
+#
+# It measures; it never changes anything. `podman machine set` needs the machine
+# stopped, which kills every running container, so that command is printed and
+# handed over rather than run.
+#
+# Exit 0 sufficient, 1 insufficient, 3 not applicable. See
+# .github/skills/zen-sandbox-capacity/SKILL.md.
+
+set -eu
+
+# Taken before the cd, or a relative $0 stops naming this file.
+SELF="$(cd "$(dirname "$0")" && pwd)/$(basename "$0")"
+cd "$(dirname "$0")/../../../.."
+
+CONCURRENCY=1
+ASSETS=assets
+SKIP_PROBE=0
+PEAK_RSS=0
+AS_JSON=0
+PROBE_TIMEOUT=25
+
+# A node-based agent container costs this much before it has done anything, so
+# a generic probe that measures less than it has measured the probe, not the
+# agent. Override with a real figure using --peak-rss.
+# A gate that guesses should guess high: guessing low returns a cheerful "ok"
+# and the batch dies anyway. 1024 is a round number just above the only figure
+# anyone has actually measured here (912 MiB), so an unprobed answer errs
+# toward refusing. Pass --peak-rss with a real number and this is unused.
+PEAK_FLOOR_MIB=1024
+HEADROOM_MIB=1024
+
+# What zen scaffolds when `sandbox:` names neither, and what `strict` uses.
+DEFAULT_CONTAINER_MIB=4096
+STRICT_CONTAINER_MIB=2048
+
+usage() {
+    sed -n '3,7p' "$SELF" | sed 's/^# \{0,1\}//'
+    echo
+    echo "  --concurrency <n>   batch width to answer for; default $CONCURRENCY"
+    echo "  --assets <dir>      where the indexes are; default $ASSETS"
+    echo "  --skip-probe        admission bound only; starts no container"
+    echo "  --peak-rss <MiB>    a measured per-container figure, instead of sampling"
+    echo "  --json              the same answer as data"
+}
+
+while [ $# -gt 0 ]; do
+    case "$1" in
+        --concurrency | -c) CONCURRENCY="${2:?--concurrency needs a number}"; shift 2 ;;
+        --assets) ASSETS="${2:?--assets needs a directory}"; shift 2 ;;
+        --peak-rss) PEAK_RSS="${2:?--peak-rss needs a number of MiB}"; shift 2 ;;
+        --skip-probe) SKIP_PROBE=1; shift ;;
+        --json) AS_JSON=1; shift ;;
+        -h | --help) usage; exit 0 ;;
+        *)
+            echo "preflight_sandbox.sh: unknown argument $1" >&2
+            usage >&2
+            exit 2
+            ;;
+    esac
+done
+
+case "$CONCURRENCY$PEAK_RSS" in
+    *[!0-9]*)
+        echo "preflight_sandbox.sh: --concurrency and --peak-rss take whole numbers" >&2
+        exit 2
+        ;;
+esac
+if [ "$CONCURRENCY" -lt 1 ]; then
+    echo "preflight_sandbox.sh: --concurrency must be at least 1" >&2
+    exit 2
+fi
+
+NOTES=""
+note() {
+    NOTES="$NOTES$1
+"
+}
+
+mib() { awk -v b="$1" 'BEGIN { printf "%d", b / 1048576 }'; }
+gib() { awk -v m="$1" 'BEGIN { printf "%.1f", m / 1024 }'; }
+
+# Everything below prints through here, so --json can suppress the prose without
+# every site having to know about it.
+say() {
+    if [ "$AS_JSON" -eq 0 ]; then printf '%s\n' "$1"; fi
+}
+
+# ---------------------------------------------------------------------------
+# 1. Does this apply at all
+#
+# Three ways not to. Each is a real answer and none of them is a failure, so
+# they share exit 3 and each says what could not be checked rather than what
+# went wrong.
+# ---------------------------------------------------------------------------
+
+not_applicable() {
+    if [ "$AS_JSON" -eq 1 ]; then
+        printf '{"applicable":false,"reason":%s}\n' "\"$1\""
+    else
+        echo "not applicable: $1"
+        if [ -n "$2" ]; then echo "  $2"; fi
+    fi
+    exit 3
+}
+
+if ! command -v podman > /dev/null 2>&1; then
+    not_applicable "podman is not on PATH" \
+        "nothing here is measurable; install podman, or run \`zen sandbox up\`"
+fi
+
+if [ "$(uname -s)" = "Linux" ]; then
+    not_applicable "podman is native on Linux — there is no VM to be the ceiling" \
+        "containers here are bounded by the host and by cgroups, not by a machine"
+fi
+
+CONF=""
+for candidate in agents.yaml agents.yml agents/agents.yaml agents/agents.yml; do
+    if [ -f "$candidate" ]; then CONF="$candidate"; break; fi
+done
+if [ -z "$CONF" ]; then
+    not_applicable "no agents.yaml in $PWD" \
+        "run this from a project, or from anywhere inside one"
+fi
+if ! grep -Eq 'sandbox:(\*|run_command|run_command_background|read_command_output|stop_command)' "$CONF"; then
+    not_applicable "no agent in $CONF holds a sandbox tool" \
+        "no container is ever started, so capacity cannot be the fault"
+fi
+
+# ---------------------------------------------------------------------------
+# 2. The host
+#
+# It bounds what the VM may be given and it is where `zen run batch` itself
+# runs, which has been OOM-killed in its own right. Free pages are the ones
+# that could be handed to a resize today.
+# ---------------------------------------------------------------------------
+
+HOST_MIB="$(mib "$(sysctl -n hw.memsize 2> /dev/null || echo 0)")"
+HOST_FREE_MIB=0
+if command -v vm_stat > /dev/null 2>&1; then
+    HOST_FREE_MIB="$(
+        vm_stat 2> /dev/null | awk '
+            /page size of/ { gsub(/[^0-9]/, "", $8); ps = $8 }
+            /Pages free/ || /Pages inactive/ { gsub(/[^0-9]/, "", $NF); p += $NF }
+            END { printf "%d", (ps ? ps : 4096) * p / 1048576 }' || true
+    )"
+fi
+
+# ---------------------------------------------------------------------------
+# 3. The VM — the ceiling
+#
+# `podman info` is the authority because it reports the machine as it is
+# running, swap included. A machine that is stopped cannot answer, so the
+# configured size from `machine list` stands in and is labelled as such.
+# ---------------------------------------------------------------------------
+
+VM_MIB=0
+VM_SWAP_MIB=0
+VM_CPUS=0
+VM_NAME=""
+VM_STATE=running
+
+INFO="$(podman info --format '{{.Host.MemTotal}} {{.Host.SwapTotal}} {{.Host.CPUs}}' 2> /dev/null || true)"
+case "$INFO" in
+    [0-9]*)
+        VM_MIB="$(mib "$(echo "$INFO" | awk '{print $1}')")"
+        VM_SWAP_MIB="$(mib "$(echo "$INFO" | awk '{print $2}')")"
+        VM_CPUS="$(echo "$INFO" | awk '{print $3}')"
+        ;;
+    *) VM_STATE=stopped ;;
+esac
+
+# `Memory` is bytes on podman 4 and a string like `2GiB` on podman 5, so it is
+# normalised rather than trusted. Read whatever the state, for the name.
+MACHINE="$(podman machine list --format '{{.Name}} {{.Memory}} {{.CPUs}} {{.Running}}' 2> /dev/null | head -1 || true)"
+if [ -n "$MACHINE" ]; then
+    # `list` marks the default machine with a trailing asterisk.
+    VM_NAME="$(echo "$MACHINE" | awk '{print $1}' | sed 's/\*$//')"
+    if [ "$VM_STATE" = stopped ]; then
+        VM_MIB="$(
+            echo "$MACHINE" | awk '{
+                v = $2
+                n = v + 0
+                if (v ~ /GiB|GB|[Gg]$/) n = n * 1024
+                else if (v ~ /MiB|MB|[Mm]$/) n = n
+                else if (n > 1073741823) n = n / 1048576
+                printf "%d", n
+            }' || true
+        )"
+        VM_CPUS="$(echo "$MACHINE" | awk '{print $3}')"
+    fi
+fi
+
+if [ "$VM_STATE" = stopped ]; then
+    note "the podman machine is not running, so these are its configured sizes, not live ones"
+    note "  start it to measure: podman machine start"
+fi
+if [ "$VM_MIB" -eq 0 ]; then
+    not_applicable "podman could not report the machine's memory" \
+        "try \`podman machine start\`, then run this again"
+fi
+
+# ---------------------------------------------------------------------------
+# 4. The container cap, out of agents.yaml
+#
+# A numeric `memory:` can only be the sandbox's: the memory *graph* block takes
+# a directory and an embedding, and an agent's binding takes a boolean or a map.
+# Per-agent overrides are read too, and the largest wins — it is the one that
+# decides whether the sum fits.
+# ---------------------------------------------------------------------------
+
+CONTAINER_MIB="$(
+    grep -E '^[[:space:]]+memory:[[:space:]]*[0-9]+[[:space:]]*(#.*)?$' "$CONF" 2> /dev/null \
+        | sed -E 's/.*memory:[[:space:]]*([0-9]+).*/\1/' | sort -n | tail -1 || true
+)"
+CONTAINER_SOURCE="$CONF"
+if [ -z "$CONTAINER_MIB" ]; then
+    if grep -Eq '^[[:space:]]+hardening:[[:space:]]*strict' "$CONF"; then
+        CONTAINER_MIB="$STRICT_CONTAINER_MIB"
+        CONTAINER_SOURCE="default (strict)"
+    else
+        CONTAINER_MIB="$DEFAULT_CONTAINER_MIB"
+        CONTAINER_SOURCE="default"
+    fi
+fi
+
+CONTAINER_CPUS="$(
+    grep -E '^[[:space:]]+cpus:[[:space:]]*[0-9]+' "$CONF" 2> /dev/null \
+        | sed -E 's/.*cpus:[[:space:]]*([0-9]+).*/\1/' | sort -n | tail -1 || true
+)"
+CONTAINER_CPUS="${CONTAINER_CPUS:-4}"
+
+if [ "$CONTAINER_MIB" -eq 0 ]; then
+    note "sandbox.memory is 0 — unconstrained, so one container may take the whole VM"
+    CONTAINER_MIB="$VM_MIB"
+fi
+
+# ---------------------------------------------------------------------------
+# 5. The indexes
+#
+# An index is read through the page cache and the cache lives in the VM, so an
+# index larger than the VM cannot be cached at all — which is the difference
+# between a five-second grep and a two-minute one. Counted once: the mount is
+# read-only and shared by every container.
+# ---------------------------------------------------------------------------
+
+INDEX_MIB=0
+INDEX_NAME=""
+INDEX_COUNT=0
+if [ -d "$ASSETS" ]; then
+    while IFS= read -r manifest; do
+        [ -n "$manifest" ] || continue
+        dir="$(dirname "$manifest")"
+        size="$(du -sk "$dir" 2> /dev/null | awk '{printf "%d", $1 / 1024}' || echo 0)"
+        INDEX_COUNT=$((INDEX_COUNT + 1))
+        if [ "${size:-0}" -gt "$INDEX_MIB" ]; then
+            INDEX_MIB="$size"
+            INDEX_NAME="$dir"
+        fi
+    done <<EOF
+$(find "$ASSETS" -maxdepth 3 -name manifest.json -type f 2> /dev/null || true)
+EOF
+fi
+
+# ---------------------------------------------------------------------------
+# 6. The probe — one container, one real read, peak RSS while it runs
+#
+# Process RSS, deliberately, not the cgroup's `memory.current`: that includes
+# page cache, and the index is already a term of its own in the budget. Summing
+# VmRSS across /proc inside the container is exactly the container's processes,
+# because it has its own pid namespace.
+#
+# The command is `local` — it makes no network call. A gate that needed a
+# credential would fail for reasons that are not about this machine.
+# ---------------------------------------------------------------------------
+
+PROBE_NAME=none
+PROBE_SECS=0
+SAMPLED_MIB=0
+
+probe() {
+    if [ -z "$INDEX_NAME" ]; then
+        note "no index under ${ASSETS}/ to read — nothing representative to probe"
+        return 0
+    fi
+    image="${ZEN_IMAGE:-$(zen sandbox status 2> /dev/null | awk '$1 == "image" { print $2 }' || true)}"
+    if [ -z "$image" ]; then
+        note "no sandbox image to probe with — run \`zen sandbox up\`, or pass --peak-rss"
+        return 0
+    fi
+    PROBE_NAME="read $INDEX_NAME"
+
+    # Passed as one argv element, so no second shell re-parses it. The loop
+    # bounds itself rather than trusting `timeout` to be in the project's image.
+    script="$(
+        cat << EOS
+( zen --version > /dev/null 2>&1; grep -rl zzzz-not-present /assets > /dev/null 2>&1 ) &
+p=\$!
+peak=0
+ticks=0
+while kill -0 \$p 2> /dev/null; do
+    cur=\$(awk '/^VmRSS:/ { s += \$2 } END { print s + 0 }' /proc/[0-9]*/status 2> /dev/null)
+    if [ "\${cur:-0}" -gt "\$peak" ]; then peak=\$cur; fi
+    ticks=\$((ticks + 1))
+    if [ \$ticks -gt $((PROBE_TIMEOUT * 5)) ]; then kill \$p 2> /dev/null; break; fi
+    sleep 0.2
+done
+wait \$p 2> /dev/null
+echo "PEAK_KB=\$peak"
+EOS
+    )"
+
+    started="$(date +%s)"
+    out="$(
+        podman run --rm -v "$PWD/$ASSETS:/assets:ro" \
+            --memory "${CONTAINER_MIB}m" --entrypoint="" \
+            "$image" sh -c "$script" 2> /dev/null || true
+    )"
+    PROBE_SECS=$(($(date +%s) - started))
+
+    kb="$(printf '%s' "$out" | sed -n 's/^PEAK_KB=\([0-9]*\)$/\1/p' | tail -1 || true)"
+    if [ -n "${kb:-}" ] && [ "${kb:-0}" -gt 0 ]; then
+        SAMPLED_MIB=$((kb / 1024))
+    else
+        note "the probe reported nothing — using the floor of ${PEAK_FLOOR_MIB} MiB"
+    fi
+}
+
+if [ "$PEAK_RSS" -gt 0 ]; then
+    PEAK_MIB="$PEAK_RSS"
+    PEAK_SOURCE="--peak-rss"
+elif [ "$SKIP_PROBE" -eq 1 ]; then
+    PEAK_MIB="$PEAK_FLOOR_MIB"
+    PEAK_SOURCE="floor (--skip-probe)"
+else
+    probe
+    if [ "$SAMPLED_MIB" -gt "$PEAK_FLOOR_MIB" ]; then
+        PEAK_MIB="$SAMPLED_MIB"
+        PEAK_SOURCE="sampled at concurrency 1"
+    elif [ "$SAMPLED_MIB" -gt 0 ]; then
+        PEAK_MIB="$PEAK_FLOOR_MIB"
+        PEAK_SOURCE="floor — the probe measured ${SAMPLED_MIB} MiB, below it"
+    else
+        # The probe did not run, or reported nothing. `note` has already said
+        # which; do not claim a measurement that was never taken.
+        PEAK_MIB="$PEAK_FLOOR_MIB"
+        PEAK_SOURCE="floor (unmeasured)"
+    fi
+fi
+
+# ---------------------------------------------------------------------------
+# 7. The verdict
+# ---------------------------------------------------------------------------
+
+ADMITTED_MIB=$((CONCURRENCY * CONTAINER_MIB))
+REQUIRED_MIB=$((INDEX_MIB + CONCURRENCY * PEAK_MIB + HEADROOM_MIB))
+
+OVERSUBSCRIBED=0
+if [ "$ADMITTED_MIB" -gt "$VM_MIB" ]; then OVERSUBSCRIBED=1; fi
+
+SUFFICIENT=1
+if [ "$REQUIRED_MIB" -gt "$VM_MIB" ]; then SUFFICIENT=0; fi
+
+# The width that does fit today, which is the remedy available on every machine.
+FITS=0
+budget=$((VM_MIB - INDEX_MIB - HEADROOM_MIB))
+if [ "$budget" -gt 0 ]; then FITS=$((budget / PEAK_MIB)); fi
+
+# Rounded up to the next whole GiB, because `machine set` takes MiB and nobody
+# wants a ceiling that is exact.
+SUGGEST_MIB=$(((REQUIRED_MIB + 1023) / 1024 * 1024))
+
+if [ "$AS_JSON" -eq 1 ]; then
+    printf '{"applicable":true,"sufficient":%s,"oversubscribed":%s,' \
+        "$([ "$SUFFICIENT" -eq 1 ] && echo true || echo false)" \
+        "$([ "$OVERSUBSCRIBED" -eq 1 ] && echo true || echo false)"
+    printf '"concurrency":%s,"hostMib":%s,"hostFreeMib":%s,' \
+        "$CONCURRENCY" "$HOST_MIB" "$HOST_FREE_MIB"
+    printf '"vm":{"name":"%s","state":"%s","memoryMib":%s,"swapMib":%s,"cpus":%s},' \
+        "$VM_NAME" "$VM_STATE" "$VM_MIB" "$VM_SWAP_MIB" "$VM_CPUS"
+    printf '"container":{"memoryMib":%s,"cpus":%s,"source":"%s"},' \
+        "$CONTAINER_MIB" "$CONTAINER_CPUS" "$CONTAINER_SOURCE"
+    printf '"index":{"largestMib":%s,"name":"%s","count":%s},' \
+        "$INDEX_MIB" "$INDEX_NAME" "$INDEX_COUNT"
+    printf '"peakRssMib":%s,"peakSource":"%s","probe":"%s","probeSeconds":%s,' \
+        "$PEAK_MIB" "$PEAK_SOURCE" "$PROBE_NAME" "$PROBE_SECS"
+    printf '"admittedMib":%s,"requiredMib":%s,"suggestMib":%s,"fitsAtConcurrency":%s}\n' \
+        "$ADMITTED_MIB" "$REQUIRED_MIB" "$SUGGEST_MIB" "$FITS"
+else
+    say "host       $(gib "$HOST_MIB") GiB total · $(gib "$HOST_FREE_MIB") GiB free"
+    swap="$VM_SWAP_MIB MiB swap"
+    if [ "$VM_SWAP_MIB" -eq 0 ]; then swap="no swap — the kill is immediate, not gradual"; fi
+    say "vm         $(gib "$VM_MIB") GiB total · $swap · ${VM_CPUS} cpus   ${VM_NAME:-?} ($VM_STATE)"
+    say "container  ${CONTAINER_MIB} MiB cap · ${CONTAINER_CPUS} cpus   ${CONTAINER_SOURCE}"
+    if [ "$INDEX_COUNT" -gt 0 ]; then
+        say "index      $(gib "$INDEX_MIB") GiB  ${INDEX_NAME} (largest of ${INDEX_COUNT})"
+    else
+        say "index      none found under ${ASSETS}/"
+    fi
+    timing=""
+    if [ "$PROBE_SECS" -gt 0 ]; then timing=" · probe ${PROBE_SECS}s"; fi
+    say "peak rss   ${PEAK_MIB} MiB  ${PEAK_SOURCE}${timing}"
+    say ""
+
+    if [ "$OVERSUBSCRIBED" -eq 1 ]; then
+        say "admission  ${CONCURRENCY} x ${CONTAINER_MIB} MiB = $(gib "$ADMITTED_MIB") GiB permitted against a $(gib "$VM_MIB") GiB vm   OVERSUBSCRIBED"
+        if [ "$CONTAINER_MIB" -gt "$VM_MIB" ]; then
+            say "           one container alone is permitted more than the whole machine"
+        else
+            say "           nothing will refuse the sum; only the containers not all"
+            say "           peaking together is keeping this alive"
+        fi
+    fi
+
+    if [ "$SUFFICIENT" -eq 1 ]; then
+        say "concurrency ${CONCURRENCY} needs ~$(gib "$REQUIRED_MIB") GiB   vm has $(gib "$VM_MIB") GiB   ok"
+    else
+        say "concurrency ${CONCURRENCY} needs ~$(gib "$REQUIRED_MIB") GiB   vm has $(gib "$VM_MIB") GiB   INSUFFICIENT"
+        say "  fix:  podman machine stop && podman machine set --memory ${SUGGEST_MIB} && podman machine start"
+        if [ "$FITS" -ge 1 ]; then
+            say "  or:   run the batch at --concurrency ${FITS}"
+        else
+            say "  or:   nothing fits — the index alone exceeds this vm; resizing is the only way"
+        fi
+        if [ "$SUGGEST_MIB" -gt "$HOST_MIB" ]; then
+            say "  note: that is more than the host has. Lower the concurrency instead"
+        fi
+    fi
+
+    if [ -n "$NOTES" ]; then
+        say ""
+        printf '%s' "$NOTES" | sed 's/^/note: /'
+    fi
+fi
+
+if [ "$SUFFICIENT" -eq 1 ]; then exit 0; fi
+exit 1