frutebox-node 0.1.0__py3-none-any.whl

frutebox/gpuproviders.py

@@ -0,0 +1,4489 @@
+"""GPU providers — one contract, many clouds, no lock-in.
+
+WHY THIS EXISTS IN THIS SHAPE
+On 2026-08-21 a pod billed for hours because wake created it under one name and stop looked
+for another. That was not a typo in a helper — it was an ASYMMETRY that the code's shape
+allowed: `start` and `stop` were written separately per provider, so nothing forced them to
+agree on how an instance is identified.
+
+Adding more providers multiplies that risk, and the risk is worse than it looks because every
+provider spells the label differently: RunPod and Lambda call it `name`, Vast.ai calls it
+`label`. A per-provider `start`/`stop` pair is three more chances to get it wrong, silently,
+in a direction that costs money and reports success.
+
+So a provider does NOT implement start/stop. It implements three narrow operations:
+
+    find(label)   -> the live instances carrying this label
+    create(label, spec) -> create ONE instance carrying this label
+    destroy(id)   -> terminate it
+
+and `start`/`stop` are written ONCE, here, on top of them. The symmetry is then structural:
+both sides go through the same `find(label)`, so they cannot disagree about what to look for.
+`contract_violations()` and the shared test suite check each provider actually honours it.
+
+WHAT A PROVIDER MUST GET RIGHT
+`create` MUST apply the label the caller passed, not one from its own spec. That single rule is
+the whole bug. It is stated on the method, tested for every provider, and is the first thing to
+check when adding a fourth.
+"""
+from __future__ import annotations
+
+import os
+import time
+import contextlib
+import contextvars
+import hashlib
+import hmac
+import json
+import logging
+import uuid
+from typing import Awaitable, Callable, Dict, List, Optional, Protocol, Set
+from urllib.parse import quote as _urlquote
+
+import httpx
+
+from .envvars import env as envvar
+
+log = logging.getLogger("frutebox.gpuproviders")
+
+
+class Instance(dict):
+    """A live instance: at minimum ``{"id": str, "label": str}``."""
+
+
+class GpuProvider(Protocol):
+    """Three required operations, plus two OPTIONAL enumerations. start/stop are NOT part of
+    this — they are derived.
+
+    WHY ENUMERATION IS THREE METHODS AND NOT ONE (owner ruling, 2026-09-24). "Is this slot
+    serving?" and "is anything of mine still billing here?" are DIFFERENT QUESTIONS, and a
+    single `find()` has to pick one answer for both. Vast picked capacity — it filters
+    `actual_status == "exited"` out — and on 2026-09-24 an exited-but-contracted instance was
+    therefore invisible to the pool census AND to the teardown at the same time, while the
+    account was billed for it. So the questions are asked separately now, and a provider that
+    genuinely cannot tell them apart says so by not implementing the split.
+
+    AND SAYS SO OUT LOUD, not merely by omission (owner ruling, 2026-09-24, second half). Not
+    implementing the split makes the fallback silent: every caller then gets the one answer the
+    provider has, dressed as the answer it asked for. `DISTINGUISHES_SERVING` is that omission
+    written down, so `stop()`, the placement confirmation and the pool census can REPORT the
+    ambiguity instead of resolving it toward "clean".
+    """
+
+    name: str
+
+    #: Can this provider separate "an instance is PRESENT" from "an instance is SERVING"?
+    #:
+    #: DECLARED, never inferred from behaviour. It is a statement about the provider's own status
+    #: vocabulary — which only the author of the adapter can make — and the default is True
+    #: because every provider that implements `find_live`/`find_all` has made it. A provider that
+    #: falls back to `find` for both MUST set this False; `test_gpuproviders.py` fails any
+    #: registered provider whose declaration and whose methods disagree, so the optimistic
+    #: default cannot be inherited by accident.
+    DISTINGUISHES_SERVING: bool = True
+
+    def configured(self) -> bool:
+        """Is there a credential for this provider? Never raises."""
+
+    async def find(self, label: str) -> List[Instance]:
+        """Live (non-terminated) instances carrying this label.
+
+        THE BASE PRIMITIVE, and deliberately NOT the one a caller with a question should reach
+        for: see `find_live` / `find_all` below. It is kept because `start`'s idempotency check
+        wants exactly this — "is anything of mine already here", answered as conservatively as
+        each provider can answer it.
+        """
+
+    async def find_live(self, label: str) -> List[Instance]:
+        """OPTIONAL. CAPACITY: instances carrying this label that are actually SERVING.
+
+        Optional because not every provider can tell. One asked through the module-level
+        `find_live()` helper, which falls back to `list_live` and then to `find`.
+        """
+
+    async def find_all(self, label: str) -> List[Instance]:
+        """OPTIONAL. TEARDOWN: every instance carrying this label that could still BILL.
+
+        Optional, same as `find_live`, and asked through the module-level `find_all()` helper.
+        """
+
+    async def create(self, label: str, spec: dict) -> bool:
+        """Create ONE instance carrying THIS label.
+
+        The label argument wins over anything in `spec`. A provider that lets its spec's name
+        through is the 2026-08-21 billing bug, reintroduced.
+        """
+
+    async def destroy(self, instance_id: str) -> bool:
+        """Terminate it. True when it is gone (or was already)."""
+
+
+# ---- the two questions, asked separately ---------------------------------------------------
+#
+# THE DEFECT THESE REPLACE (2026-09-24, real money). `find()` answered both "what is serving?"
+# and "what is still billing?", so each provider's author had to choose which one to be wrong
+# about. Vast chose: it drops `exited` instances, which is RIGHT for capacity — an exited pod
+# must not hold the pool's only slot and block its own replacement — and WRONG for teardown,
+# where `nodewake._provider_has`'s own docstring already required the opposite ("a
+# RUNNING-but-runtimeless pod serves nothing and bills anyway, and must still be found").
+# A Vast instance that took the contract and then exited was consequently invisible to BOTH
+# readers at once: `/control/pool` said 0 and the teardown said `terminated: []`, while the
+# account was charged.
+#
+# Neither helper invents an answer a provider cannot give. A provider that cannot distinguish
+# the two states falls back to the one enumeration it has, which is no worse than before — and
+# `test_gpuproviders.py` pins, per provider, which of them can.
+#
+# THE FALLBACK IS NOT FREE, AND IT IS NO LONGER SILENT (owner ruling, 2026-09-24, second half):
+# "where DataCrunch cannot distinguish intent from reality, resolve the ambiguity toward
+# suspected_billing rather than toward clean. It is the EU half of Phase 1, so a provider that
+# cannot answer the teardown question must err on the side of telling you it might be spending."
+# The fallback ANSWER stays what it was — inventing a finer one would mean guessing a status
+# vocabulary, which is the thing the previous pass refused to do and still refuses. What changes
+# is that the answer now travels with `distinguishes_serving()`, and the three places that would
+# otherwise have reported a clean result off it say "presence only" instead.
+
+
+def distinguishes_serving(provider: GpuProvider) -> bool:
+    """Can this provider tell a SERVING instance from one that is merely PRESENT?
+
+    Read from the provider's own declaration (`DISTINGUISHES_SERVING`), defaulting to True. It is
+    not inferred from which methods exist, because inference would silently relabel every test
+    double and every future adapter the moment it grew or lost a method — and because the claim
+    is about a vendor's status vocabulary, which no amount of introspection can see. The
+    declaration is kept honest by a contract test over `PROVIDERS`, not by this function.
+
+    False means: every answer this provider gives about the label is "listed / not listed". A
+    caller that reports success on that basis is reporting something it did not verify.
+    """
+    return bool(getattr(provider, "DISTINGUISHES_SERVING", True))
+
+
+def presence_only_note(provider_name: str, label: str, question: str, detail: str,
+                       terminated: "Optional[List[str]]" = None) -> dict:
+    """The ambiguity, in the shape the money channel already carries.
+
+    Same keys as `nodewake._abandon_unconfirmed`'s note — provider/name/suspected_billing/
+    terminated/detail — ON PURPOSE: `scale_to` already collects those into `unconfirmed` and
+    lifts the flagged ones into `suspected_billing`, which is precisely the channel the ruling
+    asks this to resolve toward. A second, parallel reporting path would have to be wired into
+    every reader again, and the 2026-09-17 orphan bucket is what a recorded-but-unread channel
+    is worth.
+    """
+    return {
+        "provider": provider_name,
+        "name": label,
+        "suspected_billing": True,
+        "presence_only": question,
+        "terminated": [str(i) for i in (terminated or [])],
+        "detail": detail,
+    }
+
+
+async def find_live(provider: GpuProvider, label: str) -> List[Instance]:
+    """CAPACITY: instances under this label that are actually SERVING.
+
+    The question the pool census and the scale plan ask. A corpse answered "yes" here holds a
+    slot forever and no replacement is ever created.
+
+    WHICH WAY THE FALLBACK ERRS, AND WHY IT IS THE OPPOSITE OF THE REPORTING DIRECTION. For a
+    provider that cannot distinguish, "present" is returned as live. Counting it dead instead
+    would create a REPLACEMENT while the ambiguous instance is still contracted — two instances,
+    two bills, on exactly the evidence that was too weak to classify one. Money is irreversible
+    and a short pool is not. `start()` already makes the same choice for the same reason.
+
+    AND IT IS BOUNDED, WHICH THIS FUNCTION CANNOT DO. "Present counts as live" held forever would
+    deadlock a provider that can never tell: DataCrunch would look permanently full and never
+    scale. The bound is a clock and therefore belongs with the pool census, not with a stateless
+    enumeration — `nodewake._provider_has` holds an ambiguous slot only for the confirmation
+    window and then RELEASES it while RECORDING suspected_billing (owner ruling, 2026-09-24).
+    Both halves are required: a release without the record is the silent failure this whole line
+    of work exists to remove, and a record without the release deadlocks the provider.
+    """
+    own = getattr(provider, "find_live", None)
+    if callable(own):
+        return list(await own(label))
+    # `list_live` is RunPod's older name for the same question, and a test fake may define only
+    # that. Honoured before `find` so the narrower answer always wins.
+    list_live = getattr(provider, "list_live", None)
+    if callable(list_live):
+        return [Instance(id=p.get("id"), label=p.get("name"))
+                for p in await list_live() if str(p.get("name", "")) == label]
+    return list(await provider.find(label))
+
+
+async def find_all(provider: GpuProvider, label: str) -> List[Instance]:
+    """TEARDOWN: every instance under this label that could still be BILLING, in any state.
+
+    The question `stop()` and the disarm sweep ask. A false "no" here is money: it is the
+    2026-08-21 fail-to-kill and the 2026-09-24 invisible Vast contract, both.
+    """
+    own = getattr(provider, "find_all", None)
+    if callable(own):
+        return list(await own(label))
+    return list(await provider.find(label))
+
+
+# ---- the derived lifecycle: written once, shared by every provider -------------------------
+
+async def start(provider: GpuProvider, label: str, spec: dict) -> dict:
+    """Idempotent create-on-wake.
+
+    Both the "already running?" check and the create go through the SAME label, which is what
+    makes a second wake a no-op rather than a second bill.
+
+    DELIBERATELY `find`, not `find_live`: this check exists to stop a SECOND BILL, so the
+    conservative answer is the safe one. An instance that exists but is not yet serving (still
+    booting) must read as "already here" — treating it as absent is how you buy two. Whether a
+    slot COUNTS as capacity is a different question, asked with `find_live` by the pool plan,
+    which allocates the replacement a fresh name rather than colliding with the corpse.
+    """
+    if not provider.configured():
+        return {"ok": False, "error": f"{provider.name} has no credential configured"}
+    try:
+        existing = await provider.find(label)
+    except Exception as e:
+        return {"ok": False, "error": f"{provider.name} could not be reached: {type(e).__name__}"}
+    if existing:
+        return {"ok": True, "already": [i.get("id") for i in existing]}
+    try:
+        ok = await provider.create(label, spec)
+    except Exception as e:
+        return {"ok": False, "error": f"{provider.name} create failed: {type(e).__name__}"}
+    return {"ok": bool(ok)} if ok else {
+        "ok": False,
+        "error": f"{provider.name} accepted no instance for '{label}' — usually out of stock or over quota",
+    }
+
+
+#: How long the provider-neutral teardown waits for an instance to actually disappear, and how
+#: often it re-asks. RunPod's own `terminate` uses 120s/5s and is the model; this is the same
+#: discipline for every other provider, which had none.
+DESTROY_VERIFY_TIMEOUT_S = float(envvar("DESTROY_VERIFY_TIMEOUT_S", "90"))
+DESTROY_VERIFY_POLL_S = float(envvar("DESTROY_VERIFY_POLL_S", "5"))
+
+
+async def destroy_verified(provider: GpuProvider, instance_id: str,
+                           label: str) -> "tuple[bool, str]":
+    """Terminate one instance AND CONFIRM IT IS GONE, for ANY provider. Returns (gone, reason).
+
+    THE DEFECT THIS CLOSES, and it is money. `RunPodProvider.destroy` delegates to its own
+    `terminate`, whose docstring states the rule in as many words: *"The API's 2xx is never the
+    evidence — REST DELETE returns 2xx without stopping the pod, and it keeps BILLING."* Three of
+    the four providers in this file then did exactly that. Vast:
+
+        r = await c.delete(f"{self._BASE}/instances/{instance_id}/", ...)
+        return r.status_code < 300 or r.status_code == 404
+
+    and DataCrunch and Lambda are the same shape. So `stop()` reported
+    ``{"ok": True, "terminated": [id]}`` on the strength of an HTTP status, the pool believed the
+    slot was free, and nobody looked again. The rule was written down once, enforced for one
+    provider, and the other three inherited the wrong half of it.
+
+    PROVIDER-NEUTRAL BY CONSTRUCTION. It uses only what the `GpuProvider` protocol requires —
+    `destroy` to ask and `find_all`/`find` to look — so a provider added tomorrow is covered
+    without implementing anything, which is the opposite of how `terminate` ended up RunPod-only.
+    `find_all` is the right question here for the same reason `stop` already uses it: teardown
+    must see an instance that bills without serving.
+
+    THE FIRST CHECK IS IMMEDIATE, so the common case — it really is gone — costs one extra API
+    call and no waiting, including on RunPod where this is a second opinion on a verification that
+    already happened. Re-asking `destroy` each round is deliberate and copied from RunPod's
+    terminate, which records that RunPod "sometimes needs it more than once"; a vendor that
+    accepted a delete and did nothing is exactly the case being defended against.
+
+    A TIMEOUT IS NOT A SUCCESS. The return is `(False, reason)`, and `stop` turns that into a
+    suspected-billing record rather than into a clean teardown — "I could not confirm" must never
+    print like "it is gone".
+    """
+    import asyncio as _a
+
+    # Read from the module, not from parameters. They were keyword-only overrides that only the TESTS
+    # ever supplied — "a promise that callers will name it", with no production caller, which is dead
+    # code behind a live signature (`test_no_unsupplied_keyword_args`). An operator who needs to move
+    # these sets the env vars the constants come from.
+    timeout = DESTROY_VERIFY_TIMEOUT_S
+    poll = DESTROY_VERIFY_POLL_S
+    iid = str(instance_id)
+
+    async def _still_there() -> "bool | None":
+        """True/False, or None when the question itself could not be asked."""
+        try:
+            return any(str(i.get("id")) == iid for i in await find_all(provider, label))
+        except Exception as e:
+            log.warning("%s: could not re-check %s after destroy: %s",
+                        provider.name, iid, type(e).__name__)
+            return None
+
+    try:
+        asked = await provider.destroy(iid)
+    except Exception as e:
+        return False, f"destroy raised {type(e).__name__}"
+    if not asked:
+        return False, "the provider refused the destroy"
+
+    waited = 0.0
+    while True:
+        present = await _still_there()
+        if present is False:
+            return True, "confirmed gone"
+        if present is None:
+            # NOT counted as gone. A provider we cannot read is a provider we cannot clear, and
+            # this is the same distinction `nodewake.TeardownBlocked` draws one layer up.
+            return False, "destroy was accepted but the instance could not be re-checked"
+        if waited >= timeout:
+            log.error("PANIC: %s instance %s still present %.0fs after an accepted destroy — "
+                      "MAY BE BILLING", provider.name, iid, timeout)
+            return False, (f"still present {timeout:.0f}s after the provider accepted the "
+                           f"destroy — may still be billing")
+        await _a.sleep(poll)
+        waited += poll
+        try:
+            await provider.destroy(iid)        # RunPod sometimes needs it more than once
+        except Exception as e:
+            log.warning("%s: re-issued destroy for %s raised %s",
+                        provider.name, iid, type(e).__name__)
+
+
+async def stop(provider: GpuProvider, label: str) -> dict:
+    """Terminate everything carrying this label.
+
+    Reports WHAT it terminated. "ok with nothing terminated" is a legitimate answer only when
+    nothing was running — and the caller can now tell the difference, which they could not
+    before.
+
+    A PROVIDER THAT CANNOT ANSWER THE TEARDOWN QUESTION DOES NOT GET TO REPORT A CLEAN TEARDOWN
+    (owner ruling, 2026-09-24). Where `distinguishes_serving()` is False, every id this reached
+    was chosen by PRESENCE, and "nothing else of mine is billing there" was never verified —
+    it was one enumeration answering a question it cannot answer. `ok` stays honest about the
+    terminates that did happen (flipping it would push a real teardown into `failed` and hide
+    the ids), and the ambiguity rides out beside it in `unverified`, flagged suspected_billing.
+    """
+    if not provider.configured():
+        return {"ok": False, "error": f"{provider.name} has no credential configured"}
+    try:
+        # `find_all`, NOT `find`: teardown must reach an instance that bills without serving.
+        # Asking the capacity question here is what let an exited-but-contracted Vast instance
+        # survive a teardown that reported success (2026-09-24).
+        live = await find_all(provider, label)
+    except Exception as e:
+        return {"ok": False, "error": f"{provider.name} could not be reached: {type(e).__name__}"}
+    terminated, failed, unconfirmed = [], [], []
+    for inst in live:
+        iid = str(inst.get("id"))
+        # VERIFIED, for every provider. This used to be `await provider.destroy(iid)` and the
+        # boolean was the whole evidence — which for Vast, DataCrunch and Lambda meant an HTTP
+        # status, since their `destroy` returns `status < 300 or 404`. RunPod was the only one
+        # whose `destroy` confirmed anything, because it delegates to its own verifying
+        # `terminate`. See `destroy_verified`.
+        gone, why = await destroy_verified(provider, iid, label)
+        if gone:
+            terminated.append(iid)
+        elif why == "the provider refused the destroy" or why.startswith("destroy raised"):
+            # It never got started. That is a plain failure and already reported as one.
+            failed.append(iid)
+        else:
+            # ACCEPTED AND NOT CONFIRMED GONE: the dangerous case, and the one that used to read
+            # as success. It goes to the money channel, not to `terminated`.
+            unconfirmed.append({"id": iid, "reason": why})
+    res = {"ok": not failed and not unconfirmed, "terminated": terminated,
+           **({"failed": failed} if failed else {})}
+    if unconfirmed:
+        # `ok` is False here, unlike the presence-only note below. The difference is real: there,
+        # the instance IS gone as far as anything can tell and only the "nothing ELSE is billing"
+        # claim is weak. Here a specific instance was still listed after its own destroy was
+        # accepted, so there is a named thing that may be spending money right now.
+        res["unconfirmed_destroys"] = unconfirmed
+        res["suspected_billing"] = True
+        ids = [u["id"] for u in unconfirmed]
+        log.error("%s: %d instance(s) under %r accepted a destroy and are STILL LISTED: %s — "
+                  "treating the teardown as NOT clean", provider.name, len(ids), label, ids)
+        _SUSPECTED.extend(
+            presence_only_note(
+                provider.name, label, "destroy-unconfirmed",
+                f"instance {u['id']} {u['reason']}. The provider accepted the destroy, so a "
+                f"caller trusting that answer would have recorded a clean teardown. Check by "
+                f"hand: python -m frutebox.gpuproviders stop-label {label} {provider.name}",
+                [u["id"]])
+            for u in unconfirmed)
+    if not distinguishes_serving(provider):
+        res["unverified"] = presence_only_note(
+            provider.name, label, "teardown",
+            (f"{provider.name} cannot tell an instance that is SERVING from one that is merely "
+             f"PRESENT — it has a single enumeration and answers both questions with it. This "
+             f"teardown terminated {len(terminated)} instance(s) under {label!r} on presence "
+             f"alone, so 'nothing is billing under that label on {provider.name} any more' is "
+             f"NOT a verified statement: it is the only answer that provider can give. Treat it "
+             f"as possibly still spending until checked by hand — python -m "
+             f"frutebox.gpuproviders stop-label {label} {provider.name}"),
+            terminated)
+    return res
+
+
+# ---- RunPod --------------------------------------------------------------------------------
+#
+# THE SINGLE DOOR (KB §0). Every RunPod touch in this codebase goes through this class — the SDK
+# import, the proxy hostname, the GraphQL endpoint for prices, all of it lives HERE and nowhere
+# else, enforced by tests/test_gpu_single_door.py. Almost every RunPod incident we have had
+# traces to the same root cause: many call sites, each implemented ad hoc, so a fix in one path
+# never reached the others. A new GPU type or a different start is a `PodSpec` value handed to the
+# same proven code — never a new function that re-implements create/wait/terminate.
+
+from dataclasses import dataclass, field
+
+
+@dataclass(frozen=True)
+class PodSpec:
+    """Everything a bring-up needs, as VALUES. New hardware = a new PodSpec, never new code."""
+    name: str
+    image: str
+    serving_port: int = 11434
+    #: (gpu_type_id, cloud_type) or (gpu_type_id, cloud_type, data_center_id), tried in order.
+    #: SECURE first: Community publishes no uptime SLA and is where "placed but never scheduled"
+    #: clusters — but it stays in the list, because an available Community pod beats no pod.
+    #: NOTE: when `network_volume_id` is set, the VOLUME's datacenter overrides any entry's — a
+    #: RunPod network volume is datacenter-locked, and deploying elsewhere cannot mount it.
+    gpu_fallbacks: tuple = (
+        ("NVIDIA RTX A6000", "SECURE"),
+        ("NVIDIA RTX A5000", "SECURE"),
+        ("NVIDIA A40", "SECURE"),
+        ("NVIDIA RTX A6000", "COMMUNITY"),
+    )
+    #: GPUs IN ONE POD. `create_pod` hardcoded 1, and that made the tier-S placement the whole
+    #: unit-economics story rests on unreachable through this door: file 01-B2's default is
+    #: Qwen3-235B-A22B FP8 on **2x H200** (~$7.18/hr Community) and `serving.gpu_plan` returns
+    #: exactly that multi-GPU config — which this module could then only ask RunPod for one card
+    #: of. A 235 GB model on one 141 GB H200 boots, bills, and loads forever: the 2026-08-30 root
+    #: cause with a different card. Tensor parallelism also needs the count to be a power of two,
+    #: which `serving_spec` already enforces when it builds the plan.
+    gpu_count: int = 1
+    container_disk_gb: int = 40
+    volume_gb: int = 0
+    network_volume_id: str = ""
+    #: A volume implies its datacenter; naming it makes the pin explicit in the request so a
+    #: mismatch fails loudly instead of the API inferring something else.
+    data_center_id: str = ""
+    docker_args: str = ""
+    #: RunPod's id for a stored container-registry credential. Our node image is PRIVATE, so a pod
+    #: cannot pull it without one — a pod created without this is rented and exits in ~2 seconds
+    #: with `runtime: null`, which is what happened on 2026-09-20 before this existed.
+    #: `runpod.create_pod` has no parameter for it (measured against 1.12.0, the latest release),
+    #: so it travels via a template — see `_template_id_for`.
+    container_registry_auth_id: str = ""
+    #: WHICH PORTS RUNPOD EXPOSES, as RunPod's own "8081/http,11434/http" string. Distinct from
+    #: `serving_port`, which is the ONE port the control plane dials for readiness (`serves()`);
+    #: this is everything the pod should reach the outside on.
+    #:
+    #: It exists because the operator's `ports` was being thrown away. `from_operator_spec` never
+    #: read it and every outgoing call rebuilt `f"{serving_port}/http"`, so `_WARM`'s declared
+    #: "8080/http,8081/http" had been silently reduced to "11434/http" for as long as it has been
+    #: set. The cost was not abstract: the node image runs a boot-status sidecar on :8081 built
+    #: precisely so a slow model pull and a dead container are distinguishable, and on 2026-09-21
+    #: a pod ran 15 minutes without registering and the sidecar could not be reached to say why.
+    ports: str = ""
+    #: THE PATH the readiness probe asks for on `serving_port`. Default `/` because that is what
+    #: Ollama and llama.cpp answer (both have a root page) and this door was built for them.
+    #:
+    #: IT IS A FIELD BECAUSE SGLang HAS NO `/` ROUTE. Its FastAPI app serves `/health`,
+    #: `/get_model_info`, `/v1/models` and the completion endpoints — a probe on `/` 404s forever,
+    #: which is a readiness predicate that CANNOT PASS: the pod boots, serves, and is reaped at the
+    #: timeout as dead. That is the 2026-08-30 incident in this KB (a predicate reading a field the
+    #: query never returned) with a different cause and the same cost, and the tier-S recipe would
+    #: have hit it on its first armed run.
+    health_path: str = "/"
+    env: dict = field(default_factory=dict)
+    #: ONE NAMED VARIANT = ONE TEMPLATE OF ITS OWN, carrying its per-pod env.
+    #:
+    #: A POOL spec deploys N interchangeable slots that differ only by `STEVAI_NODE_ID`, so its
+    #: template must be SHARED or every slot mints one (`_PER_POD_ENV`, below). A VARIANT is one
+    #: deliberate pod — `frutebox-media` — whose identity and advertised modalities ARE the spec.
+    #: Stripping its per-pod env to share a template with nothing is how the media node booted as
+    #: `runpod-node-1` and advertised text only: the values that make it a media node never
+    #: reached the container at all.
+    #:
+    #: Bounded by construction: one template per configured variant, not one per pod or per
+    #: attempt. The name is a pure function of the full env, so a re-arm of the same variant
+    #: FINDS its template instead of minting another.
+    dedicated_template: bool = False
+    #: Sized to the documented COLD START (image + model pull), not the serving SLA — confusing
+    #: the two once reaped six healthy pods mid-boot.
+    ready_timeout_s: int = int(envvar("POD_READY_TIMEOUT_S", "780"))
+    poll_s: int = int(envvar("POD_READY_POLL_S", "10"))
+
+    @staticmethod
+    def from_operator_spec(spec: dict, name: str = "") -> "PodSpec":
+        """Adapt a RUNPOD_POD_SPEC-shaped dict (the operator's config format) into a PodSpec."""
+        env = spec.get("env", {})
+        # A spec that PINS GPUs (gpuTypeId/gpuTypeIds — e.g. the frontier variant pinning H100)
+        # must drive the fallback walk with those pins, not with the default tier-A list: the
+        # default would happily deploy an A6000 where the operator specified frontier hardware.
+        pins = [g for g in ([spec.get("gpuTypeId")] + list(spec.get("gpuTypeIds") or [])) if g]
+        cloud = str(spec.get("cloudType", "") or "").upper()
+        clouds = [cloud] if cloud in ("SECURE", "COMMUNITY") else ["SECURE", "COMMUNITY"]
+        pinned_fallbacks = tuple((g, c) for c in clouds for g in pins)
+        return PodSpec(
+            name=name or str(spec.get("name") or "frutebox-runpod-1"),
+            **({"gpu_fallbacks": pinned_fallbacks} if pinned_fallbacks else {}),
+            image=str(spec.get("imageName") or spec.get("image") or "ollama/ollama:latest"),
+            serving_port=int(envvar("SERVING_PORT", "11434")),
+            # The operator's spec has carried `gpuCount` since the frontier example was
+            # written (it asks for 8x H100); it was read by nothing.
+            gpu_count=max(1, int(spec.get("gpuCount", 1) or 1)),
+            container_disk_gb=int(spec.get("containerDiskInGb", 40) or 40),
+            volume_gb=int(spec.get("volumeInGb", 0) or 0),
+            # ENV FIRST, spec second: where money is spent is an OPERATOR decision, not a
+            # per-spec preference — the operator's configured volume overrides whatever a spec
+            # happens to carry.
+            network_volume_id=str(os.environ.get("RUNPOD_NETWORK_VOLUME_ID", "").strip()
+                                  or spec.get("networkVolumeId") or ""),
+            data_center_id=str(os.environ.get("RUNPOD_VOLUME_DATACENTER", "").strip()
+                               or spec.get("dataCenterId") or ""),
+            docker_args=str(spec.get("dockerArgs", "") or ""),
+            container_registry_auth_id=str(spec.get("containerRegistryAuthId", "") or ""),
+            dedicated_template=bool(spec.get("dedicatedTemplate", False)),
+            ports=str(spec.get("ports", "") or ""),
+            env=env if isinstance(env, dict) else {},
+        )
+
+
+def ports_string(spec: PodSpec) -> str:
+    """What RunPod should expose, as its "port/http,port/http" string. ONE definition, because
+    three calls need the identical answer.
+
+    The template's ports and the pod's ports must agree, and the template NAME is a hash of the
+    template's ports — so a helper that drifted from its callers would mint a template per call
+    and then hand the pod a different set than the one it was named for.
+
+    THE SERVING PORT IS ALWAYS PRESENT, even when the operator's string omits it. The control
+    plane dials `serving_port` to decide a pod is ready (`serves()`); a spec that left it out
+    would produce a pod that boots correctly, cannot be reached, and is reaped as dead — paid for
+    and useless. Adding it back is cheaper than that, and saying so in the log means the spec
+    still gets fixed rather than the mistake staying invisible.
+    """
+    want = f"{spec.serving_port}/http"
+    declared = [p.strip() for p in (spec.ports or "").split(",") if p.strip()]
+    if not declared:
+        return want
+    if not any(p.split("/", 1)[0] == str(spec.serving_port) for p in declared):
+        log.warning("spec %s declares ports %r but not the serving port %s that readiness dials "
+                    "— adding it; fix the spec", spec.name, spec.ports, spec.serving_port)
+        declared.append(want)
+    return ",".join(declared)
+
+
+#: Usable VRAM per GPU type, GB. Conservative round-downs of the marketing numbers. Used by the
+#: model-fit assertion below; a type not listed is treated as unknown and only the disk check runs.
+GPU_VRAM_GB = {
+    "NVIDIA A40": 48, "NVIDIA RTX A6000": 48, "NVIDIA RTX 6000 Ada Generation": 48,
+    "NVIDIA RTX A5000": 24, "NVIDIA RTX A4000": 16,
+    "NVIDIA H100 80GB HBM3": 80, "NVIDIA H100 PCIe": 80, "NVIDIA H200": 141,
+    "NVIDIA A100 80GB PCIe": 80, "NVIDIA A100-SXM4-80GB": 80,
+    "NVIDIA L40S": 48, "NVIDIA GeForce RTX 4090": 24,
+}
+
+#: Does the card have NATIVE FP8 tensor cores? Ampere and older do not; Ada, Hopper and Blackwell
+#: do. This is an ARCHITECTURE fact, not a second opinion about our inventory — `serving.py`
+#: carries the same flag for the subset of cards it prices, and
+#: `test_the_fp8_table_agrees_with_serving_and_covers_every_card` fails if the two ever disagree
+#: or if a card is added to one table and not the other. That test is the point: a hand-kept list
+#: is correct the day it is written and quietly wrong afterwards, which is how the single-door
+#: guard came to cover one vendor.
+GPU_FP8 = {
+    "NVIDIA A40": False, "NVIDIA RTX A6000": False,
+    "NVIDIA RTX A5000": False, "NVIDIA RTX A4000": False,
+    "NVIDIA A100 80GB PCIe": False, "NVIDIA A100-SXM4-80GB": False,
+    "NVIDIA H100 80GB HBM3": True, "NVIDIA H100 PCIe": True, "NVIDIA H200": True,
+    "NVIDIA RTX 6000 Ada Generation": True, "NVIDIA L40S": True,
+    "NVIDIA GeForce RTX 4090": True,
+}
+
+
+#: serving.py's inventory name -> RunPod's `gpuTypeId`. THE MISSING HALF OF A COSTED PLACEMENT.
+#:
+#: `serving.gpu_plan()` answers "which hardware fits this model, cheapest first" in its own
+#: vocabulary ("H200 SXM"), and this module asks RunPod for hardware in RunPod's ("NVIDIA H200").
+#: Nothing translated between them, so a cost-ranked plan could be computed and never requested —
+#: which is one reason the tier-S recipe had no launcher at all. The translation belongs here
+#: because RunPod's id vocabulary is this door's business and nothing else's (KB §0).
+#:
+#: An empty value means DELIBERATELY UNMAPPED: the card is priced by `serving.py` but this door has
+#: no id it can vouch for, so a placement on it is skipped rather than guessed. A guessed id is not
+#: a near miss — RunPod refuses it, and the refusal reads exactly like a capacity shortage.
+RUNPOD_GPU_TYPE_ID = {
+    "RTX A4000": "NVIDIA RTX A4000",
+    "RTX A5000": "NVIDIA RTX A5000",
+    "A40": "NVIDIA A40",
+    "RTX A6000": "NVIDIA RTX A6000",
+    "A100 PCIe": "NVIDIA A100 80GB PCIe",
+    "A100 SXM": "NVIDIA A100-SXM4-80GB",
+    "H100 SXM": "NVIDIA H100 80GB HBM3",
+    "H200 SXM": "NVIDIA H200",
+    # RunPod's own id for the Blackwell workstation card is not one we have seen in a reply from
+    # the account, and `GPU_VRAM_GB`/`GPU_FP8` do not carry it either. Unmapped on purpose.
+    "RTX PRO 6000": "",
+}
+
+
+def runpod_gpu_type_id(serving_gpu_type: str) -> str:
+    """RunPod's id for a `serving.GpuConfig.gpu_type`, or "" when this door cannot vouch for one.
+
+    KeyError would be the wrong answer for an unknown name: the caller is walking a cost-ranked
+    list and should skip a card it cannot ask for, not abort a bring-up over the cheapest entry.
+    """
+    return RUNPOD_GPU_TYPE_ID.get(serving_gpu_type, "")
+
+
+def model_fit_error(model: str, gpu_type_id: str, gpu_count: int, disk_gb: int) -> str:
+    """PURE. Why this model cannot run on this hardware — or "" when it fits.
+
+    THE ROOT CAUSE THIS ENCODES (owner-diagnosed from the console System Logs, 2026-08-30): the
+    default pool spec carried the tier-S Kimi config, so every A40 boot tried to download and load
+    a ~595 GB model onto 48 GB of VRAM and a small disk. llama-server's /health said "loading"
+    forever, the boot script looped for two hours, the node never registered, and the pod billed
+    while "running". Ten-plus pods died that way across three days, and it looked exactly like a
+    provider scheduling fault. A doomed combination must be refused BEFORE money is spent —
+    clearly, naming the numbers.
+    """
+    try:
+        from . import serving
+        ms = serving.serving_spec(model)
+    except Exception:
+        return ""                       # unknown model: nothing to assert against
+    need_vram = float(getattr(ms, "vram_gb", 0) or 0)
+    if not need_vram:
+        return ""
+    # The download lands on the container disk first (plus image + headroom).
+    need_disk = need_vram * 1.1 + 12
+    if disk_gb and need_disk > disk_gb:
+        return (f"model {model!r} needs ~{need_vram:.0f}GB downloaded (≥{need_disk:.0f}GB disk with "
+                f"headroom) but the spec gives {disk_gb}GB — this pod would bill while failing")
+    per_gpu = GPU_VRAM_GB.get(gpu_type_id)
+    if per_gpu is not None and need_vram > per_gpu * max(1, gpu_count):
+        return (f"model {model!r} needs ~{need_vram:.0f}GB VRAM but {gpu_count}x {gpu_type_id} "
+                f"has {per_gpu * max(1, gpu_count)}GB — this pod would bill while failing")
+    # ENOUGH VRAM IS NOT ENOUGH. An FP8 model on an Ampere card has the memory and still cannot
+    # load: 6x A40 is 288GB, more than the 235GB the weights need, and the pod would bill while
+    # the server failed to start. `serving.gpu_plan(require_fp8=True)` already refuses the
+    # placement when the plan is BUILT; this is the check on the path that refuses a doomed
+    # combination someone SUPPLIED, which is where a hand-written variant spec arrives.
+    # `engine == "sglang"` is the FP8 path — the only branch `serving_spec` sends there.
+    if getattr(ms, "engine", "") == "sglang" and GPU_FP8.get(gpu_type_id) is False:
+        return (f"model {model!r} is served FP8 and {gpu_type_id} has no native FP8 tensor cores "
+                f"(Ampere or older) — {gpu_count}x gives {per_gpu * max(1, gpu_count) if per_gpu else '?'}GB, "
+                f"enough memory and still unable to load; this pod would bill while failing")
+    return ""
+
+
+
+# ---- THE REAPER ----------------------------------------------------------------------------
+#
+# THE RULE THIS ENCODES (2026-09-17, after a 13h20m orphan billed $6.54):
+#
+#     A TIMEOUT ON A CALL THAT CREATES A RESOURCE IS NOT EVIDENCE THAT NOTHING WAS CREATED.
+#     It is evidence that you do not know. Treat it as "may have succeeded" and reconcile
+#     against the provider's own list before moving on.
+#
+# What happened: `create_pod` wrapped the SDK call in `wait_for(..., timeout=180)`. The call
+# timed out, the `except` logged "create REFUSED" and returned None, and the caller moved to the
+# next fallback. But `wait_for` cannot cancel a blocking call running in a worker thread — the
+# request was still in flight, and RunPod created the pod minutes later, after the process had
+# exited. Nothing owned it, so nothing reaped it. It billed overnight with `runtime: None`.
+#
+# Two properties make this reaper different from the teardown that already existed:
+#
+#   1. The reap set comes from RUNPOD'S LIST, never from the ids we think we created. An orphan
+#      we never saw an id for is exactly the case that costs money, and it is invisible to any
+#      bookkeeping built on our own return values.
+#   2. It runs in a `finally`, so an exception, a timeout, or a KeyboardInterrupt on the wake
+#      path cannot skip it.
+
+
+#: Reconcile timings. Module-level so tests drive the real code paths at speed rather than
+#: mocking them out — the 2026-09-17 bug lived in a path that had never once been executed.
+_AMBIGUOUS_WINDOW_S = 120.0     # how long to watch for a pod after an ambiguous create
+_AMBIGUOUS_POLL_S = 10.0
+_SETTLE_POLL_S = 10.0           # re-list interval while waiting for late pods to settle
+_SETTLE_S = 180.0               # how long an ambiguous create keeps the exit reap watching
+#: An unowned pod older than this is no longer "someone else's pod, probably fine" — it is a
+#: suspected orphan and must escalate past a log line. 30 min is well past any legitimate
+#: bring-up (the documented cold start is ~94 min, but a DIAG pod is watched by a human from the
+#: first minute); the 2026-09-17 orphan sat for 13h20m inside a "reported" bucket.
+_ORPHAN_SUSPECT_AGE_H = 0.5
+
+
+class PodTracker:
+    """The set of pods a guarded window is allowed to leave running.
+
+    `saw()` is bookkeeping for the log. `keep()` is the only thing that spares a pod: a pod is
+    reaped unless the caller explicitly confirmed it wants it alive. Silence never means keep.
+    """
+
+    def __init__(self, owns: str):
+        self.owns = owns
+        self.seen: Set[str] = set()
+        self.kept: Set[str] = set()
+        #: names whose create call ended ambiguously (timeout/transport error). Their pods may
+        #: still materialise AFTER the call returned, so the exit reap waits for them to settle.
+        self.ambiguous: Set[str] = set()
+
+    def saw(self, pod_id: str) -> None:
+        if pod_id:
+            self.seen.add(pod_id)
+
+    def keep(self, pod_id: str) -> None:
+        """Confirm this pod is intentionally alive — the caller owns it from here."""
+        if pod_id:
+            self.kept.add(pod_id)
+            self.seen.add(pod_id)
+
+
+#: Suspected orphans seen by any guard in this process. A wake that runs after one was found can
+#: read this and refuse to add more pods to an account nobody has cleaned up.
+_SUSPECTED: "List[dict]" = []
+
+
+def suspected_orphans() -> "List[dict]":
+    """Unowned pods past the suspect age that a guard has seen in this process. Not empty means
+    somebody must look at the account before more pods are armed."""
+    return list(_SUSPECTED)
+
+
+#: The guard active on this task, so `create_pod` can register what it learns without every
+#: call site having to thread a tracker through. None = unguarded (the reaper then warns).
+_TRACKER: "contextvars.ContextVar[Optional[PodTracker]]" = contextvars.ContextVar(
+    "runpod_tracker", default=None)
+
+
+def _pod_age_hours(pod: dict) -> "float | None":
+    """Best effort age in hours, or None when RunPod gave us no timestamp.
+
+    Deliberately tolerant: a missing or unparseable timestamp must never stop a reap. Age is for
+    the LOG — so an orphan leaves a trace saying how long it had been burning — not for the
+    decision about whether to kill it.
+    """
+    import datetime as _dt
+    for key in ("createdAt", "created_at", "lastStatusChange", "podCreatedAt"):
+        raw = pod.get(key)
+        if not raw:
+            continue
+        text = str(raw)
+        # "Rented by user: Mon Sep 15 2026 17:05:17 GMT+0000" and friends.
+        if ":" in text and not text[:4].isdigit():
+            text = text.split(":", 1)[1].strip()
+        for fmt in ("%Y-%m-%dT%H:%M:%S.%fZ", "%Y-%m-%dT%H:%M:%SZ", "%Y-%m-%dT%H:%M:%S",
+                    "%a %b %d %Y %H:%M:%S GMT%z", "%a %b %d %Y %H:%M:%S"):
+            try:
+                when = _dt.datetime.strptime(text[:len(_dt.datetime.now().strftime(fmt)) + 8]
+                                             if "%z" not in fmt else text, fmt)
+            except Exception:
+                continue
+            if when.tzinfo is None:
+                when = when.replace(tzinfo=_dt.timezone.utc)
+            return (_dt.datetime.now(_dt.timezone.utc) - when).total_seconds() / 3600.0
+    return None
+
+
+def _pool_scope(name: str) -> str:
+    """The ownership prefix for a pod name — 'frutebox-runpod-1' owns 'frutebox-runpod'.
+
+    Scoping by the POOL BASE, not the exact name, is deliberate: a create that lands under a
+    slightly different name (the 2026-08-21 asymmetry) is still ours and must still be reapable.
+    """
+    import re as _re
+    return _re.sub(r"-\d+$", "", str(name or "")) or str(name or "")
+
+
+def _describe(pod: dict) -> str:
+    age = _pod_age_hours(pod)
+    return (f"id={pod.get('id')} name={pod.get('name')!r} "
+            f"desired={pod.get('desiredStatus')} runtime={'yes' if pod.get('runtime') else 'None'} "
+            f"gpus={pod.get('gpuCount')} age={'%.2fh' % age if age is not None else 'unknown'} "
+            f"cost/hr={pod.get('costPerHr')}")
+
+
+# ---- §A9: credentials come from the registry, not the environment ---------------------------
+#
+# THE SPLIT THIS CLOSES (plan 28 §A9, done-criteria at 28:108). The encrypted registry in Neon was
+# built, populated and correct — and had exactly one caller, the provider-doctor. Every path that
+# actually launched a machine read `os.environ`. So the diagnostic read the database and the
+# launcher read the environment, and the two could disagree indefinitely: a provider reported
+# healthy while nothing could launch. `directory_control.py` warns about that exact shape.
+#
+# Precedence is the section's: DATABASE FIRST, env as the cold-start/local-dev fallback. A stale
+# env var outranking a rotated DB credential is what §A9 exists to remove.
+
+#: Rotation window. `_key()` is called per operation via `_sdk()`, so an uncached read would be an
+#: HTTP round trip per SDK call. Short enough that 28:108's "rotating a credential causes no
+#: downtime" means minutes, not "whenever this process restarts".
+_CREDENTIAL_TTL_S = float(envvar("CREDENTIAL_TTL_S", "60"))
+
+#: provider_id -> (fetched_at, {name: value}). Process-local by design: the directory is the only
+#: service that launches, and a shared cache would be a second source of truth.
+_CRED_CACHE: "Dict[str, tuple]" = {}
+
+
+def _credential_cache_clear() -> None:
+    """Drop everything. Tests and an explicit operator refresh."""
+    _CRED_CACHE.clear()
+
+
+def _credential_cache_expire_now() -> None:
+    """Age every entry past the TTL without discarding its value — so a refresh is attempted and
+    the LAST GOOD VALUE is still there to fall back on if that refresh fails."""
+    for pid, (_, creds) in list(_CRED_CACHE.items()):
+        _CRED_CACHE[pid] = (0.0, creds)
+
+
+def _resolve_provider_credentials(provider_id: str) -> Dict[str, str]:
+    """The boundary: one registry read for one provider. Patched wholesale in tests.
+
+    Kept as a module-level function rather than inlined so there is exactly one place the registry
+    is consulted from the launch path — the same reason this file is the single door for RunPod.
+    """
+    from . import providers as _reg
+    row = next((r for r in _reg.load_seed() if r.id == provider_id), None)
+    if row is None:
+        return {}
+    return _reg.resolve_credentials(row, _reg.fetch_credentials(provider_id))
+
+
+def _provider_credential(provider_id: str, name: str, *, env_name: "str | None" = None) -> str:
+    """One credential, database first, env second, cached for `_CREDENTIAL_TTL_S`.
+
+    A FAILED OR EMPTY REFRESH NEVER EVICTS A GOOD VALUE. `fetch_credentials` returns `{}` on any
+    failure by design — including failures it cannot distinguish from "no rows" — so an empty
+    answer is not evidence that a credential was deleted. Treating it as such would turn a network
+    blip into "every provider unconfigured", silently, which is the degradation shape this
+    codebase keeps finding. The cache is therefore last-known-good, not a mirror.
+    """
+    env_name = env_name or name
+    now = time.monotonic()
+    cached = _CRED_CACHE.get(provider_id)
+    if cached is not None and (now - cached[0]) < _CREDENTIAL_TTL_S:
+        creds = cached[1]
+    else:
+        try:
+            fresh = _resolve_provider_credentials(provider_id) or {}
+        except Exception as e:
+            log.warning("credential refresh for %s failed (%s) — serving the last known value",
+                        provider_id, type(e).__name__)
+            fresh = {}
+        if fresh:
+            _CRED_CACHE[provider_id] = (now, fresh)
+            creds = fresh
+        elif cached is not None:
+            # Keep the value, reset the clock so we do not hammer a failing source every call.
+            _CRED_CACHE[provider_id] = (now, cached[1])
+            creds = cached[1]
+        else:
+            creds = {}
+    value = str(creds.get(name, "") or "").strip()
+    if value:
+        return value
+    # §A9.3 / §O2: the env read survives as the cold-start / local-dev fallback. What is removed
+    # is the env OUTRANKING the database, not the env existing.
+    #
+    # THIS GATE WAS ABSENT AND THAT WAS LOAD-BEARING. Until §O1 landed, every registry read failed
+    # with EnvelopeError, so this unconditional fallback was the only reason the platform launched
+    # anything at all. With the registry path working, an ungated fallback becomes the bug it was
+    # written to prevent: a credential rotated in the database would never take effect, because a
+    # stale environment variable would answer first and nothing would say so.
+    #
+    # `providers.ENV_FALLBACK` is read at CALL time, not bound at import, so the flag can be
+    # changed (and tested) without reimporting the module.
+    from . import providers as _reg_flag
+    if not getattr(_reg_flag, "ENV_FALLBACK", False):
+        return ""
+    return os.environ.get(env_name, "").strip()
+
+
+def provider_credential(provider_id: str, name: str, *, env_name: "str | None" = None) -> str:
+    """THE PUBLIC DOOR for one provider credential: database first, env second, cached.
+
+    WHY THIS EXISTS AS A SEPARATE NAME (BACKEND ask, 2026-10-17). `_provider_credential` below is
+    the implementation and its leading underscore says "internal to this module" — but three
+    modules outside it were already reaching past that underscore (`serving.py`, `nodewake.py`,
+    `runpod_templates.py`). A private name with external callers is not private; it is an
+    undocumented API with a discouraging prefix, and the next person to refactor the private one
+    breaks three files with no signal that they were a contract.
+
+    So the contract is named. This is what code outside `gpuproviders` should call, and the §O
+    precedence it guarantees is the whole point of routing through here rather than reading
+    `os.environ`: file 28 §O made the DATABASE the source of truth, so a direct env read answers
+    "absent" for any deployment whose credential lives in the DB — which is the silent degradation
+    `tests/test_provider_credential_env_bypass_guard.py` exists to prevent.
+
+    IT DELEGATES, AND IT MUST NOT BECOME AN ALIAS. `provider_credential = _provider_credential`
+    would bind the implementation object at import time, so the four suites that monkeypatch
+    `gpuproviders._provider_credential` (alibaba, phala, and others) would patch the private name
+    while this public one went on calling the original — tests that pass while testing nothing.
+    One extra stack frame buys that correctness; please leave it.
+    """
+    return _provider_credential(provider_id, name, env_name=env_name)
+
+
+#: The most GPUs one pod may be created with. RunPod's own ceiling is 8 for the multi-GPU types
+#: this account uses; the cap is here so a mis-typed `gpuCount` cannot become an hourly bill.
+MAX_GPU_COUNT = int(envvar("POD_MAX_GPU_COUNT", "8"))
+
+#: Env keys that are PER POD and must never reach the template hash.
+#:
+#: This was the bug that stopped the fleet booting. `nodewake` injects `STEVAI_NODE_ID` into each
+#: pod's env, so the projection hashed to a DIFFERENT name for every pod: `find_template_id` could
+#: never match, `create_template` was attempted with a brand-new name every time, and the function
+#: minted a template per attempt — the exact thing its own docstring says must not happen. The
+#: leftover `frutebox-node-*` templates on the account are that residue. When template creation
+#: then started failing, the guard refused every create and NOTHING COULD START.
+#:
+#: The rest of the env stays in the hash for the reason the docstring gives: a changed gateway URL
+#: or node credential must not resolve to a template carrying the old one. Only the values that
+#: are per-pod by construction come out.
+_PER_POD_ENV = ("STEVAI_NODE_ID", "FRUTEBOX_NODE_ID")
+
+
+def _template_env(env: dict, dedicated: bool = False) -> dict:
+    """The env a TEMPLATE carries: everything except what differs between two pods of one spec.
+
+    `dedicated=True` (a NAMED VARIANT — see `PodSpec.dedicated_template`) keeps the per-pod keys,
+    because a variant is one pod whose identity is the point of it. One variant = one template.
+
+    WHICH LAYER WINS IS NO LONGER A QUESTION ANYONE HAS TO ANSWER. `create_pod` sends `env=` and
+    `template_id=` together and RunPod does not document which it prefers; the old code put
+    DIFFERENT values on the two layers and therefore depended on that answer. Now this one
+    function is the single source for the template's env, and it is used BOTH to name the template
+    and to create it, so the two layers either agree or the template is not reused. Whichever
+    RunPod prefers, it prefers the same value.
+
+    THE BUG THAT MADE THIS NECESSARY: the name hashed `_template_env(...)` while the content was
+    created from the FULL `spec.env`. A template's baked env therefore did not match its own name,
+    so a template minted by one pod was reused by another whose per-pod values differed — and the
+    media pod matched a pre-existing template created without any `STEVAI_NODE_ID`, booted on
+    `entrypoint.sh`'s `runpod-node-1` default, collided with the live node and advertised text.
+    """
+    if dedicated:
+        return dict(env or {})
+    return {k: v for k, v in (env or {}).items() if k not in _PER_POD_ENV}
+
+
+#: The last error each GPU type's create returned, so a refusal can say WHY rather than guess.
+#: Keyed by type id; overwritten per attempt, which is all a diagnostic needs.
+_LAST_CREATE_ERROR: Dict[str, str] = {}
+
+
+class RunPodProvider:
+    name = "runpod"
+    #: GraphQL endpoint — used ONLY for the price query, for which the SDK has no call. Everything
+    #: with a lifecycle (create/get/terminate) goes through the SDK: hand-rolling the pod query
+    #: once produced a readiness predicate that could never pass (KB incident 2026-08-30).
+    _GQL = "https://api.runpod.io/graphql"
+
+    def _key(self) -> str:
+        return _provider_credential("runpod", "RUNPOD_API_KEY")
+
+    def configured(self) -> bool:
+        return bool(self._key())
+
+    def _sdk(self):
+        """The configured SDK, or None. None is just another reason a bring-up cannot happen —
+        it must never crash the control plane."""
+        try:
+            import runpod as _rp
+        except Exception:
+            log.warning("runpod SDK not installed")
+            return None
+        key = self._key()
+        if not key:
+            return None
+        _rp.api_key = key
+        return _rp
+
+    # -- observations ------------------------------------------------------------------------
+
+    async def get_pod(self, pod_id: str) -> "dict | None":
+        """One pod. None means RunPod no longer knows it — the signal a reap waits for.
+
+        A transport/SDK error returns {} instead: "I could not ask" must never be mistaken for
+        "it is gone", or a reaper declares a billing pod dead on a network blip.
+        """
+        rp = self._sdk()
+        if rp is None:
+            return {}
+        try:
+            import asyncio as _a
+            return await _a.wait_for(_a.to_thread(rp.get_pod, pod_id), timeout=45)
+        except Exception as e:
+            msg = str(e).lower()
+            if "not found" in msg or "does not exist" in msg:
+                return None
+            log.warning("runpod get_pod %s: %s", pod_id, type(e).__name__)
+            return {}
+
+    async def list_pods(self) -> List[dict]:
+        """Every pod on the account, whatever its state. For planning and teardown."""
+        rp = self._sdk()
+        if rp is None:
+            return []
+        try:
+            import asyncio as _a
+            return list(await _a.wait_for(_a.to_thread(rp.get_pods), timeout=45) or [])
+        except Exception as e:
+            log.warning("runpod get_pods: %s", type(e).__name__)
+            return []
+
+    async def list_live(self) -> List[dict]:
+        """Pods that are actually UP: desiredStatus RUNNING **and** a runtime object.
+
+        `desiredStatus` alone is a statement of intent RunPod sets the moment a record exists —
+        counting on it is how a corpse held the pool's only slot for a night.
+        """
+        return [p for p in await self.list_pods()
+                if str(p.get("desiredStatus", "")).upper() == "RUNNING" and p.get("runtime")]
+
+    async def _list_pods_or_none(self) -> "Optional[List[dict]]":
+        """The account's pods, or None when the ASK ITSELF failed.
+
+        `list_pods` flattens a transport error to `[]`, which is right for planning and fatal for
+        reaping: an empty list would read as "no orphans" on exactly the network blip where you
+        most need to look again. The reaper must be able to tell "nothing there" from "I could
+        not see".
+        """
+        rp = self._sdk()
+        if rp is None:
+            return None
+        try:
+            import asyncio as _a
+            return list(await _a.wait_for(_a.to_thread(rp.get_pods), timeout=45) or [])
+        except Exception as e:
+            log.error("reap: could not list pods (%s) — CANNOT conclude the account is clean",
+                      type(e).__name__)
+            return None
+
+    # -- the reaper ---------------------------------------------------------------------------
+
+    async def reap(self, tracker: "Optional[PodTracker]" = None, *, owns: str = "",
+                   dry_run: bool = False, reap_unowned: bool = False,
+                   settle_s: float = 0.0) -> dict:
+        """Reconcile against RunPod's own list and terminate what nothing is holding.
+
+        `tracker` supplies the kept set; without one, NOTHING is kept — that is the standalone
+        sweep. `owns` scopes which names may be terminated (see the ownership note below);
+        `reap_unowned=True` drops that scope and kills everything unkept.
+
+        `settle_s` > 0 re-lists until it stops finding new pods, for the case this whole class
+        exists for: a create whose call timed out, whose pod appears a minute later.
+
+        OWNERSHIP. By default the reaper only TERMINATES pods whose name starts with `owns`;
+        anything else it reports loudly but leaves alone. That protects the two kinds of pod a
+        blanket reap would destroy: `diag_create` pods, which exist precisely so the owner can
+        read boot failures in the console (the API exposes no pod logs), and anything the owner
+        started by hand. Unowned pods are never silently ignored — they are logged as ORPHAN? and
+        returned in `unowned`, so a sweep still surfaces them.
+        """
+        import asyncio as _a
+        kept = set(tracker.kept) if tracker else set()
+        scope = owns or (tracker.owns if tracker else "")
+
+        pods = await self._list_pods_or_none()
+        if pods is None:
+            return {"ok": False, "error": "could not list pods", "terminated": [],
+                    "kept": sorted(kept), "unowned": []}
+
+        # Settle: an ambiguous create can land AFTER the call that made it returned.
+        if settle_s > 0:
+            deadline = time.monotonic() + settle_s
+            known = {str(x.get("id")) for x in pods}
+            while time.monotonic() < deadline:
+                await _a.sleep(_SETTLE_POLL_S)
+                again = await self._list_pods_or_none()
+                if again is None:
+                    continue
+                fresh = {str(x.get("id")) for x in again} - known
+                pods = again
+                if fresh:
+                    log.warning("reap: %d pod(s) appeared AFTER the create returned: %s",
+                                len(fresh), ", ".join(sorted(fresh)))
+                    known |= fresh
+                    deadline = time.monotonic() + settle_s   # something moved; watch again
+
+        terminated, failed, unowned, suspected = [], [], [], []
+        for pod in pods:
+            pid, pname = str(pod.get("id") or ""), str(pod.get("name") or "")
+            if not pid or pid in kept:
+                continue
+            if scope and not reap_unowned and not pname.startswith(scope):
+                age = _pod_age_hours(pod)
+                # An unowned pod is left alone (a diag pod is the point of the exception) — but
+                # "left alone" must never mean "quietly tolerated". Past the suspect age it is
+                # escalated: ERROR, and carried out in `suspected_orphans` so the caller's exit
+                # status can reflect it. A 13-hour pod in a reported bucket is how this cost $6.54.
+                old_enough = age is None or age >= _ORPHAN_SUSPECT_AGE_H
+                entry = {"id": pid, "name": pname, "age_h": age}
+                if old_enough:
+                    log.error("reap: SUSPECTED ORPHAN — not mine, %s old, LEAVING IT but this "
+                              "needs a human: %s. Reap it with: python -m frutebox.podreaper "
+                              "--sweep --all",
+                              ("unknown age" if age is None else "%.2fh" % age), _describe(pod))
+                    suspected.append(entry)
+                else:
+                    log.warning("reap: not mine, leaving it (only %.2fh old): %s",
+                                age, _describe(pod))
+                unowned.append(entry)
+                continue
+            if dry_run:
+                log.warning("reap: WOULD TERMINATE (dry run): %s", _describe(pod))
+                terminated.append(pid)
+                continue
+            log.error("reap: TERMINATING untracked pod: %s", _describe(pod))
+            (terminated if await self.terminate(pid) else failed).append(pid)
+
+        if terminated and not dry_run:
+            log.error("reap: terminated %d untracked pod(s): %s — a pod reached this point "
+                      "because nothing confirmed it was wanted", len(terminated),
+                      ", ".join(terminated))
+        if suspected:
+            log.error("reap: %d SUSPECTED ORPHAN(S) older than %.0f min left running: %s",
+                      len(suspected), _ORPHAN_SUSPECT_AGE_H * 60,
+                      ", ".join(x["id"] for x in suspected))
+        return {"ok": not failed, "terminated": terminated, "kept": sorted(kept),
+                "unowned": unowned, "suspected_orphans": suspected,
+                **({"failed": failed} if failed else {})}
+
+    @contextlib.asynccontextmanager
+    async def creation_guard(self, owns: str, *, dry_run: bool = False):
+        """Wrap every window in which a pod may be created. Yields a `PodTracker`.
+
+        The reap runs in a `finally`: an exception, a timeout, a cancelled task or a
+        KeyboardInterrupt cannot skip it. Anything the caller did not `keep()` dies.
+
+            async with rp.creation_guard("frutebox-runpod") as t:
+                pod_id = await rp.create_pod(spec, gpu, cloud)
+                if pod_id and await rp.wait_ready(pod_id, spec):
+                    t.keep(pod_id)          # <- the ONLY thing that spares it
+        """
+        tracker = PodTracker(owns)
+        token = _TRACKER.set(tracker)
+        try:
+            yield tracker
+        finally:
+            _TRACKER.reset(token)
+            try:
+                # An ambiguous create means a pod may still be on its way: wait for it.
+                settle = _SETTLE_S if tracker.ambiguous else 0.0
+                result = await self.reap(tracker, dry_run=dry_run, settle_s=settle)
+                if result.get("terminated"):
+                    log.error("creation_guard(%s): reaped %s", owns, result["terminated"])
+                # A suspected orphan is not this window's to kill, but the NEXT wake must not be
+                # able to proceed as if the account were clean. Recorded where the caller sees it.
+                if result.get("suspected_orphans"):
+                    _SUSPECTED.extend(result["suspected_orphans"])
+                    log.error("creation_guard(%s): %d suspected orphan(s) still running — "
+                              "BILLING. %s", owns, len(result["suspected_orphans"]),
+                              ", ".join(x["id"] for x in result["suspected_orphans"]))
+            except Exception as e:                       # a failing reaper must still be LOUD
+                log.error("creation_guard(%s): REAP FAILED (%s) — pods MAY BE BILLING, sweep "
+                          "with: python -m frutebox.podreaper --sweep", owns, type(e).__name__)
+
+
+    @staticmethod
+    def pod_runtime_ready(pod: "dict | None") -> bool:
+        """PURE. A live `runtime` with mapped ports — never `desiredStatus`.
+
+        Deliberately reads ONLY fields the SDK's pod query selects (`runtime { ports {...} }`).
+        A predicate that once required `runtime.uptimeInSeconds` — a field the query cannot
+        return — was structurally impossible to satisfy and reaped six healthy pods in a night.
+        The guard test asserts every field read here appears in the SDK's own query text.
+        """
+        if not pod:
+            return False
+        rt = pod.get("runtime") or {}
+        return bool(rt) and bool(rt.get("ports"))
+
+    @staticmethod
+    def proxy_url(pod_id: str, port: int) -> str:
+        return f"https://{pod_id}-{port}.proxy.runpod.net"
+
+    async def serves(self, pod_id: str, port: int, path: str = "/") -> bool:
+        """A REAL request to the served port — not a TCP probe.
+
+        The User-Agent matters: RunPod's proxy rejects requests that do not look like a browser
+        or curl, which once made a stream of perfectly healthy pods look dead.
+
+        `path` comes from `PodSpec.health_path`, because "what counts as answering" is a property
+        of the SERVER, not of this door — see that field for the engine that has no `/`.
+        """
+        try:
+            async with httpx.AsyncClient(timeout=20) as c:
+                r = await c.get(f"{self.proxy_url(pod_id, port)}{path or '/'}",
+                                headers={"user-agent": "curl/8.4.0"})
+                return r.status_code == 200
+        except Exception:
+            return False
+
+    # -- lifecycle ---------------------------------------------------------------------------
+
+    async def wait_ready(self, pod_id: str, spec: PodSpec,
+                         extra_ready: "Optional[Callable[[], bool]]" = None) -> bool:
+        """Poll until the pod has a live runtime AND serves, or give up.
+
+        `extra_ready` lets the CALLER add its own success signal (the pool passes "a node
+        registered with the directory", the strongest possible proof for our own image) without
+        this module knowing anything about directories.
+
+        Returns False rather than raising: the caller's next move is reap-and-fallback, and an
+        exception here would skip the reap and leave a billing pod behind.
+        """
+        import asyncio as _a
+        waited = 0.0
+        while waited < spec.ready_timeout_s:
+            pod = await self.get_pod(pod_id)
+            if pod is None:
+                log.warning("pod %s vanished while waiting for readiness", pod_id)
+                return False
+            status = str(pod.get("desiredStatus", "")).upper()
+            if status and status != "RUNNING":
+                log.warning("pod %s left RUNNING (%s) before becoming ready", pod_id, status)
+                return False
+            if self.pod_runtime_ready(pod):
+                if extra_ready is not None and extra_ready():
+                    log.info("pod %s READY after %.0fs (registered)", pod_id, waited)
+                    return True
+                if await self.serves(pod_id, spec.serving_port, spec.health_path):
+                    log.info("pod %s READY after %.0fs (runtime live and serving)", pod_id, waited)
+                    return True
+            await _a.sleep(spec.poll_s)
+            waited += spec.poll_s
+        log.warning("pod %s NOT ready after %.0fs. Reaping.", pod_id, spec.ready_timeout_s)
+        return False
+
+    async def terminate(self, pod_id: str, verify_timeout_s: float = 120, poll_s: float = 5) -> bool:
+        """Terminate AND VERIFY the pod is gone. The API's 2xx is never the evidence — REST
+        DELETE returns 2xx without stopping the pod, and it keeps BILLING. The terminate is
+        re-issued each round until the pod query stops returning it."""
+        import asyncio as _a
+        rp = self._sdk()
+        if rp is None:
+            return False
+
+        async def _issue():
+            try:
+                await _a.wait_for(_a.to_thread(rp.terminate_pod, pod_id), timeout=45)
+            except Exception as e:
+                log.warning("runpod terminate_pod %s: %s", pod_id, type(e).__name__)
+
+        await _issue()
+        waited = 0.0
+        while waited < verify_timeout_s:
+            pod = await self.get_pod(pod_id)
+            if pod is None:
+                log.info("pod %s terminated and verified gone", pod_id)
+                return True
+            await _a.sleep(poll_s)
+            waited += poll_s
+            await _issue()                     # RunPod sometimes needs it more than once
+        log.error("PANIC: pod %s still present %.0fs after terminate — MAY BE BILLING",
+                  pod_id, verify_timeout_s)
+        return False
+
+    async def _template_id_for(self, spec: PodSpec) -> "str | None":
+        """The RunPod template that carries this spec's registry credential, found or created.
+
+        NO CACHE, DELIBERATELY. The name is a hash of the spec's own contents, so the same spec
+        always resolves to the same name; we re-find the template by ASKING RunPod rather than by
+        remembering an id. A remembered id would be a second place holding something derived from
+        the spec, and it would drift the moment the spec changed and the memory did not.
+
+        Measured 2026-09-20: `create_template` with a name that already exists FAILS with
+        "Template name must be unique." — it does not return the existing id and does not make a
+        duplicate. So the find MUST come first, templates cannot leak, and the count is bounded
+        server-side by the number of distinct specs.
+        """
+        import asyncio as _a
+        from . import runpod_templates as rt
+
+        rp = self._sdk()
+        if rp is None:
+            return None
+        # The projection: only what the template actually carries. Not the pod name, not the GPU —
+        # those vary per attempt and would mint a template per attempt.
+        projection = {
+            "image_name": spec.image,
+            "container_disk_in_gb": spec.container_disk_gb,
+            "ports": ports_string(spec),
+            "registry_auth_id": spec.container_registry_auth_id,
+            # THE ENV GOES ON THE TEMPLATE TOO, and it is part of the name.
+            #
+            # `create_pod` sends `env=` and `template_id=` in the same call, and which layer wins
+            # is not documented. That is not a question worth renting a pod to answer: putting the
+            # env on BOTH means the node boots with its credential and its gateway URL either way.
+            # Whichever layer RunPod prefers, it prefers the same values.
+            #
+            # It belongs in the hash for the same reason everything else here does — a node
+            # credential or a gateway URL that changed while the name stayed put would resolve to
+            # a template carrying the OLD one, and the pod would boot with stale identity. The
+            # hash is sha256 and only the digest is ever used, so no value is exposed by it.
+            "env": _template_env(spec.env, spec.dedicated_template),
+        }
+        name = rt.template_name(projection)
+
+        found = await _a.to_thread(rt.find_template_id, name)
+        if found:
+            log.info("template %s found (%s)", name, found)
+            return found
+        try:
+            res = await _a.wait_for(_a.to_thread(lambda: rp.create_template(
+                name=name,
+                image_name=spec.image,
+                container_disk_in_gb=spec.container_disk_gb,
+                ports=ports_string(spec),
+                registry_auth_id=spec.container_registry_auth_id,
+                # THE SAME PROJECTION THAT NAMED IT. Creating with the full env while naming with
+                # a stripped one is what let a template's content drift from its own name.
+                env=_template_env(spec.env, spec.dedicated_template),
+            )), timeout=60)
+        except Exception as e:
+            # Someone may have created it between our find and our create. Ask once more before
+            # giving up — the uniqueness error is exactly what a race looks like.
+            log.warning("template %s create failed (%s: %s); re-checking",
+                        name, type(e).__name__, str(e)[:160])
+            return await _a.to_thread(rt.find_template_id, name)
+        tid = (res or {}).get("id")
+        log.info("template %s created (%s)", name, tid)
+        return str(tid) if tid else None
+
+    async def create_pod(self, spec: PodSpec, gpu_type_id: str, cloud_type: str,
+                         data_center_id: str = "") -> "str | None":
+        """One create attempt. Every refusal is surfaced with RunPod's own reply — a silent None
+        once cost three armed windows spent guessing."""
+        import asyncio as _a
+        rp = self._sdk()
+        if rp is None:
+            return None
+        gpu_count = max(1, min(int(spec.gpu_count), MAX_GPU_COUNT))
+        if gpu_count != int(spec.gpu_count):
+            # A spec asking for more cards than the cap gets the cap, loudly. Silently honouring
+            # an absurd count is how one typo becomes an hourly bill nobody chose.
+            log.error("spec %s asked for %s GPUs; capped at %s (STEVAI_POD_MAX_GPU_COUNT)",
+                      spec.name, spec.gpu_count, gpu_count)
+        if gpu_count > 1:
+            # SAY IT. `from_operator_spec` now reads the operator's `gpuCount`, which it ignored
+            # for as long as it existed — so a configured frontier spec that always produced a
+            # 1-GPU pod suddenly produces the 8-GPU pod it always asked for. That is the intent
+            # (a 1-GPU frontier pod cannot load the model at all), and it is an 8x hourly cost
+            # change, so it belongs in the log at the moment the money is committed.
+            log.warning("MULTI-GPU POD: %s x %s — hourly cost scales with the count",
+                        gpu_count, gpu_type_id)
+        kwargs = dict(
+            name=spec.name,
+            image_name=spec.image,
+            gpu_type_id=gpu_type_id,
+            cloud_type=cloud_type,
+            gpu_count=gpu_count,
+            container_disk_in_gb=spec.container_disk_gb,
+            volume_in_gb=spec.volume_gb,
+            ports=ports_string(spec),
+            docker_args=spec.docker_args,
+            support_public_ip=True,
+            env=dict(spec.env),
+            # THE FIX for "RUNNING but no runtime, ever": without a CUDA filter the pod can land
+            # on an old-driver host where the container fails OCI-create BEFORE any process starts
+            # (unsatisfied condition: cuda>=12.x) — billing, empty logs, no runtime.
+            allowed_cuda_versions=[v.strip() for v in envvar("ALLOWED_CUDA", "12.4,12.5,12.6,12.7,12.8").split(",") if v.strip()],
+        )
+        # A PRIVATE image needs a registry credential, and create_pod takes none — it travels as
+        # a template. Only when the spec carries one: a public image (the PROBE spec pulls
+        # ollama/ollama:latest from Docker Hub) must go out with no template and no credential.
+        if spec.container_registry_auth_id:
+            template_id = await self._template_id_for(spec)
+            if not template_id:
+                log.error("create REFUSED name=%s: the spec needs a registry credential but no "
+                          "template could be found or created — a pod without one is rented and "
+                          "exits in seconds", spec.name)
+                return None
+            kwargs["template_id"] = template_id
+        if spec.network_volume_id:
+            kwargs["network_volume_id"] = spec.network_volume_id
+        # A network volume is DATACENTER-LOCKED: when one is attached, the volume's datacenter
+        # overrides whatever the fallback entry says — deploying anywhere else cannot mount it,
+        # which is a pod that bills and serves nothing. Without a volume, the entry's DC (if any)
+        # applies, else placement stays free.
+        dc = (spec.data_center_id if spec.network_volume_id else "") \
+            or data_center_id or spec.data_center_id
+        if dc:
+            kwargs["data_center_id"] = dc
+        log.info("create attempt: name=%s gpu=%sx%s cloud=%s dc=%s",
+                 spec.name, kwargs["gpu_count"], gpu_type_id, cloud_type,
+                 kwargs.get("data_center_id", "-"))
+        # Who was on the account BEFORE we asked. The only way to tell an ambiguous create's pod
+        # from someone else's is to know what was already there.
+        before = {str(x.get("id")) for x in (await self._list_pods_or_none() or [])}
+        tracker = _TRACKER.get()
+        if tracker is None:
+            log.warning("create_pod(%s) is running OUTSIDE a creation_guard — if this call times "
+                        "out, nothing will reap what it may have created", spec.name)
+        try:
+            # BOUNDED. On 2026-08-30 a create call hung inside the SDK with no timeout, holding
+            # the reconcile lock — one pool-plan log line, then silence, while every tick skipped
+            # as busy and the operator had no window into why. A stuck transport call is a
+            # REFUSAL, loudly, never a wedge.
+            pod = await _a.wait_for(_a.to_thread(lambda: rp.create_pod(**kwargs)), timeout=180)
+        except Exception as e:
+            # NOT "nothing was created". `wait_for` cancels the AWAIT, not the blocking SDK call
+            # running in the worker thread — that request is still in flight and RunPod may honour
+            # it seconds or minutes from now. On 2026-09-17 this exact path returned None, the
+            # caller moved to the next fallback, the process exited, and the pod that arrived
+            # afterwards billed for 13h20m. Reconcile against RunPod's list; do not guess.
+            _LAST_CREATE_ERROR[gpu_type_id] = f"{type(e).__name__}: {str(e)[:160]}"
+            log.error("create AMBIGUOUS gpu=%s cloud=%s: %s: %s — a pod MAY have been created; "
+                      "reconciling against RunPod's list", gpu_type_id, cloud_type,
+                      type(e).__name__, str(e)[:300])
+            if tracker is not None:
+                tracker.ambiguous.add(spec.name)
+            pod_id = await self._find_created_after(spec.name, before)
+            if pod_id:
+                log.error("create AMBIGUOUS but a pod DID appear: %s — adopting it so the normal "
+                          "ready-or-reap path owns it", pod_id)
+                if tracker is not None:
+                    tracker.saw(pod_id)
+                return pod_id
+            # Still nothing. The guard's exit reap re-checks with a settle window, because it can
+            # still show up after we return.
+            return None
+        pod_id = (pod or {}).get("id")
+        if not pod_id:
+            log.warning("create refused gpu=%s cloud=%s reply=%s",
+                        gpu_type_id, cloud_type, str(pod)[:300])
+        elif tracker is not None:
+            tracker.saw(pod_id)
+        return pod_id
+
+    async def _find_created_after(self, name: str, before: "Set[str]",
+                                  window_s: "float | None" = None,
+                                  poll_s: "float | None" = None) -> "str | None":
+        """Poll RunPod for a pod named `name` that was not on the account before we asked.
+
+        Bounded, because the alternative to waiting is guessing, and guessing here costs money
+        per hour. A pod that appears later than this window is caught by the guard's exit reap.
+        """
+        import asyncio as _a
+        window_s = _AMBIGUOUS_WINDOW_S if window_s is None else window_s
+        poll_s = _AMBIGUOUS_POLL_S if poll_s is None else poll_s
+        waited = 0.0
+        while waited <= window_s:
+            pods = await self._list_pods_or_none()
+            if pods is not None:
+                for pod in pods:
+                    pid = str(pod.get("id") or "")
+                    if pid and pid not in before and str(pod.get("name") or "") == name:
+                        return pid
+            await _a.sleep(poll_s)
+            waited += poll_s
+        return None
+
+    async def create_ready(self, spec: PodSpec,
+                           extra_ready: "Optional[Callable[[], bool]]" = None) -> "str | None":
+        """Deploy → verify → reap → next candidate, across the spec's GPU/cloud fallbacks.
+
+        Returns the pod id only once it is genuinely serving. Anything that does not get there is
+        terminated (with verification) before the next attempt, so a run of failures cannot leave
+        a trail of billing corpses. None after the whole list = a genuine provider shortage — the
+        caller escalates, never spins.
+        """
+        # EVERY create in this method happens inside the guard, so no exit path — exhausted
+        # fallbacks, an exception, a cancelled task — can leave a pod nothing is holding. The
+        # only pod that survives is the one we explicitly `keep()` below.
+        async with self.creation_guard(_pool_scope(spec.name)) as tracker:
+            return await self._create_ready_guarded(spec, tracker, extra_ready)
+
+    async def _create_ready_guarded(self, spec: PodSpec, tracker: PodTracker,
+                                    extra_ready: "Optional[Callable[[], bool]]" = None) -> "str | None":
+        model = str(spec.env.get("STEVAI_OLLAMA_MODEL", "") or "")
+        # LIVE STOCK FIRST. The static list is the candidate SET; which of them can actually be
+        # rented right now, and in what order, is a question only the provider can answer. Fails
+        # open to the static order — see `rank_by_availability`.
+        ordered = await self.rank_by_availability(spec.gpu_fallbacks, model=model,
+                                                  disk_gb=spec.container_disk_gb)
+        for entry in ordered:
+            gpu_type_id, cloud_type = entry[0], entry[1]
+            entry_dc = entry[2] if len(entry) > 2 else ""
+            # A doomed combination is refused BEFORE money is spent. This is the assertion form of
+            # the 2026-08-30 root cause: a tier-S model on an A40 booted, billed, and "loaded"
+            # forever — and looked exactly like a provider fault.
+            if model:
+                err = model_fit_error(model, gpu_type_id,
+                                      spec.gpu_count, spec.container_disk_gb)
+                if err:
+                    log.error("REFUSING create gpu=%s cloud=%s: %s", gpu_type_id, cloud_type, err)
+                    continue
+            pod_id = await self.create_pod(spec, gpu_type_id, cloud_type, data_center_id=entry_dc)
+            if not pod_id:
+                continue
+            log.info("placed pod=%s gpu=%s cloud=%s — verifying it actually serves",
+                     pod_id, gpu_type_id, cloud_type)
+            if await self.wait_ready(pod_id, spec, extra_ready=extra_ready):
+                log.info("READY pod=%s gpu=%s cloud=%s", pod_id, gpu_type_id, cloud_type)
+                tracker.keep(pod_id)          # the ONLY thing that spares it from the reaper
+                return pod_id
+            log.warning("not ready in time; reaping pod=%s gpu=%s cloud=%s",
+                        pod_id, gpu_type_id, cloud_type)
+            await self.terminate(pod_id)
+        log.error("all fallbacks exhausted — genuine RunPod capacity shortage, not a retry loop")
+        return None
+
+    # -- diagnostics (owner-driven boot debugging) ---------------------------------------------
+
+    async def rank_by_availability(self, candidates, *, model: str = "",
+                                   disk_gb: int = 40) -> list:
+        """Order (gpu, cloud[, dc]) candidates by LIVE STOCK and price; drop what cannot be rented.
+
+        WHY THIS EXISTS. `gpu_fallbacks` is a static list written when it was written. On
+        2026-09-28 every card the WARM spec pins — A40, RTX A5000, RTX A6000, L40S — was out of
+        stock simultaneously, so a wake tried four combinations, spent ~75s on each (RunPod's
+        "no instances available" is ambiguous, so the provider reconciles against the live pod list
+        before giving up), and produced nothing. The same thing happening at 3am to a standby that
+        has died is a network with no capacity and nobody watching.
+
+        `lowestPrice` is null for a card with no stock, so this is a real availability signal.
+        Capacity also MOVES: L40S went from no-stock to $0.79 inside two minutes the same day,
+        which is why this is queried per wake and never cached.
+
+        IT FAILS OPEN, DELIBERATELY. If the price query cannot be answered — no credential, the
+        vendor is down — this returns the caller's original order untouched. The alternative is a
+        wake that refuses to try because it could not read a price list, which turns a degraded
+        signal into no capacity at all. Same for the case where every candidate reports no stock:
+        the static order is still attempted, because a stale "no stock" must not be the reason
+        nothing is tried.
+        """
+        original = [tuple(c) for c in candidates]
+        try:
+            types = await self.gpu_prices()
+        except Exception as e:                            # noqa: BLE001
+            log.warning("availability: price query failed (%s) — keeping the static order",
+                        type(e).__name__)
+            return original
+        if not types:
+            log.warning("availability: no price data — keeping the static order")
+            return original
+
+        price: dict = {}
+        for t in types:
+            lp = t.get("lowestPrice") or {}
+            best = lp.get("uninterruptablePrice") or lp.get("minimumBidPrice")
+            if best is not None:
+                price[str(t.get("id") or "")] = float(best)
+
+        in_stock, out = [], []
+        for c in original:
+            gpu = str(c[0])
+            if gpu not in price:
+                out.append(gpu)
+                continue
+            if model:
+                err = model_fit_error(model, gpu, 1, disk_gb)
+                if err:
+                    log.info("availability: skipping %s — %s", gpu, err)
+                    continue
+            in_stock.append(c)
+
+        if not in_stock:
+            log.warning("availability: none of %d candidate(s) report stock (%s) — trying the "
+                        "static order anyway", len(original), ", ".join(sorted(set(out))) or "-")
+            return original
+
+        # Cheapest first. SECURE before COMMUNITY at equal price: Community publishes no uptime
+        # SLA, which is the existing preference in `gpu_fallbacks` and not ours to reverse here.
+        in_stock.sort(key=lambda c: (price[str(c[0])], 0 if str(c[1]).upper() == "SECURE" else 1))
+        if out:
+            log.info("availability: %d candidate(s) have no stock (%s)", len(out),
+                     ", ".join(sorted(set(out))))
+        log.info("availability: trying %s first at $%.2f/hr",
+                 in_stock[0][0], price[str(in_stock[0][0])])
+        return in_stock
+
+    async def diag_create(self, spec: PodSpec, gpu_type_id: str = "",
+                          cloud_type: str = "") -> dict:
+        """Create ONE pod and DO NOT verify or reap it — the owner reads its System Logs in the
+        RunPod console, which is the ONLY place boot failures are visible (the API/SDK exposes no
+        pod logs; open feature request). The pod is named outside the pool pattern so no reconcile
+        or teardown can ever touch it: it lives until the owner (or an explicit diag terminate)
+        ends it.
+
+        IT WALKS THE SPEC'S OWN FALLBACKS, like the real create path does. It used to hardcode
+        `NVIDIA A40` + `SECURE` and ignore `spec.gpu_fallbacks` entirely, so on 2026-09-27 a
+        diagnostic wake returned `{"pod_id": null}` against RunPod's "no longer any instances
+        available with the requested specifications" — while the spec it was handed listed FOUR
+        GPU types across two cloud types, seven of which were never tried. A diagnostic that fails
+        where production would have succeeded is worse than no diagnostic: it reads as "the node
+        cannot start" and sends you hunting the node.
+
+        `model_fit_error` is applied for the same reason the real path applies it: a model that
+        cannot fit the card boots, bills, and "loads" forever, which looks exactly like a provider
+        fault. Refusing before money is spent is the point.
+        """
+        # An explicit override still wins — that is how a caller pins one combination on purpose.
+        if gpu_type_id:
+            fallbacks = ((gpu_type_id, cloud_type or "SECURE", ""),)
+        else:
+            fallbacks = tuple(spec.gpu_fallbacks) or (("NVIDIA A40", "SECURE", ""),)
+
+        # INSIDE A CREATION GUARD, AND THIS ONE IS PAID FOR. This path used to create pods with
+        # nothing holding them, and the warning it logged said so. On 2026-09-27 the caller's HTTP
+        # request hit Cloud Run's 300s cap mid-walk, the task was cancelled, and a pod appeared
+        # AFTER the caller had already reported "no pod created" and run its own account check —
+        # so it billed at $0.79/hr, unseen, until a manual account read found it.
+        #
+        # The guard reaps in a `finally`, so an exception, a timeout or a CANCELLED TASK cannot
+        # skip it, and when a create was ambiguous it re-lists until pods stop appearing — which is
+        # exactly the late-arriving pod that got away. `owns` is the diag pod's own name, so this
+        # can never touch a pool pod.
+        #
+        # A DIAG POD MUST SURVIVE its own guard: it exists so the owner can read boot failures in
+        # the provider console, which is the only place they are visible. `keep()` is what spares
+        # it, and it is called ONLY for the pod actually created.
+        model = str(spec.env.get("STEVAI_OLLAMA_MODEL", "") or "")
+        # Same live-stock ordering as the real wake path. A diagnostic that searches differently
+        # from production is a diagnostic that lies about production.
+        if not gpu_type_id:
+            fallbacks = await self.rank_by_availability(fallbacks, model=model,
+                                                        disk_gb=spec.container_disk_gb)
+        refused: list = []
+        async with self.creation_guard(_pool_scope(spec.name)) as tracker:
+            for entry in fallbacks:
+                gt, ct = entry[0], entry[1]
+                dc = entry[2] if len(entry) > 2 else ""
+                if model:
+                    err = model_fit_error(model, gt, spec.gpu_count, spec.container_disk_gb)
+                    if err:
+                        log.error("diag REFUSING gpu=%s cloud=%s: %s", gt, ct, err)
+                        refused.append({"gpu": gt, "cloud": ct, "reason": err})
+                        continue
+                pod_id = await self.create_pod(spec, gt, ct, data_center_id=dc)
+                if pod_id:
+                    tracker.keep(pod_id)      # the ONLY thing that spares it from the reap
+                    info = await self.diag_info(pod_id)
+                    return {"pod_id": pod_id, "gpu": gt, "cloud": ct,
+                            **({"refused": refused} if refused else {}), **info}
+                # SAY WHICH. "no capacity" is a claim about the MARKET; a rejected request is a
+                # claim about US, and they send a reader to opposite places. Measured 2026-09-29:
+                # nineteen creates were reported as capacity refusals while RunPod was actually
+                # answering `ValueError: No GPU found with the specified ID` — the caller had
+                # passed a DISPLAY name (`A40`) where the API wants a type id (`NVIDIA A40`). Two
+                # hours went into the account balance, datacenter pinning and the stock table
+                # because this line named the wrong subsystem with confidence.
+                refused.append({"gpu": gt, "cloud": ct,
+                                "reason": _LAST_CREATE_ERROR.get(gt) or "no capacity or create refused"})
+            # Every combination refused. Say WHICH, so the next attempt is informed rather than a
+            # repeat — a silent None here once cost three armed windows spent guessing. Nothing was
+            # kept, so the guard's reap on the way out cleans up any ambiguous create.
+            log.error("diag create exhausted %d combination(s) for %s", len(fallbacks), spec.name)
+            return {"pod_id": None, "tried": len(fallbacks), "refused": refused}
+
+    async def diag_info(self, pod_id: str) -> dict:
+        """Everything observable about one pod, including the datacenter (which the SDK's own pod
+        query does not select — this is a door-internal GraphQL query, allowed here and only
+        here)."""
+        pod = await self.get_pod(pod_id) or {}
+        out = {
+            "desiredStatus": pod.get("desiredStatus"),
+            "costPerHr": pod.get("costPerHr"),
+            "runtime": pod.get("runtime"),
+            "machine": pod.get("machine"),
+            "lastStatusChange": pod.get("lastStatusChange"),
+        }
+        try:
+            q = ('query($id:String!){pod(input:{podId:$id}){machineId machine{dataCenterId '
+                 'gpuDisplayName}}}')
+            async with httpx.AsyncClient(timeout=30) as c:
+                r = await c.post(self._GQL, json={"query": q, "variables": {"id": pod_id}},
+                                 headers={"Authorization": f"Bearer {self._key()}",
+                                          "content-type": "application/json"})
+                d = ((r.json().get("data") or {}).get("pod")) or {}
+                out["machineId"] = d.get("machineId")
+                out["dataCenter"] = (d.get("machine") or {}).get("dataCenterId")
+                out["gpu"] = (d.get("machine") or {}).get("gpuDisplayName")
+        except Exception as e:
+            out["dataCenter"] = f"<query failed: {type(e).__name__}>"
+        return out
+
+    # -- prices (the ONE sanctioned GraphQL call — the SDK has no price query) -----------------
+
+    async def gpu_prices(self) -> List[dict]:
+        """Live per-GPU pricing, for `gpuprices.py`. Returns [] on any failure."""
+        if not self.configured():
+            return []
+        query = ("query{gpuTypes{id displayName memoryInGb securePrice communityPrice "
+                 "lowestPrice(input:{gpuCount:1}){minimumBidPrice uninterruptablePrice}}}")
+        try:
+            async with httpx.AsyncClient(timeout=30) as c:
+                r = await c.post(self._GQL, json={"query": query},
+                                 headers={"Authorization": f"Bearer {self._key()}",
+                                          "content-type": "application/json"})
+                if r.status_code >= 300:
+                    log.warning("runpod price fetch HTTP %s", r.status_code)
+                    return []
+                return ((r.json().get("data") or {}).get("gpuTypes")) or []
+        except Exception as e:
+            log.warning("runpod price fetch: %s", type(e).__name__)
+            return []
+
+    # -- the generic provider contract (find/create/destroy for start/stop above) --------------
+
+    async def find(self, label: str) -> List[Instance]:
+        return await self.find_all(label)
+
+    async def find_all(self, label: str) -> List[Instance]:
+        """TEARDOWN breadth. Everything RunPod has not TERMINATED still bills, including a pod
+        whose `desiredStatus` is RUNNING with no runtime — the most expensive shape there is."""
+        return [Instance(id=p.get("id"), label=p.get("name"))
+                for p in await self.list_pods()
+                if str(p.get("name", "")) == label
+                and str(p.get("desiredStatus", "")).upper() != "TERMINATED"]
+
+    async def find_live(self, label: str) -> List[Instance]:
+        """CAPACITY. `list_live` keyed by name: RUNNING **and** carrying a runtime object.
+
+        RunPod is the provider that can answer both questions honestly, because `desiredStatus`
+        and `runtime` are two separate facts — intent and reality.
+        """
+        return [Instance(id=p.get("id"), label=p.get("name"))
+                for p in await self.list_live() if str(p.get("name", "")) == label]
+
+    async def create(self, label: str, spec: dict) -> bool:
+        pod_spec = PodSpec.from_operator_spec(spec, name=label)
+        return bool(await self.create_ready(pod_spec))
+
+    async def destroy(self, instance_id: str) -> bool:
+        return await self.terminate(instance_id)
+
+
+# ---- Vast.ai -------------------------------------------------------------------------------
+
+class VastProvider:
+    """Vast.ai. NOTE it spells the label `label`, not `name` — the exact kind of difference
+    that made a hand-written start/stop pair per provider unsafe."""
+
+    name = "vast"
+    _BASE = "https://console.vast.ai/api/v0"
+
+    def _key(self) -> str:
+        return _provider_credential("vast", "VAST_API_KEY")
+
+    def configured(self) -> bool:
+        return bool(self._key())
+
+    def _headers(self) -> dict:
+        return {"Authorization": f"Bearer {self._key()}", "content-type": "application/json"}
+
+    #: `actual_status` values that mean the CONTAINER IS NOT SERVING. The contract, and the
+    #: bill, outlive the container: an `exited` instance is still rented until it is destroyed.
+    #: That is the whole 2026-09-24 lesson — "not serving" and "not billing" are not the same
+    #: fact, and one list cannot answer both.
+    _NOT_SERVING = frozenset({"exited"})
+
+    async def _labelled(self, label: str) -> List[dict]:
+        """Every instance on the account carrying this label, in WHATEVER state.
+
+        Raw and unfiltered on purpose. Which states count is the CALLER's question; a
+        pre-filtered list is exactly what hid a paid-for corpse from both readers at once.
+        Instances Vast has actually destroyed stop appearing here at all, so "listed" already
+        means "still contracted".
+        """
+        async with httpx.AsyncClient(timeout=30) as c:
+            r = await c.get(f"{self._BASE}/instances/", headers=self._headers(),
+                            params={"owner": "me"})
+            if r.status_code >= 300:
+                return []
+            return [i for i in ((r.json() or {}).get("instances") or [])
+                    if i.get("label") == label]
+
+    async def find(self, label: str) -> List[Instance]:
+        return await self.find_live(label)
+
+    async def find_live(self, label: str) -> List[Instance]:
+        """CAPACITY. Excludes `exited` — an exited instance serves nothing, and counting it
+        would let it hold the pool's only slot and block its own replacement."""
+        return [Instance(id=i.get("id"), label=i.get("label"))
+                for i in await self._labelled(label)
+                if str(i.get("actual_status", "")).lower() not in self._NOT_SERVING]
+
+    async def find_all(self, label: str) -> List[Instance]:
+        """TEARDOWN breadth. EVERY listed instance under this label, exited ones included.
+
+        This is the method whose absence cost money: `create` took the contract, the container
+        exited, and the only enumeration Vast had filtered the result out of the census and the
+        teardown together. Nothing here is a guess — an instance Vast still lists is an instance
+        Vast is still charging for.
+        """
+        return [Instance(id=i.get("id"), label=i.get("label"))
+                for i in await self._labelled(label)]
+
+    async def _cheapest_offer(self, spec: dict) -> Optional[int]:
+        """Vast is a MARKETPLACE: you rent a specific offer, so one must be chosen first."""
+        query = {
+            "limit": 20, "type": "ondemand",
+            "rentable": {"eq": True}, "verified": {"eq": True},
+            "num_gpus": {"gte": int(spec.get("gpuCount", 1) or 1)},
+            "reliability": {"gte": 0.95},
+        }
+        if spec.get("minVramGb"):
+            query["gpu_ram"] = {"gte": int(spec["minVramGb"]) * 1024}
+        async with httpx.AsyncClient(timeout=30) as c:
+            # TRAILING SLASH, as the API reference writes it (`POST .../api/v0/bundles/`, verified
+            # 2026-10-12). Vast's other paths are spelled with one here too (`/asks/{id}/`,
+            # `/instances/{id}/`); this one was not, and a missing slash on that API redirects or
+            # 404s — which `_cheapest_offer` would report as "no offers" and the race would read as
+            # "no capacity", not as a broken URL.
+            r = await c.post(f"{self._BASE}/bundles/", headers=self._headers(), json=query)
+            if r.status_code >= 300:
+                return None
+            offers = (r.json() or {}).get("offers") or []
+            if not offers:
+                return None
+            offers.sort(key=lambda o: float(o.get("dph_total") or 1e9))  # cheapest that fits
+            return offers[0].get("id")
+
+    async def create(self, label: str, spec: dict) -> bool:
+        offer = await self._cheapest_offer(spec)
+        if offer is None:
+            return False
+        body = {
+            "image": spec.get("imageName") or spec.get("image") or "",
+            "label": label,                       # the caller's label, never the spec's
+            "disk": float(spec.get("containerDiskInGb") or 40),
+            "env": spec.get("env") or {},
+            "onstart": spec.get("dockerArgs") or "",
+            "runtype": "args",
+        }
+        async with httpx.AsyncClient(timeout=60) as c:
+            r = await c.put(f"{self._BASE}/asks/{offer}/", headers=self._headers(), json=body)
+            if r.status_code >= 300:
+                return False
+            return bool((r.json() or {}).get("new_contract") or (r.json() or {}).get("success"))
+
+    async def destroy(self, instance_id: str) -> bool:
+        async with httpx.AsyncClient(timeout=30) as c:
+            r = await c.delete(f"{self._BASE}/instances/{instance_id}/", headers=self._headers())
+            return r.status_code < 300 or r.status_code == 404
+
+
+# ---- Verda, ex-DataCrunch (the Phase-1 EU-sovereign provider) ------------------------------
+#
+# Finland-HQ, EU data residency, self-serve. Owner decision 2026-10-16 promotes this and Nebius
+# to REPLACE RunPod, so the EU pool is exactly as real as this class is.
+#
+# THE PROVIDER ID STAYS `datacrunch`. The company renamed itself to Verda in Nov 2025, but the id
+# is a PRIMARY KEY: it is the seed row's `id`, the key in `PROVIDERS`, the key in `_FETCHERS`, the
+# `providerId` on every credential row already in the database, and the prefix
+# `regionmap.provider_of_node` attributes a running node by. Renaming the id would orphan the
+# stored credential and silently un-attribute every live EU node — a rename of a key is a
+# migration, not a tidy-up. The class docstring, the log lines and the operator-facing text say
+# Verda; the id says `datacrunch`, deliberately.
+#
+# WHAT IS DIFFERENT HERE, AND WHY IT IS WRITTEN OUT
+#   * AUTH IS OAuth2 CLIENT-CREDENTIALS, not a bearer key. Every other provider in this file
+#     holds a static key; this one exchanges an id+secret for a short-lived access token. So the
+#     token is CACHED — minting one per find/create/destroy would triple every call's latency and
+#     hammer the auth endpoint during a wake storm.
+#   * THE LABEL IS THE `hostname`. Vast spells it `label`, RunPod spells it `name`, this spells it
+#     `hostname` — the precise class of difference that made a hand-rolled start/stop pair per
+#     provider unsafe, which is why they all sit behind one interface.
+#   * DELETE IS A `PUT` with `{"action": "delete"}`, not a DELETE verb.
+#
+# RE-VERIFIED 2026-10-16 against the vendor's OWN SOURCE — the official `verda-cloud/sdk-python`
+# package and the docs changelog — not against memory. Four things had moved since the 2026-09-07
+# transcription, and two of them cost money:
+#
+#   1. THE API HOST IS `api.verda.com` NOW. The SDK's `VerdaClient` default moved there. The old
+#      `api.datacrunch.io` host still answers, so this was not yet an outage — it is a host that
+#      is one vendor decision away from being one, and the default below follows the vendor.
+#
+#   2. `location_code` IS REQUIRED SINCE 2026-03-23, and omitting it is a 400 rather than the old
+#      silent default to FIN-01. The previous `create` sent `"location_code": ""` whenever the
+#      spec did not carry one — which is WORSE than omitting it, and meant every create without
+#      an explicit location had been failing with a 400 since March. `create` now REFUSES without
+#      a location instead of sending an empty string, for the same reason it already refuses
+#      without an instance type: an under-specified create that 400s is a launch that silently
+#      never happens, and `start()` reads the False as "no capacity".
+#
+#   3. A DELETE THAT NAMES NO VOLUMES LEAVES THE OS VOLUME BILLING. The vendor's own words: "By
+#      default, no storage is selected for deletion." So the previous `destroy` reported a
+#      successful teardown and left a paid NVMe volume behind every single time. `destroy` now
+#      reads the instance's `os_volume_id` first and passes it with `delete_permanently`, which
+#      is the same leak — and the same fix — as `DeleteWithInstance=false` on Alibaba. TERMINATE
+#      MEANS NOTHING IS LEFT SPENDING, not "the compute stopped".
+#
+#   4. THE STATUS VOCABULARY IS NOW PUBLISHED, so this class can finally answer the two questions
+#      separately — see `DISTINGUISHES_SERVING` below. `offline` BILLS AND DOES NOT SERVE, which
+#      is precisely the state the old presence-only answer could not express.
+#
+# EU-ONLY IS NARROWER THAN "VERDA" (owner constraint, this lane). Verda's locations are FIN-01/02/03
+# and ICE-01, and ICE-01 is in ICELAND — EEA, not EU. An EU-residency promise served out of
+# Reykjavik is a promise this product did not make, so `EU_LOCATIONS` holds the Finnish codes only
+# and `create` refuses a location outside it. That refusal is in the adapter and not only in the
+# registry row because the row says which REGION the provider serves and the location code is a
+# finer thing the row cannot see.
+
+#: Verda datacenter codes this product treats as EU. FIN-* only: `ICE-01` is Iceland, which is EEA
+#: but NOT an EU member state, and `regionmap.residency_providers` promises EU residency off this
+#: provider's `hq_country: FI`. Read from the vendor's `Locations` constants 2026-10-16.
+#:
+#: OPERATOR-OVERRIDABLE, because a new Finnish or EU datacenter must not need a release — but the
+#: DEFAULT is the conservative set, so a code the vendor adds later is refused until someone says
+#: it is in the EU rather than admitted because it was new.
+#: The DEFAULT set, as a string. The live answer comes from `verda_eu_locations()`.
+_VERDA_EU_LOCATIONS_DEFAULT = "FIN-01,FIN-02,FIN-03"
+
+
+def verda_eu_locations() -> frozenset:
+    """The EU location codes, READ PER CALL.
+
+    A FUNCTION RATHER THAN A MODULE CONSTANT, and the reason is worth recording because the
+    alternative cost half an hour. A constant is frozen at import, so the only way to test the
+    operator override is `importlib.reload(gpuproviders)` — and a reload REBINDS this module's
+    `PROVIDERS` dict while every module that did `from .gpuproviders import PROVIDERS` keeps the
+    old one. `podreaper` does exactly that, so two tests of mine reloading this module desynchronised
+    the reaper's registry from the real one and `test_pod_reaper` started asking a REAL RunPod
+    client for the account — an AuthenticationError 90 test-files later, in a different file,
+    reported as somebody else's flake.
+    
+    It is also the better shape on its own terms: `region_providers()` and `warmpool_providers()`
+    are call-time readers for the stated reason that "an operator can change the preference order
+    with a restart rather than a rebuild", and a datacenter allow-list is the same kind of thing.
+    """
+    raw = envvar("VERDA_EU_LOCATIONS", _VERDA_EU_LOCATIONS_DEFAULT)
+    return frozenset(c.strip().upper() for c in raw.split(",") if c.strip())
+
+
+def verda_api_base() -> str:
+    """The Verda API host, read per call, new vendor name first.
+
+    Same reasoning as `verda_eu_locations()`: testable without a module reload. `_BASE` on the
+    class is initialised from this and remains the attribute `gpuprices` and the auth probe read,
+    so nothing else changes.
+    """
+    return (os.environ.get("VERDA_API_BASE")
+            or os.environ.get("DATACRUNCH_API_BASE")
+            or "https://api.verda.com/v1").rstrip("/")
+
+#: The scope the token endpoint ISSUES for a Public-API client-credentials token (docs changelog
+#: 2026-03-20). It is NOT sent on the request — the vendor's own SDK sends no `scope` parameter,
+#: and adding one would be inventing a protocol. It is checked on the RESPONSE: a token minted with
+#: some other scope will 403 with "Insufficient scope" on the first real call, and finding that out
+#: at the auth step with a named reason beats finding it out at create time as an opaque refusal.
+VERDA_EXPECTED_SCOPE = "cloud-api-v1"
+
+
+class DataCrunchProvider:
+    """Verda (ex-DataCrunch). OAuth2 client-credentials; instances keyed by `hostname`.
+
+    `name` is `datacrunch` on purpose — see the id note above this class.
+    """
+
+    name = "datacrunch"
+    #: Default moved to `api.verda.com` 2026-10-16, following the vendor's own SDK default.
+    #: `DATACRUNCH_API_BASE` still overrides it, and `VERDA_API_BASE` is accepted too so an
+    #: operator reaching for the new name is not silently ignored.
+    _BASE = verda_api_base()
+
+    #: IT DISTINGUISHES NOW, AND THAT IS A READING RATHER THAN A DECISION TO BE BRAVER.
+    #:
+    #: This was the ONE provider declaring False, and its own comment said what it would take to
+    #: change: "Classifying it would need a verified status list from the vendor, which is a ruling
+    #: and an API check, not a guess made here." That list is now published — `verda/constants.py`
+    #: in the vendor's official SDK enumerates every `InstanceStatus` — and the vendor's docs say
+    #: which of them bill: "Shutdown instances continue to charge your account."
+    #:
+    #: So the two questions have different answers here and the class can give them:
+    #:   SERVING  -> `running` only                    (`_SERVING`)
+    #:   BILLING  -> everything that is not gone       (`find`, minus `_DEAD`)
+    #: and `offline` — which bills and serves nothing — is the state that used to be reported as a
+    #: clean "present, therefore live" to all three readers at once.
+    #:
+    #: `test_gpuproviders.py` enforces the declaration against the methods, so this True is only
+    #: legal while both enumerations below exist.
+    DISTINGUISHES_SERVING = True
+
+    #: Statuses that mean the instance is GONE. Everything else — including `offline` — counts as
+    #: live for TEARDOWN. That direction is deliberate on both paths: an instance we cannot
+    #: classify must not cause `start()` to create a second one, and must not be skipped by
+    #: `stop()`. Guessing "probably dead" is how something keeps billing after a teardown reported
+    #: success.
+    #:
+    #: `hibernating`/`starting_hibernation`/`restoring` are NOT here even though the vendor has
+    #: REMOVED hibernation as a feature ("it was the same as Delete while keeping all storage").
+    #: A state the vendor retired is exactly the state an old instance could still be sitting in,
+    #: and treating a retired state as "gone" would make such an instance invisible to teardown
+    #: while its storage bills. Retired by the vendor is not the same as absent from the account.
+    _DEAD = frozenset({"deleted", "terminated", "destroyed", "discontinued"})
+
+    #: The ONLY status that means this instance is actually SERVING. A deliberately narrow set:
+    #: `provisioning` and `ordered` are not serving yet, `error` is not serving at all, and
+    #: `offline` is a shut-down instance that still charges the account. Anything the vendor adds
+    #: later is NOT serving until someone adds it here, which is the safe direction for a capacity
+    #: answer — an unknown status holds no pool slot and so cannot block its own replacement, while
+    #: `find`/`find_all` still see it and still tear it down.
+    _SERVING = frozenset({"running"})
+
+    def __init__(self) -> None:
+        self._token = ""
+        self._token_expires = 0.0
+
+    def _creds(self) -> tuple:
+        """The client id and secret, under EITHER naming.
+
+        TWO NAMES, NEW ONE FIRST. The credential was stored under `DATACRUNCH_*` before the vendor
+        renamed itself; an operator seeding it today reaches for `VERDA_*`. Which of the two is in
+        the database is not knowable from here — so BOTH are read, the new name wins, and the old
+        one keeps working. The alternative is a rename migration that strands a working credential
+        and reports the provider unconfigured, which is the 2026-09-07 RunPod key failure shape:
+        present in the registry, invisible to the code, "configured: true" in the doctor.
+
+        A PAIR IS NOT MIXED ACROSS NAMINGS. An id read from `VERDA_CLIENT_ID` is never paired with
+        a secret read from `DATACRUNCH_CLIENT_SECRET`: half of a rotated pair and half of a retired
+        one authenticate as neither, and the resulting 401 looks like a revoked key rather than a
+        seeding mistake. So each naming is resolved whole, and the first COMPLETE pair wins.
+        """
+        for cid_name, sec_name in (("VERDA_CLIENT_ID", "VERDA_CLIENT_SECRET"),
+                                   ("DATACRUNCH_CLIENT_ID", "DATACRUNCH_CLIENT_SECRET")):
+            cid = _provider_credential("datacrunch", cid_name)
+            secret = _provider_credential("datacrunch", sec_name)
+            if cid and secret:
+                return (cid, secret)
+        return ("", "")
+
+    def credential_names(self) -> "tuple[str, str]":
+        """WHICH naming resolved, for the doctor and the probe. Names only, never values — the name
+        of an env var is not secret (file 28 §O) and its contents never leave `_creds`."""
+        for cid_name, sec_name in (("VERDA_CLIENT_ID", "VERDA_CLIENT_SECRET"),
+                                   ("DATACRUNCH_CLIENT_ID", "DATACRUNCH_CLIENT_SECRET")):
+            if _provider_credential("datacrunch", cid_name) and _provider_credential("datacrunch", sec_name):
+                return (cid_name, sec_name)
+        return ("", "")
+
+    def configured(self) -> bool:
+        cid, secret = self._creds()
+        return bool(cid and secret)
+
+    async def _access_token(self) -> str:
+        """A cached OAuth2 access token, refreshed a minute before it actually expires.
+
+        The margin matters: a token that passes the check here and expires in flight produces a
+        401 on the CREATE call, and a create that fails ambiguously is the one failure mode that
+        can leave an instance running that nobody recorded.
+
+        NO `scope` IS SENT. The vendor's own SDK sends `grant_type`, `client_id` and
+        `client_secret` and nothing else; `cloud-api-v1` is what the server PUTS IN THE RESPONSE
+        (docs changelog 2026-03-20). The response scope is checked and a mismatch is LOGGED rather
+        than refused — the vendor is free to rename or widen its own scope string, and refusing a
+        token the server just issued would ground the EU pool over a label. The log is what turns
+        the later "Insufficient scope" 403 from a mystery into a lookup.
+        """
+        now = time.time()
+        if self._token and now < self._token_expires:
+            return self._token
+        cid, secret = self._creds()
+        if not (cid and secret):
+            return ""
+        try:
+            async with httpx.AsyncClient(timeout=30) as c:
+                r = await c.post(f"{self._BASE}/oauth2/token",
+                                 json={"grant_type": "client_credentials",
+                                       "client_id": cid, "client_secret": secret})
+        except Exception as e:
+            # A TRANSPORT FAILURE HERE USED TO RAISE OUT OF EVERY METHOD ON THIS CLASS, which
+            # contradicts the contract `_headers()` states one function below in as many words:
+            # "Callers check for None and fail the way the contract says — 'nothing running' /
+            # 'did not create' — never by raising."
+            #
+            # It was unwrapped from before this lane existed, and the reachable consequences are
+            # real: `create()` has no try/except of its own, so a DNS blip or a connection reset
+            # on the token endpoint propagated out of a provider method as an exception rather
+            # than as "no capacity". `find()` has the same shape. Nebius's exchange was already
+            # wrapped; this is Verda catching up.
+            #
+            # The TYPE only — never the exception's text. A client error can quote the request,
+            # and this request carries the client secret.
+            log.warning("verda: token endpoint unreachable (%s) — treating as no token",
+                        type(e).__name__)
+            return ""
+        if r.status_code >= 300:
+            log.warning("verda: token endpoint refused the client credentials (HTTP %s)",
+                        r.status_code)
+            return ""
+        data = r.json() or {}
+        token = str(data.get("access_token") or "")
+        if not token:
+            return ""
+        scope = str(data.get("scope") or "")
+        if scope and VERDA_EXPECTED_SCOPE not in scope.split():
+            log.warning("verda: token issued with scope %r, expected %r — Public API calls may "
+                        "return 403 'Insufficient scope'", scope, VERDA_EXPECTED_SCOPE)
+        self._token = token
+        self._token_expires = now + max(0.0, float(data.get("expires_in") or 3600)) - 60
+        return token
+
+    async def _headers(self) -> "Optional[dict]":
+        """Auth headers, or None when no token could be obtained.
+
+        None rather than an empty bearer: `Authorization: Bearer ` is an ILLEGAL header value and
+        httpx raises `LocalProtocolError` on it, so a simple credential problem would surface as
+        a protocol crash from inside the transport. Callers check for None and fail the way the
+        contract says — "nothing running" / "did not create" — never by raising.
+        """
+        token = await self._access_token()
+        if not token:
+            return None
+        return {"Authorization": f"Bearer {token}", "content-type": "application/json"}
+
+    async def _instances(self) -> "Optional[List[dict]]":
+        """Every instance on the account, or None when the account could not be ASKED.
+
+        None IS NOT AN EMPTY LIST, and that distinction is this codebase's most expensive recurring
+        bug: an unreadable list read as "nothing is there". `find` converts None to `[]` because
+        its contract says so, but `destroy` needs the difference — it must not conclude an instance
+        has no OS volume because the list call failed.
+        """
+        headers = await self._headers()
+        if headers is None:
+            return None
+        try:
+            async with httpx.AsyncClient(timeout=30) as c:
+                r = await c.get(f"{self._BASE}/instances", headers=headers)
+        except Exception as e:
+            log.warning("verda: could not list instances (%s)", type(e).__name__)
+            return None
+        if r.status_code >= 300:
+            log.warning("verda: instance list HTTP %s", r.status_code)
+            return None
+        body = r.json() or []
+        rows = body if isinstance(body, list) else (body.get("instances") or body.get("data") or [])
+        return [i for i in rows if isinstance(i, dict)]
+
+    def _matching(self, rows: "List[dict]", label: str, statuses: "Optional[frozenset]" = None,
+                  *, exclude_dead: bool = True) -> List[Instance]:
+        """The rows carrying `label`, narrowed to `statuses` when one is given."""
+        out: List[Instance] = []
+        for i in rows:
+            if i.get("hostname") != label:
+                continue
+            status = str(i.get("status", "")).lower()
+            if exclude_dead and status in self._DEAD:
+                continue
+            if statuses is not None and status not in statuses:
+                continue
+            out.append(Instance(id=i.get("id"), label=i.get("hostname"), status=status))
+        return out
+
+    async def find(self, label: str) -> List[Instance]:
+        """THE BASE PRIMITIVE: anything carrying this label that is not GONE.
+
+        What `start()`'s idempotency check wants — "is anything of mine already here" — answered as
+        conservatively as the vendor's vocabulary allows.
+        """
+        rows = await self._instances()
+        return self._matching(rows or [], label)
+
+    async def find_live(self, label: str) -> List[Instance]:
+        """CAPACITY: only instances that are actually SERVING (`running`).
+
+        This is the half the presence-only answer got wrong in the expensive direction. An
+        `offline` instance was reported live, so it held its pool slot, no replacement was ever
+        created, and the account was charged for a machine serving nothing.
+        """
+        rows = await self._instances()
+        return self._matching(rows or [], label, self._SERVING)
+
+    async def find_all(self, label: str) -> List[Instance]:
+        """TEARDOWN: everything under this label that could still BILL — `offline` included.
+
+        Identical to `find` today, and NOT an alias for it: they answer different questions and
+        the vendor could add a status that is billing-but-not-live-for-idempotency. Writing it out
+        keeps `DISTINGUISHES_SERVING = True` honest and keeps the two call sites independent.
+        """
+        rows = await self._instances()
+        return self._matching(rows or [], label)
+
+    async def status(self, label: str) -> dict:
+        """The vendor's own status for each instance under this label, unflattened.
+
+        For operators and for the live-proof log: `find*` return the classification and this
+        returns what was classified. A teardown that has to be defended later needs the raw word
+        the vendor used, not our bucket for it.
+
+        `{"ok": False}` when the account could not be asked — never an empty `instances` list,
+        which would read as "the label is clear".
+        """
+        rows = await self._instances()
+        if rows is None:
+            return {"ok": False, "provider": self.name, "label": label,
+                    "detail": "could not list instances — this is NOT 'the label is clear'"}
+        mine = [i for i in rows if i.get("hostname") == label]
+        return {
+            "ok": True,
+            "provider": self.name,
+            "label": label,
+            "instances": [{"id": i.get("id"), "status": str(i.get("status", "")).lower(),
+                           "location": i.get("location") or i.get("location_code") or "",
+                           "os_volume_id": i.get("os_volume_id") or "",
+                           "price_per_hour": i.get("price_per_hour"),
+                           "serving": str(i.get("status", "")).lower() in self._SERVING,
+                           "billing": str(i.get("status", "")).lower() not in self._DEAD}
+                          for i in mine],
+        }
+
+    async def list_account(self) -> "Optional[List[dict]]":
+        """EVERYTHING on the account, label-agnostic, normalised. `None` when it could not be asked.
+
+        THE QUESTION `find(label)` CANNOT ANSWER, and the reason `podreaper` exists at all: the
+        guard in this module only covers instances created inside a guarded window, and the
+        2026-09-17 orphan was created by a process that had already exited believing it had failed.
+        Something has to be able to ask "what is actually on this account" with no memory of what
+        was supposed to be there — and that question has no label to filter on.
+
+        `None` rather than `[]` on failure, loudly, because `podreaper`'s whole discipline is that
+        a list it could not read is NOT "the account is clean".
+        """
+        rows = await self._instances()
+        if rows is None:
+            return None
+        return [{"id": str(i.get("id") or ""),
+                 "label": str(i.get("hostname") or ""),
+                 "status": str(i.get("status", "")).lower(),
+                 "created_at": i.get("created_at") or "",
+                 "price_per_hour": i.get("price_per_hour"),
+                 "location": i.get("location") or i.get("location_code") or "",
+                 "billing": str(i.get("status", "")).lower() not in self._DEAD}
+                for i in rows]
+
+    async def list_volumes(self) -> "Optional[List[dict]]":
+        """Every non-deleted volume on the account, normalised. `None` when it could not be asked.
+
+        WHY THIS EXISTS, AND IT IS A BILL THAT IS ALREADY RUNNING. Until 2026-10-16 `destroy` did
+        not name the volume ids, and the vendor deletes no storage unless the delete names it ("by
+        default, no storage is selected for deletion"). So every Verda instance this platform has
+        ever torn down very likely left a detached, paid NVMe volume behind. Closing the leak does
+        not reclaim the residue, and nothing else in this repo can see it: `podreaper --providers`
+        enumerates INSTANCES, and `frutebox/volumes.py` is a cost model, not an inventory.
+
+        IT READS AND NOTHING ELSE. There is no delete anywhere on this path, deliberately — a
+        detached volume may be somebody's deliberately-kept dataset, and this code cannot tell that
+        from an orphan. `test_verda_orphan_volumes.py` asserts the absence over the syntax tree.
+
+        NO `?status=detached`, THOUGH THE VENDOR OFFERS IT. The filter would make "0 detached" and
+        "the call did not work" the same output, which is the mistake this codebase keeps paying
+        for. Everything is fetched and classified here, so a zero always arrives with the total it
+        was drawn from — and a volume whose `status` the vendor words differently than we expect is
+        still seen, instead of being filtered out of existence upstream.
+        """
+        headers = await self._headers()
+        if headers is None:
+            return None
+        try:
+            async with httpx.AsyncClient(timeout=30) as c:
+                r = await c.get(f"{self._BASE}/volumes", headers=headers)
+        except Exception as e:
+            log.warning("verda: could not list volumes (%s)", type(e).__name__)
+            return None
+        if r.status_code >= 300:
+            log.warning("verda: volume list HTTP %s", r.status_code)
+            return None
+        body = r.json() or []
+        rows = body if isinstance(body, list) else (body.get("volumes") or body.get("data") or [])
+        out: List[dict] = []
+        for v in rows:
+            if not isinstance(v, dict):
+                continue
+            out.append({
+                "id": str(v.get("id") or ""),
+                "name": str(v.get("name") or ""),
+                "status": str(v.get("status", "")).lower(),
+                "type": str(v.get("type") or ""),
+                "size_gb": v.get("size"),
+                "is_os_volume": bool(v.get("is_os_volume")),
+                # None when detached, per the vendor's own field documentation.
+                "instance_id": v.get("instance_id") or None,
+                "location": str(v.get("location") or v.get("location_code") or "").upper(),
+                "created_at": v.get("created_at") or "",
+                "deleted_at": v.get("deleted_at") or None,
+                # THE NUMBERS THAT MAKE THIS WORTH READING. The vendor returns them per volume, so
+                # the report can say what the residue COSTS rather than how many rows it has.
+                "hourly_cost": v.get("base_hourly_cost"),
+                "monthly_price": v.get("monthly_price"),
+                "currency": str(v.get("currency") or ""),
+            })
+        return out
+
+    async def create(self, label: str, spec: dict) -> bool:
+        location = str(spec.get("locationCode") or spec.get("location_code") or "").strip().upper()
+        body = {
+            # The CALLER's label, never the spec's. A provider that lets the spec's name through
+            # is the 2026-08-21 billing bug reintroduced: the wake cannot find what it started.
+            "hostname": label,
+            "description": spec.get("description") or label,
+            "instance_type": spec.get("instanceType") or spec.get("instance_type") or "",
+            "image": spec.get("image") or spec.get("imageName") or "",
+            "location_code": location,
+        }
+        if not body["instance_type"] or not body["image"]:
+            return False           # an under-specified create would 400 anyway; fail honestly
+        if not location:
+            # REQUIRED SINCE 2026-03-23 — omitted is a 400, and the empty string this used to send
+            # is worse than omitted. Refusing here names the missing field; sending "" produced an
+            # opaque 400 that `start()` read as "no capacity in the EU".
+            log.error("verda: refusing to create %r without a location_code. It has been REQUIRED "
+                      "since 2026-03-23 (an absent one is HTTP 400, not a default to FIN-01). Set "
+                      "it in the launch spec; EU codes are %s",
+                      label, ",".join(sorted(verda_eu_locations())))
+            return False
+        if location not in verda_eu_locations():
+            # ICE-01 is Iceland: EEA, not EU. See `verda_eu_locations`.
+            log.error("verda: refusing to create %r in %s — not an EU location. Permitted: %s",
+                      label, location, ",".join(sorted(verda_eu_locations())))
+            return False
+        ssh = spec.get("sshKeyIds") or spec.get("ssh_key_ids")
+        if ssh:
+            body["ssh_key_ids"] = list(ssh)
+        script = spec.get("startupScriptId") or spec.get("startup_script_id")
+        if script:
+            body["startup_script_id"] = script
+        for optional in ("contract", "is_spot", "os_volume", "volumes", "existing_volumes",
+                         "pricing"):
+            if spec.get(optional) is not None:
+                body[optional] = spec[optional]
+        headers = await self._headers()
+        if headers is None:
+            return False
+        async with httpx.AsyncClient(timeout=90) as c:
+            r = await c.post(f"{self._BASE}/instances", headers=headers, json=body)
+        if r.status_code >= 300:
+            log.error("verda: create %r HTTP %s", label, r.status_code)
+            return False
+        return True
+
+    async def destroy(self, instance_id: str) -> bool:
+        """Terminate — AND take the OS volume with it. 404 counts as success.
+
+        THE VOLUME IS THE POINT OF THIS METHOD'S SHAPE. The vendor: "By default, no storage is
+        selected for deletion." So the obvious `{"action": "delete", "id": X}` deletes the compute,
+        reports 200, and leaves a paid NVMe volume on the account forever — a teardown that
+        reports success and keeps spending, which is the exact failure `destroy_verified` exists to
+        catch and which no amount of checking the HTTP status would have revealed.
+
+        So this reads the instance's `os_volume_id` first and names it, with `delete_permanently`.
+
+        A FAILED LOOKUP DOES NOT BECOME "NO VOLUME". If the account cannot be listed, the delete
+        still goes ahead — leaving a running GPU to bill because a list call failed would be the
+        worse trade — but it is LOGGED as a teardown whose storage was not accounted for, so the
+        residue is discoverable instead of silent.
+
+        THERE IS NO VOLUME SWEEP TO FALL BACK ON, and this docstring said there was. `volumes.py`
+        is PURE POLICY — "should a network volume exist, given cold-start frequency and cost" —
+        with no I/O and no CLI at all, so `python -m frutebox.volumes --sweep` was a command that
+        does not exist, pointed at an operator in a log line they would only ever read while
+        chasing a bill. Checked, not assumed; see the WARNING text below for what it says now.
+        """
+        headers = await self._headers()
+        if headers is None:
+            return False
+
+        volume_ids: List[str] = []
+        rows = await self._instances()
+        if rows is None:
+            log.warning("verda: could not read instance %s before deleting it — its OS volume is "
+                        "NOT accounted for and may keep billing. Nothing in this repo lists Verda "
+                        "volumes; check `GET %s/volumes` with the same credential, or the "
+                        "Storage page in the Verda console, and delete any detached volume whose "
+                        "instance is gone.", instance_id, self._BASE)
+        else:
+            for i in rows:
+                if str(i.get("id")) != str(instance_id):
+                    continue
+                if i.get("os_volume_id"):
+                    volume_ids.append(str(i["os_volume_id"]))
+                for v in (i.get("volumes") or []):
+                    vid = v.get("id") if isinstance(v, dict) else v
+                    if vid:
+                        volume_ids.append(str(vid))
+                break
+
+        body: Dict[str, object] = {"action": "delete", "id": instance_id}
+        if volume_ids:
+            # Both keys together: `delete_permanently` is documented as applying only when
+            # `volume_ids` is also present, so sending it alone would be a no-op that reads like a
+            # guarantee.
+            body["volume_ids"] = volume_ids
+            body["delete_permanently"] = True
+        async with httpx.AsyncClient(timeout=60) as c:
+            r = await c.put(f"{self._BASE}/instances", headers=headers, json=body)
+        return r.status_code < 300 or r.status_code == 404
+
+
+#: Volume statuses that mean the volume is GONE and cannot be billing. Everything else counts as
+#: present — including a status we have not seen, for the same reason `_DEAD` is a small set on the
+#: instance side: an unclassifiable volume must be REPORTED, never filtered into non-existence.
+VERDA_VOLUME_DEAD = frozenset({"deleted", "deleting"})
+
+
+def verda_detached_volumes(rows: "List[dict]") -> "List[dict]":
+    """The volumes nobody is holding: present, and attached to no instance.
+
+    DETACHED IS READ FROM `instance_id`, NOT FROM `status`, AND BOTH ARE CONSULTED. The vendor
+    documents `instance_id` as "None if detached", which is the fact we actually care about —
+    whether anything is using it — while `status` is a lifecycle word whose vocabulary we have only
+    partially verified. A volume with no instance is detached whatever its status says, and a
+    volume the vendor explicitly calls `detached` is detached even if some future response carries
+    a stale instance id. Either signal is enough; neither is required to agree with the other.
+
+    THIS IS NOT "ORPHANED". A detached volume may be a dataset somebody keeps on purpose, and
+    nothing here can tell that from residue — which is exactly why the caller only ever LISTS.
+    """
+    out = []
+    for v in rows:
+        if str(v.get("status", "")).lower() in VERDA_VOLUME_DEAD or v.get("deleted_at"):
+            continue
+        if v.get("instance_id") and str(v.get("status", "")).lower() != "detached":
+            continue
+        out.append(v)
+    return out
+
+
+# ---- POD SPEC DERIVATION: the cheapest EU single-GPU box that can run the proof ------------
+#
+# SUPERVISOR DECISION 2026-10-17: "POD_SPECs are not an owner decision — set the defaults to the
+# cheapest EU single-GPU type in each provider's LIVE catalog that fits the proof model; log the
+# choice + price."
+#
+# WHY THIS IS A DERIVATION AND NOT A DEFAULT STRING, which is the one design call in here. The
+# instruction says "in each provider's LIVE catalog", and a catalog is not readable without a
+# credential — Owners 33/34 are open, so no catalog has been read on this machine. Writing
+# `1V100.6V` into a constant today would therefore be a GUESS wearing the costume of a default:
+# the 2026-09-24 `VAST_POD_SPEC` ruling is that a provider which guesses the spec deploys the
+# wrong machine and bills for it, and a guess that happens to be in a registry file is no better
+# than one in an adapter.
+#
+# So the DEFAULT IS THE DERIVATION. `FRUTEBOX_<NAME>_POD_SPEC` still wins when an operator sets it
+# — that is what makes a deliberate choice possible — and when it is unset these functions read
+# the vendor's live catalog and choose. The consequence is the property the instruction actually
+# wants: the moment a credential resolves, the cheapest qualifying EU box is picked with no edit
+# and no redeploy, and the choice and its price are LOGGED rather than assumed.
+#
+# WHAT "FITS THE PROOF MODEL" MEANS, in numbers rather than adjectives. The live proof boots our
+# node image and serves `gemma3:4b` through ollama. That is a ~4B-parameter model at q4 — roughly
+# 3 GB of weights, plus a KV cache and ollama's overhead — so the floor below is generous on
+# purpose: every current datacenter GPU clears it, which keeps this a FILTER rather than a
+# constraint that quietly excludes the cheap end of the catalog and overspends.
+#
+# SINGLE GPU IS A HARD FILTER, NOT A PREFERENCE. A multi-GPU box can be cheaper per card and is
+# never cheaper per hour, and the proof rents by the hour. `gpu_count == 1` is also what makes the
+# €10 cap meaningful: an 8-GPU instance at the same per-card price is eight times the bill.
+
+#: VRAM floor for the live-proof model, in GB per card. Overridable because the proof model is
+#: itself a choice; the default is sized for `gemma3:4b` with room, not measured against it.
+PROOF_MIN_VRAM_GB = int(envvar("PROOF_MIN_VRAM_GB", "16"))
+
+
+def _cheapest_fitting(candidates: "List[dict]") -> "Optional[dict]":
+    """The cheapest candidate, with ties broken by name so the choice is REPRODUCIBLE.
+
+    A tie broken by dict order would make the derivation pick differently on two runs against the
+    same catalog, which turns "the choice was logged" into a claim nobody can check later.
+    """
+    if not candidates:
+        return None
+    return sorted(candidates, key=lambda c: (round(float(c["usd_per_hr"]), 6), c["name"]))[0]
+
+
+#: Image flavours the node must NOT boot. Each one is a preinstalled stack that fights the node's
+#: own provisioning: `jupyter` ships a notebook server, `kubernetes` a kubelet expecting a cluster,
+#: `docker` a daemon we neither need nor configure. `node-startup.sh` installs ollama and the agent
+#: onto a bare host, so a plain OS+CUDA image is the only one it is written for.
+_VERDA_IMAGE_REJECT = ("jupyter", "kubernetes", "k8s", "docker")
+
+
+def _verda_pick_image(candidates: "List[str]") -> str:
+    """The newest PLAIN Ubuntu+CUDA image, by parsed version rather than by string order.
+
+    THE BUG THIS REPLACES COST A BILLED CREATE. The previous line was `sorted(cuda)[-1]`, with the
+    comment "newest by name; the catalog carries no explicit version order". Measured against the
+    live catalog on 2026-10-18, that picked `jupyter.cuda.12.8` out of a list whose real newest was
+    `26.04.cuda13.4` — because `'j'` sorts after `'2'`. So "newest by name" was not newest, it was
+    last alphabetically, and it chose a notebook image for a headless node. The create then failed
+    for an unrelated reason and hid it; it would have booted the wrong machine otherwise.
+
+    Versions are compared as TUPLES OF INTEGERS (`26.04` + `cuda13.4` -> `(26, 4, 13, 4)`), so
+    `cuda13.4` beats `cuda12.9` — which string order gets wrong too, since `'2' < '3'` but
+    `'12' > '13'` lexicographically only after the first differing digit. A name we cannot parse
+    sorts LAST rather than being dropped: it stays selectable if nothing else qualifies, but never
+    outranks a version we can actually read.
+    """
+    import re
+
+    def version_key(name: str):
+        nums = tuple(int(n) for n in re.findall(r"\d+", name))
+        return (1, nums) if nums else (0, ())
+
+    plain = [c for c in candidates
+             if not any(bad in c.lower() for bad in _VERDA_IMAGE_REJECT)]
+    if not plain:
+        return ""
+    return sorted(plain, key=version_key)[-1]
+
+
+async def verda_candidates(*, min_vram_gb: "Optional[int]" = None) -> "Optional[List[dict]]":
+    """Every qualifying EU single-GPU offering, CHEAPEST FIRST. `None` when unaskable.
+
+    WHY A LIST AND NOT JUST THE WINNER. `/instance-availability` says a type is in stock, and that
+    is NOT a promise it can still be created a second later: measured 2026-10-20, a `1L40S.20V`
+    the catalog listed as available in FIN-02 answered `503 "No capacity available"` on create.
+    A derivation that returns one winner leaves its caller with nothing to do about that except
+    fail, which is how a launch reports "no EU capacity" while five other types are rentable.
+    `nodewake._create_cheapest_first` already walks fallbacks for the fleet; this gives the live
+    proof and any other caller the same ability.
+
+    ONE FILTER, SHARED. `derive_datacrunch_pod_spec` calls this and takes the head, so the two can
+    never disagree about what "qualifying" means — a second copy of the gpu-count/VRAM/stock
+    predicate is the drift this repo keeps paying for.
+    """
+    floor = PROOF_MIN_VRAM_GB if min_vram_gb is None else int(min_vram_gb)
+    prov = PROVIDERS.get("datacrunch")
+    if prov is None or not prov.configured():
+        log.error("verda: cannot read the catalog without a credential — Owner 33, not a code "
+                  "change.")
+        return None
+    headers = await prov._headers()
+    if headers is None:
+        log.error("verda: the credential was refused a token")
+        return None
+    try:
+        async with httpx.AsyncClient(timeout=30) as c:
+            types_r = await c.get(f"{prov._BASE}/instance-types", headers=headers)
+            avail_r = await c.get(f"{prov._BASE}/instance-availability", headers=headers)
+    except Exception as e:
+        log.error("verda: catalog read failed (%s)", type(e).__name__)
+        return None
+    if types_r.status_code >= 300 or avail_r.status_code >= 300:
+        log.error("verda: catalog read HTTP %s/%s", types_r.status_code, avail_r.status_code)
+        return None
+
+    eu = verda_eu_locations()
+    stock: Dict[str, List[str]] = {}
+    for loc in (avail_r.json() or []):
+        if not isinstance(loc, dict):
+            continue
+        code = str(loc.get("location_code") or "").upper()
+        if code not in eu:
+            continue
+        for t in loc.get("availabilities") or []:
+            stock.setdefault(str(t), []).append(code)
+
+    out: List[dict] = []
+    for t in (types_r.json() or []):
+        if not isinstance(t, dict):
+            continue
+        name = str(t.get("instance_type") or "").strip()
+        if not name or name not in stock:
+            continue
+        gpu = t.get("gpu") or {}
+        if int(gpu.get("number_of_gpus") or 0) != 1:
+            continue
+        vram = int((t.get("gpu_memory") or {}).get("size_in_gigabytes") or 0)
+        if vram < floor:
+            continue
+        try:
+            price = float(t.get("price_per_hour") or 0)
+        except (TypeError, ValueError):
+            continue
+        if price <= 0:
+            continue
+        # EVERY EU LOCATION WITH STOCK, not just the first: a 503 is often per-location, so the
+        # same type elsewhere is the cheapest retry available.
+        for loc_code in sorted(stock[name]):
+            out.append({"name": name, "usd_per_hr": price, "vram_gb": vram,
+                        "location": loc_code,
+                        "currency": str(t.get("currency") or "").lower(),
+                        "gpu": str(gpu.get("description") or "")})
+    out.sort(key=lambda c: (round(c["usd_per_hr"], 6), c["name"], c["location"]))
+    return out
+
+
+async def derive_datacrunch_pod_spec(*, min_vram_gb: "Optional[int]" = None) -> "Optional[dict]":
+    """Verda's cheapest in-stock EU single-GPU instance type, as a complete launch spec.
+
+    THE HEAD OF `verda_candidates()`, plus the image and SSH keys a create also needs. The filter
+    lives in exactly one place: this function used to carry its own copy of the
+    gpu-count/VRAM/stock predicate, and its docstring claimed the refactor that removed it before
+    the refactor existed — `test_no_orphan_implementations` caught the lie by noticing
+    `verda_candidates` had no caller.
+
+    `None` on any failure, with the reason LOGGED — never a partial spec. A spec missing its image
+    or its location is a create that 400s, and `start()` reads that as "no EU capacity".
+    """
+    floor = PROOF_MIN_VRAM_GB if min_vram_gb is None else int(min_vram_gb)
+    prov = PROVIDERS.get("datacrunch")
+    cands = await verda_candidates(min_vram_gb=floor)
+    if cands is None:
+        return None
+    best = cands[0] if cands else None
+    if best is None:
+        log.error("verda: no in-stock EU single-GPU type with >=%dGB VRAM in the catalog. NOT "
+                  "falling back to a guess.", floor)
+        return None
+    headers = await prov._headers()
+    if headers is None:
+        return None
+
+    # The image is a second catalog read, scoped to the chosen type so the answer is one the
+    # vendor says can actually boot on it.
+    try:
+        async with httpx.AsyncClient(timeout=30) as c:
+            img_r = await c.get(f"{prov._BASE}/images", headers=headers,
+                                params={"instance_type": best["name"]})
+        images = (img_r.json() or []) if img_r.status_code < 300 else []
+    except Exception as e:
+        log.error("verda: image catalog read failed (%s)", type(e).__name__)
+        return None
+    cuda = [str(i.get("image_type") or "") for i in images
+            if isinstance(i, dict) and "cuda" in str(i.get("image_type") or "").lower()]
+    if not cuda:
+        log.error("verda: no CUDA image offered for %s (%d image(s) listed) — refusing to guess "
+                  "an image name, which would boot a machine with no driver and bill for it",
+                  best["name"], len(images))
+        return None
+    image = _verda_pick_image(cuda)
+    if not image:
+        log.error("verda: %d CUDA image(s) offered for %s but none is a PLAIN OS image (every one "
+                  "is a jupyter/kubernetes/docker variant) — refusing to pick one, because the "
+                  "node needs a bare host it can install onto", len(cuda), best["name"])
+        return None
+
+    # SSH KEYS ARE NOT OPTIONAL HERE, and the vendor's first error message said otherwise.
+    # `POST /instances` without them answers 400 "SSH keys can be an array of UUID's, a single
+    # UUID string, null value or not defined" — which lists `not defined` as acceptable and is
+    # misleading: sending null and sending nothing both fail, and the SECOND message is the true
+    # one, "SSH keys must be provided if image is not an OS volume". Measured 2026-10-18.
+    #
+    # DISCOVERED, NOT CREATED. A derivation reads the account; minting a key is a write and a
+    # credential, which is the live proof's job (it makes an ephemeral one and removes it). If the
+    # account has none, this says so rather than returning a spec whose create cannot succeed.
+    ssh_ids = await _verda_ssh_key_ids(prov, headers)
+    if ssh_ids is None:
+        log.error("verda: could not read the account's SSH keys — not deriving a spec, because a "
+                  "create without them is a guaranteed 400")
+        return None
+    if not ssh_ids:
+        log.error("verda: the account has NO SSH keys, and Verda refuses an image boot without one "
+                  "(\"SSH keys must be provided if image is not an OS volume\"). Add one, or let "
+                  "the live proof mint an ephemeral key. Not returning a spec that cannot launch.")
+        return None
+
+    # `sym` and the candidate count come from the chosen row and the list it was chosen from —
+    # both now owned by `verda_candidates`, which is the point of the refactor.
+    sym = {"eur": "EUR", "usd": "USD"}.get(best["currency"], best["currency"].upper() or "?")
+    log.info("verda: derived pod spec — instance_type=%s gpu=%s vram=%dGB location=%s "
+             "image=%s PRICE=%.4f %s/hr (cheapest in-stock EU single-GPU over %dGB, chosen from "
+             "%d qualifying offering(s))",
+             best["name"], best["gpu"], best["vram_gb"], best["location"], image,
+             best["usd_per_hr"], sym, floor, len(cands))
+    return {
+        "instance_type": best["name"],
+        "image": image,
+        "location_code": best["location"],
+        "ssh_key_ids": ssh_ids,
+        "_derived": {"price_per_hr": best["usd_per_hr"], "currency": sym,
+                     "vram_gb": best["vram_gb"], "gpu": best["gpu"],
+                     "qualifying": len(cands),
+                     "source": "verda /instance-types + /instance-availability + /images"},
+    }
+
+
+async def _verda_ssh_key_ids(prov, headers: dict) -> "Optional[List[str]]":
+    """The account's SSH key ids, or `None` when the account could not be ASKED.
+
+    `/ssh-keys` is the CURRENT path; `/sshkeys` is a deprecated alias the vendor's own SDK still
+    uses (docs changelog 2026-09-21). The current one is used here, and the deprecated one is not
+    tried as a fallback: if the current path stops answering, that is news rather than something to
+    paper over.
+
+    `None` is not `[]`. An unreadable key list means "do not launch"; an empty one means "the
+    account genuinely has no key", and the two lead to different messages and different fixes.
+    """
+    try:
+        async with httpx.AsyncClient(timeout=30) as c:
+            r = await c.get(f"{prov._BASE}/ssh-keys", headers=headers)
+    except Exception as e:
+        log.warning("verda: could not list SSH keys (%s)", type(e).__name__)
+        return None
+    if r.status_code >= 300:
+        log.warning("verda: SSH key list HTTP %s", r.status_code)
+        return None
+    rows = r.json() or []
+    return [str(k.get("id")) for k in rows if isinstance(k, dict) and k.get("id")]
+
+
+async def derive_nebius_pod_spec(*, min_vram_gb: "Optional[int]" = None) -> "Optional[dict]":
+    """Nebius's cheapest EU single-GPU preset, as a complete launch spec.
+
+    WHERE "CHEAPEST" COMES FROM, after one correction. `/compute/v1/platforms` publishes
+    platforms, presets and GPU counts and NO money, and on that basis I previously wrote that the
+    vendor publishes no price and required the operator's `FRUTEBOX_NEBIUS_PRICES` table. That was
+    wrong: Nebius publishes no price LIST, but
+    `/billing/v1alpha1/calculators/estimate` prices a SPECIFIC platform+preset, which is exactly
+    the question here. So the order is now the operator's table FIRST (it is what the account is
+    contracted at) and the vendor's calculator second (list price for the configuration), and the
+    chosen row records WHICH answered — reporting one as the other would be a false provenance on
+    a figure that gates spending.
+
+    With neither source answering, "cheapest" is unanswerable and this says so instead of picking
+    — except where exactly one preset fits at all, when there is nothing to be cheapest among.
+
+    The subnet and the image are DISCOVERED (§A5), not configured: a guessed subnet is a machine on
+    the wrong network or an unreachable one, and a guessed image family is a box with no driver.
+    """
+    floor = PROOF_MIN_VRAM_GB if min_vram_gb is None else int(min_vram_gb)
+    prov = PROVIDERS.get("nebius")
+    if prov is None or not prov.configured():
+        log.error("nebius: cannot derive a pod spec without an authorized key and a project — "
+                  "the catalog is an authenticated read. This is Owner 34, not a code change.")
+        return None
+    project = await prov._resolve_project()
+    if not project:
+        log.error("nebius: no project for region %s, so there is no catalog to derive from",
+                  NEBIUS_REGION)
+        return None
+    if not await prov._assert_eu_project(project):
+        # The EU gate fails CLOSED here exactly as it does in `create`: an unverified jurisdiction
+        # is not an EU one, and deriving a spec for a non-EU project would hand `create` something
+        # it must then refuse.
+        return None
+    headers = await prov._headers()
+    if headers is None:
+        return None
+
+    try:
+        async with httpx.AsyncClient(timeout=30) as c:
+            plat_r = await c.get(f"{prov._BASE}/compute/v1/platforms", headers=headers,
+                                 params={"parentId": project})
+            subnet_r = await c.get(f"{prov._BASE}/vpc/v1/subnets", headers=headers,
+                                   params={"parentId": project})
+    except Exception as e:
+        log.error("nebius: catalog read failed (%s) — not deriving a spec", type(e).__name__)
+        return None
+    if plat_r.status_code >= 300 or subnet_r.status_code >= 300:
+        log.error("nebius: catalog read HTTP %s/%s — not deriving a spec",
+                  plat_r.status_code, subnet_r.status_code)
+        return None
+
+    prices = nebius_price_table()
+
+    fitting: List[dict] = []
+    for plat in ((plat_r.json() or {}).get("items") or []):
+        if not isinstance(plat, dict):
+            continue
+        pname = str(((plat.get("metadata") or {}).get("name") or "")).strip()
+        pspec = plat.get("spec") or {}
+        for preset in (pspec.get("presets") or []):
+            res = preset.get("resources") or {}
+            if int(res.get("gpuCount") or 0) != 1:
+                continue
+            # ABSENT VRAM IS UNKNOWN, NOT ZERO — and treating it as zero was my own instance of
+            # this codebase's most expensive habit. Measured 2026-10-18: this project's catalog
+            # publishes `gpu-b300-sxm/1gpu-24vcpu-346gb` with NO `gpuMemoryGibibytes` at either the
+            # preset or the platform level, so `or 0` scored a B300 (288GB of HBM3e) as 0GB and the
+            # derivation reported "no EU single-GPU preset with >=16GB VRAM" — refusing the only
+            # qualifying GPU on the account for lack of a field.
+            #
+            # So an unpublished figure means the floor CANNOT BE APPLIED, and that is said out loud
+            # rather than resolved either way silently. It is admitted because `gpuCount == 1` on a
+            # named GPU platform is already a strong filter and the alternative discards real
+            # capacity; the log line is what stops that being an invisible assumption.
+            raw_vram = res.get("gpuMemoryGibibytes") or pspec.get("gpuMemoryGibibytes")
+            vram = int(raw_vram) if raw_vram else 0
+            if raw_vram and vram < floor:
+                continue
+            if not raw_vram:
+                log.warning("nebius: %s/%s publishes no gpuMemoryGibibytes, so the >=%dGB floor "
+                            "could NOT be checked for it — admitted on gpuCount=1 alone",
+                            pname, preset.get("name"), floor)
+            key = f"{pname}/{preset.get('name')}"
+            fitting.append({"name": key, "platform": pname, "preset": str(preset.get("name")),
+                            "vram_gb": vram, "usd_per_hr": prices.get(key)})
+
+    if not fitting:
+        log.error("nebius: no EU single-GPU preset with >=%dGB VRAM in the project's catalog. "
+                  "NOT falling back to a guess.", floor)
+        return None
+
+    # THE VENDOR DOES PRICE A CONFIGURATION, and I previously wrote that it does not. What Nebius
+    # publishes is no price LIST — `/compute/v1/platforms` carries hardware and no money — but
+    # `/billing/v1alpha1/calculators/estimate` prices a SPECIFIC platform+preset, which is exactly
+    # the question being asked here. Measured 2026-10-18: the 1×B300 preset returns
+    # `hourlyCost.general.total.cost = 9.5`. An operator table is now an OVERRIDE rather than the
+    # only source, so the cap and the merit order get a real number with no configuration at all.
+    for f in fitting:
+        f["price_source"] = "FRUTEBOX_NEBIUS_PRICES" if f["usd_per_hr"] is not None else ""
+        if f["usd_per_hr"] is None:
+            f["usd_per_hr"] = await _nebius_estimate_hourly(prov, headers, project,
+                                                            f["platform"], f["preset"])
+            if f["usd_per_hr"] is not None:
+                f["price_source"] = "vendor calculator (/billing/v1alpha1/calculators/estimate)"
+    priced = [f for f in fitting if f["usd_per_hr"] is not None]
+    if priced:
+        best = _cheapest_fitting(priced)
+    elif len(fitting) == 1:
+        best = fitting[0]
+        log.warning("nebius: one qualifying preset (%s), and neither the calculator nor "
+                    "FRUTEBOX_NEBIUS_PRICES gave a price — choosing it because there is nothing to "
+                    "be cheapest among, but the live-proof cap cannot be checked against it.",
+                    best["name"])
+    else:
+        log.error("nebius: %d qualifying presets and NO price from the calculator or "
+                  "FRUTEBOX_NEBIUS_PRICES (%s). 'Cheapest' is unanswerable and picking one would "
+                  "be spending on a coin flip.", len(fitting), ", ".join(f["name"] for f in fitting))
+        return None
+
+    subnets = [s for s in ((subnet_r.json() or {}).get("items") or []) if isinstance(s, dict)]
+    subnet_id = ""
+    for s in subnets:
+        sid = str(((s.get("metadata") or {}).get("id") or ""))
+        if sid:
+            subnet_id = sid
+            break
+    if not subnet_id:
+        log.error("nebius: the project has no subnet to place an instance in (%d listed) — "
+                  "refusing to guess a subnet id", len(subnets))
+        return None
+    if len(subnets) > 1:
+        log.warning("nebius: project %s has %d subnets; using %s. Set FRUTEBOX_NEBIUS_POD_SPEC if "
+                    "that is the wrong network.", project, len(subnets), subnet_id)
+
+    family = await _nebius_image_family(prov, headers, best["platform"], best["preset"],
+                                       region=prov._project_region.get(project, ""))
+    if not family:
+        return None
+
+    # WHERE THE NUMBER CAME FROM, NAMED. It is one of two sources and they are not
+    # interchangeable: the operator's table is what this account is contracted at, while the
+    # vendor's calculator is list price for the configuration. Reporting one as the other is a
+    # false provenance on a figure that gates spending — and this line did exactly that for one
+    # commit, claiming FRUTEBOX_NEBIUS_PRICES for a number the calculator had produced.
+    #
+    # NEITHER CARRIES A CURRENCY. The calculator's v1alpha1 response is a bare number and the
+    # operator's table is whatever they typed, so the unit is not asserted here. The v1 batch
+    # endpoint does take a `currency`, and answered 500 for this spec.
+    src_txt = best.get("price_source") or "unknown source"
+    price_txt = (("%.4f/hr (unit unstated by the source; from %s)" % (best["usd_per_hr"], src_txt))
+                 if best["usd_per_hr"] is not None else "UNKNOWN — no price from either source")
+    log.info("nebius: derived pod spec — platform=%s preset=%s vram=%dGB subnet=%s "
+             "imageFamily=%s PRICE=%s (cheapest of %d qualifying EU single-GPU preset(s))",
+             best["platform"], best["preset"], best["vram_gb"], subnet_id, family, price_txt,
+             len(fitting))
+    return {
+        "platform": best["platform"],
+        "preset": best["preset"],
+        "imageFamily": family,
+        "subnetId": subnet_id,
+        "_derived": {"price_per_hr": best["usd_per_hr"],
+                     "price_source": src_txt,
+                     "currency": "unstated by the source",
+                     "vram_gb": best["vram_gb"],
+                     "vram_checked": bool(best["vram_gb"]),
+                     "qualifying": len(fitting),
+                     "source": "nebius /compute/v1/platforms + /vpc/v1/subnets"
+                               " + /compute/v1/images/list-public"},
+    }
+
+
+async def _nebius_estimate_hourly(prov, headers: dict, project: str,
+                                  platform: str, preset: str) -> "Optional[float]":
+    """What the vendor says this platform+preset costs per hour, or `None`.
+
+    THE REQUEST SHAPE WAS FOUND BY ASKING, because the published schema does not give it: the
+    OpenAPI document types `billing.v1.ResourceSpec.spec` as an unexpanded `any`, so three shapes
+    were tried against the live API 2026-10-18 and its own errors named the problem — the first two
+    returned "container id is required: invalid container id". The one it accepts nests the project
+    the same way a create does, `{computeInstanceSpec: {metadata: {parentId}, spec: {resources}}}`.
+
+    `None` on any failure, never a zero: a zero price is the cheapest thing in any catalog and
+    would win every comparison it entered, which is the phantom-cheapest-row failure this file
+    guards against elsewhere.
+
+    THE CURRENCY IS THE ACCOUNT'S and is not asserted here. The v1alpha1 response carries a bare
+    number with no currency field; the v1 batch endpoint takes a `currency` parameter but answered
+    500 for this spec. So the figure is reported as the vendor's own unit rather than relabelled
+    into euros, for the same reason Verda's price is logged as USD when the catalog says USD.
+    """
+    body = {"resourceSpec": {"computeInstanceSpec": {
+        "metadata": {"parentId": project},
+        "spec": {"resources": {"platform": platform, "preset": preset}}}}}
+    try:
+        async with httpx.AsyncClient(timeout=30) as c:
+            r = await c.post(f"{prov._BASE}/billing/v1alpha1/calculators/estimate",
+                             headers=headers, json=body)
+    except Exception as e:
+        log.warning("nebius: price estimate for %s/%s failed (%s)", platform, preset,
+                    type(e).__name__)
+        return None
+    if r.status_code >= 300:
+        log.warning("nebius: price estimate for %s/%s HTTP %s", platform, preset, r.status_code)
+        return None
+    try:
+        cost = (((r.json() or {}).get("hourlyCost") or {}).get("general") or {}
+                ).get("total", {}).get("cost")
+        return float(cost) if cost is not None else None
+    except (TypeError, ValueError, AttributeError):
+        log.warning("nebius: price estimate for %s/%s returned an unreadable body shape",
+                    platform, preset)
+        return None
+
+
+async def _nebius_image_family(prov, headers: dict, platform: str, preset: str,
+                               *, region: str = "") -> str:
+    """A public image family the vendor says can boot on this platform/preset.
+
+    `ImageSpec` carries `recommendedPlatforms` and `unsupportedPresets`, so this is a READ rather
+    than a guess: an image the vendor marks unsupported for the chosen preset is excluded, and one
+    that recommends the chosen platform is preferred over one that merely does not forbid it.
+    """
+    if not region:
+        # The catalog cannot be read without it, and inventing one would ask a different region's
+        # catalog than the project actually launches in.
+        log.error("nebius: no region established for the project, so the public image catalog "
+                  "cannot be queried (it requires one) — refusing to guess an image family")
+        return ""
+    try:
+        async with httpx.AsyncClient(timeout=30) as c:
+            r = await c.get(f"{prov._BASE}/compute/v1/images/list-public", headers=headers,
+                            params={"region": region})
+    except Exception as e:
+        log.error("nebius: public image list failed (%s)", type(e).__name__)
+        return ""
+    if r.status_code >= 300:
+        log.error("nebius: public image list HTTP %s", r.status_code)
+        return ""
+    recommended, allowed = [], []
+    for img in ((r.json() or {}).get("items") or []):
+        if not isinstance(img, dict):
+            continue
+        spec = img.get("spec") or {}
+        family = str(spec.get("imageFamily") or "").strip()
+        if not family:
+            continue
+        if any(str(u.get("preset")) == preset and str(u.get("platform")) == platform
+               for u in (spec.get("unsupportedPresets") or []) if isinstance(u, dict)):
+            continue
+        if platform in [str(p) for p in (spec.get("recommendedPlatforms") or [])]:
+            recommended.append(family)
+        elif platform not in [str(p) for p in (spec.get("unsupportedPlatforms") or [])]:
+            allowed.append(family)
+    # CUDA first within each tier: the node runs ollama on a GPU, and an image with no driver
+    # boots a machine that bills and cannot serve.
+    for tier in (recommended, allowed):
+        cuda = sorted(f for f in tier if "cuda" in f.lower())
+        if cuda:
+            return cuda[-1]
+    if recommended:
+        log.warning("nebius: no CUDA image family recommended for %s; using %s, which may need a "
+                    "driver install in cloud-init", platform, sorted(recommended)[-1])
+        return sorted(recommended)[-1]
+    log.error("nebius: no image family the vendor permits on %s/%s — refusing to guess one",
+              platform, preset)
+    return ""
+
+
+# ---- Lambda Cloud --------------------------------------------------------------------------
+
+class LambdaProvider:
+    name = "lambda"
+    _BASE = "https://cloud.lambdalabs.com/api/v1"
+
+    def _key(self) -> str:
+        return _provider_credential("lambda", "LAMBDA_API_KEY")
+
+    def configured(self) -> bool:
+        return bool(self._key())
+
+    def _headers(self) -> dict:
+        return {"Authorization": f"Bearer {self._key()}", "content-type": "application/json"}
+
+    #: Gone: no longer rented, nothing left to terminate.
+    _GONE = frozenset({"terminated"})
+
+    #: Rented but NOT serving. `unhealthy` is Lambda's billing corpse — the VM is up and charged
+    #: for, and nothing on it works. `terminating` is already leaving, so it must not be counted
+    #: as capacity a new request could land on. Both still belong to TEARDOWN.
+    _NOT_SERVING = _GONE | frozenset({"unhealthy", "terminating"})
+
+    async def _labelled(self, label: str) -> List[dict]:
+        async with httpx.AsyncClient(timeout=30) as c:
+            r = await c.get(f"{self._BASE}/instances", headers=self._headers())
+            if r.status_code >= 300:
+                return []
+            return [i for i in ((r.json() or {}).get("data") or [])
+                    if i.get("name") == label]
+
+    async def find(self, label: str) -> List[Instance]:
+        return await self.find_all(label)
+
+    async def find_all(self, label: str) -> List[Instance]:
+        """TEARDOWN breadth: everything Lambda has not terminated is still rented by the hour."""
+        return [Instance(id=i.get("id"), label=i.get("name"))
+                for i in await self._labelled(label)
+                if str(i.get("status", "")).lower() not in self._GONE]
+
+    async def find_live(self, label: str) -> List[Instance]:
+        """CAPACITY: booting or active only.
+
+        Lambda rents whole VMs, so it cannot see inside the container the way RunPod's `runtime`
+        does — an `active` VM whose workload died still reads as live here. What it CAN tell is
+        `unhealthy`, and that one must not hold a pool slot.
+        """
+        return [Instance(id=i.get("id"), label=i.get("name"))
+                for i in await self._labelled(label)
+                if str(i.get("status", "")).lower() not in self._NOT_SERVING]
+
+    async def create(self, label: str, spec: dict) -> bool:
+        region = spec.get("region") or os.environ.get("LAMBDA_REGION", "")
+        itype = spec.get("instanceType") or os.environ.get("LAMBDA_INSTANCE_TYPE", "")
+        ssh = [k for k in (os.environ.get("LAMBDA_SSH_KEYS", "").split(",")) if k]
+
+        # §A5 option 1 (owner ruling 2026-09-22): the operator named the instance type — the
+        # decision that costs money — so discover the account-scoped rest of it. Only what they
+        # left unset is filled; an explicit value always wins, and nothing here picks an
+        # instance type. Without this, an unset region silently became "us-west-1", which fails
+        # for a type that has capacity only elsewhere.
+        if itype and (not region or not ssh):
+            derived = await derive_lambda_launch(instance_type=itype)
+            region = region or derived.get("LAMBDA_REGION", "")
+            ssh = ssh or [k for k in derived.get("LAMBDA_SSH_KEYS", "").split(",") if k]
+
+        body = {
+            "region_name": region or "us-west-1",
+            "instance_type_name": itype,
+            "ssh_key_names": ssh,
+            "name": label,                        # the caller's label, never the spec's
+            "quantity": 1,
+        }
+        if not body["instance_type_name"]:
+            return False
+        async with httpx.AsyncClient(timeout=60) as c:
+            r = await c.post(f"{self._BASE}/instance-operations/launch",
+                             headers=self._headers(), json=body)
+            if r.status_code >= 300:
+                return False
+            return bool(((r.json() or {}).get("data") or {}).get("instance_ids"))
+
+    async def destroy(self, instance_id: str) -> bool:
+        async with httpx.AsyncClient(timeout=30) as c:
+            r = await c.post(f"{self._BASE}/instance-operations/terminate",
+                             headers=self._headers(), json={"instance_ids": [instance_id]})
+            return r.status_code < 300 or r.status_code == 404
+
+
+# ---- Nebius, the SECOND EU provider behind Verda (owner decision 7, 2026-10-14) -------------
+#
+# PROMOTED 2026-10-16: with RunPod being replaced, this and Verda ARE the EU pool.
+#
+# WHAT THIS CLASS USED TO BE, AND WHAT CHANGED. It was a scaffold that refused: `create` raised
+# rather than POST to a guessed path, because `api.nebius.cloud` answering 404 to an
+# unauthenticated root GET proves the host resolves and nothing about the operations. That refusal
+# was right, and the reason for it is now GONE rather than overruled — Nebius publishes an OpenAPI
+# document at `https://api.nebius.cloud/openapi.json` (443 paths, fetched 2026-10-16), so the paths
+# below were READ, not derived from the gRPC service names.
+#
+# REST, NOT THE gRPC SDK — the choice, and why it is not laziness. Every other adapter in this file
+# speaks HTTP through `httpx`. The `nebius` pip package is gRPC plus generated protobufs: a large
+# new dependency and a second concurrency model, bought to obtain paths that are now published. The
+# protos in `nebius/api` carry NO `google.api.http` annotations, so the OpenAPI document — not the
+# proto — is the authority for REST, and it is what was used. If a future operation turns out to be
+# gRPC-only, that is the moment to take the dependency, for that operation, with a reason.
+#
+# AUTH IS A TWO-STEP EXCHANGE, unlike every other provider here. There is no static API key: a
+# service account holds an AUTHORIZED KEY (a key id + the service account id + an RSA private key),
+# the client signs a short-lived JWT with it, and POSTs that to the IAM token endpoint to get a
+# 12-hour access token. Signed with `cryptography`, which is already a declared dependency —
+# PyJWT would be a new one for fifteen lines, and this file already has an RS256 precedent in
+# `tee.py`.
+#
+# THE REGION IS A PROPERTY OF THE PROJECT, NOT OF THE INSTANCE, and that is the single most
+# important thing about placing EU work here. `CreateInstanceRequest` has no region field at all —
+# `metadata.parentId` names a PROJECT, and the project's own `spec.region` decides where the
+# hardware is. So "EU only" cannot be enforced by inspecting a create body; it is enforced by
+# CHECKING THE PROJECT, which `_assert_eu_project` does against `GET /iam/v2/projects/{id}` before
+# anything is created. A product that promised EU residency off an unchecked `parentId` would be
+# promising whatever project id happened to be configured.
+#
+# RESIDENCY: NO LONGER HELD. The seed row carried `residency_hold: true` — a Dutch-incorporated
+# provider with a Yandex lineage, excluded from legally pinned EU work until the owner decided.
+# The owner decided on 2026-10-20: Nebius may run EU-locked work, so the flag is gone from the
+# seed row and `regionmap.residency_providers` stops excluding it. The hold was about corporate
+# lineage; the EU-region check above is a DIFFERENT thing and it still applies, because it is the
+# one that is checked rather than declared — `_assert_eu_project` reads the project's region from
+# IAM before any create, and that is what makes "EU only" a fact instead of a promise.
+#: THE EU REGION NEBIUS WORK RUNS IN (owner rule, 2026-10-21): "Point Nebius EU at the eu-north1
+#: project (GPUs actually start there), not eu-west2."
+#:
+#: Measured 2026-10-20, which is why it is this one: this account holds one project per region and
+#: their GPU CATALOGUES DIFFER. eu-west2 publishes `gpu-b300-sxm` and nothing else, so "the
+#: cheapest EU single-GPU preset" could only ever be a 1xB300 - and that preset reverts
+#: STARTING -> STOPPED after ~5m20s with no status message, no operation record and no serial
+#: console. eu-north1 publishes 17 GPU presets (L40S/H100/H200/GB300) and an L40S reached RUNNING
+#: in 78 seconds on the identical code path.
+NEBIUS_REGION = envvar("NEBIUS_REGION", "eu-north1")
+
+NEBIUS_BASE = envvar("NEBIUS_API_BASE", "https://api.nebius.cloud").rstrip("/")
+
+#: The IAM token-exchange endpoint. EU by deliberate choice of host, not only of region: the
+#: exchange is where the service-account assertion is presented, so sending it to a non-EU auth
+#: host would route the credential itself outside the bloc.
+NEBIUS_AUTH_URL = envvar("NEBIUS_AUTH_URL", "https://auth.eu.nebius.com/oauth2/token/exchange")
+
+#: Compute REST paths, READ from the published OpenAPI document 2026-10-16 (not derived):
+#:   POST   /compute/v1/instances          create
+#:   GET    /compute/v1/instances          list      (?parentId=&pageSize=&pageToken=)
+#:   GET    /compute/v1/instances/{id}     get
+#:   DELETE /compute/v1/instances/{id}     delete
+#: `POST /compute/v1/instances/start` and `/stop` also exist and are NEVER called from here —
+#: TERMINATE NEVER STOP, and a stopped instance keeps its disks and its bill.
+NEBIUS_INSTANCES_PATH = "/compute/v1/instances"
+NEBIUS_PROJECTS_PATH = "/iam/v2/projects"
+
+#: Nebius regions this product treats as EU, from the vendor's region list (2026-10-16):
+#: `eu-north1` Finland, `eu-west1` and `eu-west2` France.
+#:
+#: `eu-north2` IS ICELAND and is deliberately absent — EEA, not EU, exactly like Verda's ICE-01 —
+#: and `us-central1` is Kansas City. The `eu-` prefix is the vendor's NAME for a region, not a
+#: statement about EU membership, so this is an allow-list of codes and never a prefix match.
+NEBIUS_EU_REGIONS = frozenset(
+    r.strip().lower() for r in envvar("NEBIUS_EU_REGIONS", "eu-north1,eu-west1,eu-west2").split(",")
+    if r.strip()
+)
+
+#: Instance states, READ from the OpenAPI enum `nebius.compute.v1.InstanceStatus.InstanceState`:
+#: UNSPECIFIED, CREATING, UPDATING, STARTING, RUNNING, STOPPING, STOPPED, DELETING, ERROR.
+#:
+#: SERVING is `RUNNING` alone. Everything the list returns still exists and can still bill, so
+#: there is no `_DEAD` set here at all: for Nebius, GONE means ABSENT FROM THE LIST. `DELETING` is
+#: deliberately counted as still-present — a deletion in flight is not a deletion observed, and the
+#: teardown's own verification is what establishes the difference.
+NEBIUS_SERVING_STATES = frozenset({"RUNNING"})
+
+
+def nebius_price_table() -> "Dict[str, float]":
+    """The operator's `platform/preset -> price per hour` table, parsed. `{}` when unset.
+
+    ONE PARSER AND ONE ENV READ, shared by `gpuprices._fetch_nebius` (the merit order) and
+    `derive_nebius_pod_spec` (the live proof's default). It lives here rather than in `gpuprices`
+    because that module already imports this one, so the other direction would be a cycle.
+
+    WHY IT IS NOT TWO FUNCTIONS. The second copy was written before this one existed, and the two
+    read the same variable with the same JSON shape for the same purpose — the exact duplication
+    this repo's rule 12 is about, and the kind that drifts: a fix to one copy's number handling
+    would silently not reach the other, so the price the race ranks on and the price the cap is
+    checked against could disagree.
+
+    A ROW THAT WILL NOT PARSE IS DROPPED, NOT ZEROED. A zero price is the cheapest thing in any
+    catalog and would win every race; an absent one simply does not compete.
+    """
+    raw = (envvar("NEBIUS_PRICES", "") or "").strip()
+    if not raw:
+        return {}
+    try:
+        parsed = json.loads(raw)
+    except Exception as e:
+        log.error("nebius: FRUTEBOX_NEBIUS_PRICES is not valid JSON (%s) — no operator prices",
+                  type(e).__name__)
+        return {}
+    if not isinstance(parsed, dict):
+        log.error("nebius: FRUTEBOX_NEBIUS_PRICES must be a JSON object of "
+                  "'platform/preset': price_per_hour — no operator prices")
+        return {}
+    out: Dict[str, float] = {}
+    for k, v in parsed.items():
+        try:
+            price = float(v)
+        except (TypeError, ValueError):
+            continue
+        if price > 0:
+            out[str(k)] = price
+    return out
+
+
+def _b64url(raw: bytes) -> str:
+    """JWS base64url: no padding. A padded segment is rejected by the token endpoint."""
+    import base64
+    return base64.urlsafe_b64encode(raw).rstrip(b"=").decode()
+
+
+def nebius_jwt(*, key_id: str, service_account_id: str, private_key_pem: str,
+               now: "Optional[float]" = None, ttl_s: int = 300) -> str:
+    """The signed assertion that is exchanged for an IAM token. RS256, five-minute life.
+
+    Claims, from the vendor's own documented flow: `kid` (the AUTHORIZED KEY's id) in the header,
+    `iss` and `sub` both the SERVICE ACCOUNT's id, and `exp`. Short-lived on purpose — it is used
+    once, immediately, to obtain the real token, so a longer life buys nothing and widens the
+    window in which a captured assertion is useful.
+
+    A MODULE-LEVEL FUNCTION rather than a method, so the signing can be tested against a generated
+    key pair without constructing a provider or touching a credential store — and so it is
+    obviously one pure function of its inputs. It takes the PEM as a string and never a path: the
+    key reaches this process through the credential store, not off a disk this code chose.
+    """
+    from cryptography.hazmat.primitives import hashes, serialization
+    from cryptography.hazmat.primitives.asymmetric import padding, rsa
+
+    key = serialization.load_pem_private_key(private_key_pem.encode(), password=None)
+    if not isinstance(key, rsa.RSAPrivateKey):
+        # RS256 is what the vendor documents. An EC key here would sign something the endpoint
+        # cannot verify, and the resulting 401 would look like a wrong key rather than a wrong
+        # ALGORITHM — a diagnosis worth hours.
+        raise ValueError("nebius: the authorized key's private key is not RSA; RS256 is required")
+    issued = int(now if now is not None else time.time())
+    header = {"alg": "RS256", "typ": "JWT", "kid": key_id}
+    claims = {"iss": service_account_id, "sub": service_account_id,
+              "iat": issued, "exp": issued + ttl_s}
+    signing_input = f"{_b64url(json.dumps(header).encode())}.{_b64url(json.dumps(claims).encode())}"
+    sig = key.sign(signing_input.encode(), padding.PKCS1v15(), hashes.SHA256())
+    return f"{signing_input}.{_b64url(sig)}"
+
+
+class NebiusProvider:
+    """Nebius AI Cloud GPU, through the same `GpuProvider` protocol as every other backend.
+
+    Second in the EU preference order, behind Verda.
+    """
+
+    name = "nebius"
+    _BASE = NEBIUS_BASE
+
+    #: IT DISTINGUISHES, and this is a reading rather than a hope. The previous `False` said the
+    #: list response had not been read; it has been now — the OpenAPI document publishes the
+    #: `InstanceState` enum, so `RUNNING` is separable from `STOPPED` and from a creation still in
+    #: flight. `test_gpuproviders.py`'s contract test refuses a `True` the code does not back up,
+    #: so this is only legal while both enumerations exist below.
+    DISTINGUISHES_SERVING = True
+
+    def __init__(self) -> None:
+        self._token = ""
+        self._token_expires = 0.0
+        #: The project whose region has already been checked, so the check is one call per project
+        #: per process and not one per create. Cleared with the token.
+        self._eu_checked: Set[str] = set()
+        #: The project `_resolve_project` found for `NEBIUS_REGION`, once. Empty until it has run
+        #: and empty if it could not read the account — never a stand-in for one it did not find.
+        self._discovered_project: str = ""
+        #: project id -> the region `_assert_eu_project` read for it. Kept because the image
+        #: catalog REQUIRES a region ("validation error: region: value is required") and the EU
+        #: gate has already established it — asking IAM twice for the same fact, or worse guessing
+        #: it from the project's NAME, would be two ways of being wrong about jurisdiction.
+        self._project_region: Dict[str, str] = {}
+
+    # ---- credential ------------------------------------------------------------------------
+
+    def _key(self) -> dict:
+        """The authorized key as a dict, or `{}`.
+
+        ONE ENV VAR HOLDING A JSON DOCUMENT, which is unlike every other provider here, so it is
+        parsed in one place. A malformed key is `{}` — not a partial dict — because a half-read
+        credential that still looks truthy is how a provider reports ready and then cannot sign.
+
+        FIELD NAMES ARE THE VENDOR'S OWN, as they appear in the key file IAM issues: `id` is the
+        AUTHORIZED KEY's id (the JWT's `kid`), `service_account_id` is the account it belongs to,
+        and `private_key` is the PEM. `subject-credentials` wrappers are not unwrapped here: a key
+        file in a shape we have not seen is reported as missing fields rather than guessed at.
+        """
+        raw = _provider_credential("nebius", "NEBIUS_SERVICE_ACCOUNT_KEY")
+        if not raw:
+            return self._key_from_parts()
+        try:
+            doc = json.loads(raw)
+        except Exception:
+            # NOT the contents. A parse error on a credential must not put the credential in a log.
+            log.error("nebius: NEBIUS_SERVICE_ACCOUNT_KEY is not valid JSON — refusing to use it")
+            return {}
+        if not isinstance(doc, dict):
+            return {}
+        # The three fields an authorized key must have to be signable. Reported as names only.
+        missing = [f for f in ("id", "service_account_id", "private_key") if not doc.get(f)]
+        if missing:
+            log.error("nebius: authorized key is missing %s", ",".join(missing))
+            return {}
+        return doc
+
+    def _key_from_parts(self) -> dict:
+        """The same authorized key, assembled from the three parts under their own names.
+
+        WHY THIS EXISTS. `NEBIUS_SERVICE_ACCOUNT_KEY` is one env var holding a JSON document, and
+        IAM does not hand you that document — it hands you a key id, an account id, and a PEM, in
+        three places. So using this provider required hand-building JSON around a private key,
+        which is both the easiest thing to get wrong and the easiest thing to leave in a shell
+        history. On 2026-10-20 the estate file held Nebius credentials and this provider still
+        reported itself unconfigured, because nothing could assemble that document from the parts
+        that actually existed on the machine.
+
+        The JSON form stays primary (it is what IAM's downloadable key file becomes, and it is one
+        secret instead of three). This is the fallback, and it reports WHICH part is missing: with
+        one var the only possible answer was "no credential", which is indistinguishable from
+        "three quarters of a credential".
+
+        `NEBIUS_PRIVATE_KEY_FILE` names a path rather than carrying the PEM, which is how the key
+        reaches an operator's shell in the first place. `nebius_jwt` still takes the PEM as a
+        string and never a path — the disk this reads is the one the OPERATOR named, not one this
+        code went looking for.
+        """
+        key_id = _provider_credential("nebius", "NEBIUS_PUBLIC_KEY_ID")
+        sa_id = _provider_credential("nebius", "NEBIUS_SERVICE_ACCOUNT_ID")
+        pem = _provider_credential("nebius", "NEBIUS_PRIVATE_KEY")
+        if not pem:
+            path = _provider_credential("nebius", "NEBIUS_PRIVATE_KEY_FILE")
+            if path:
+                try:
+                    with open(os.path.expanduser(path), "r", encoding="utf-8") as fh:
+                        pem = fh.read()
+                except Exception as e:
+                    # The PATH may be logged; what is at the end of it may not.
+                    log.error("nebius: NEBIUS_PRIVATE_KEY_FILE could not be read (%s)",
+                              type(e).__name__)
+                    return {}
+        if not (key_id or sa_id or pem):
+            # Nothing of this provider is configured. THAT is not the same as a broken key, so it
+            # is not reported as one — but say so if the one credential in the estate is the one
+            # that cannot sign, because that diagnosis took a day to make once.
+            access_key = _provider_credential("nebius", "NEBIUS_KEY_ID")
+            if access_key:
+                log.error(
+                    "nebius: NEBIUS_KEY_ID/NEBIUS_SECRET_KEY are an OBJECT-STORAGE access key "
+                    "(IAM rejects the id as 'Invalid nid format'); the compute API needs a "
+                    "service-account authorized key — set NEBIUS_SERVICE_ACCOUNT_ID, "
+                    "NEBIUS_PUBLIC_KEY_ID and NEBIUS_PRIVATE_KEY_FILE")
+            return {}
+        missing = [n for n, v in (("NEBIUS_PUBLIC_KEY_ID", key_id),
+                                  ("NEBIUS_SERVICE_ACCOUNT_ID", sa_id),
+                                  ("NEBIUS_PRIVATE_KEY/_FILE", pem)) if not v]
+        if missing:
+            log.error("nebius: authorized key is incomplete, missing %s", ",".join(missing))
+            return {}
+        return {"id": key_id, "service_account_id": sa_id, "private_key": pem}
+
+    def _project_id(self) -> str:
+        """The project every call is scoped to — `metadata.parentId` on create, `parentId` on list.
+
+        ACCOUNT-SCOPED, NOT A SECRET (§A5: the owner supplies the credential, the code discovers
+        the account's resources). It used to be required configuration on the reasoning that
+        "picking one for the operator would be choosing where the money is spent and which
+        jurisdiction the data lands in" — and that reasoning was right about the CHOICE and wrong
+        about who had to type it. The owner has now made the choice, by region: EU work runs in
+        `NEBIUS_REGION` (eu-north1). Which project id that is, in this account, is an account
+        resource — exactly the kind of thing §A5 says the code discovers.
+
+        So: explicit configuration still wins, and otherwise `_resolve_project` finds the project
+        whose own region IS the named one. Nothing is guessed either way; a region with no project
+        resolves to "" and every caller refuses, which is what it did before.
+        """
+        explicit = _provider_credential("nebius", "NEBIUS_PROJECT_ID").strip()
+        return explicit or self._discovered_project
+
+    async def _resolve_project(self) -> str:
+        """The project id for `NEBIUS_REGION`, discovered once and remembered.
+
+        One listing, cached for the process: the account's project set changes on the timescale of
+        someone creating a project, and re-asking per create would put an IAM round trip on the
+        spend path for an answer that does not move.
+
+        A FAILED LISTING IS NOT "NO PROJECT". It leaves the cache empty and returns "", so the
+        caller refuses — the same answer an unconfigured deployment gets, and never a different
+        region's project standing in for the one we could not read.
+        """
+        explicit = _provider_credential("nebius", "NEBIUS_PROJECT_ID").strip()
+        if explicit or self._discovered_project:
+            return explicit or self._discovered_project
+        want = (NEBIUS_REGION or "").strip().lower()
+        if not want:
+            return ""
+        headers = await self._headers()
+        if headers is None:
+            return ""
+        try:
+            async with httpx.AsyncClient(timeout=30) as c:
+                t = await c.get(f"{self._BASE}/iam/v1/tenants", headers=headers)
+                if t.status_code >= 300:
+                    log.error("nebius: tenant listing HTTP %s — cannot resolve the %s project",
+                              t.status_code, want)
+                    return ""
+                for ten in ((t.json() or {}).get("items") or []):
+                    tid = str(((ten.get("metadata") or {}).get("id") or ""))
+                    if not tid:
+                        continue
+                    r = await c.get(f"{self._BASE}{NEBIUS_PROJECTS_PATH}", headers=headers,
+                                    params={"parentId": tid})
+                    if r.status_code >= 300:
+                        log.error("nebius: project listing HTTP %s for tenant — cannot resolve "
+                                  "the %s project", r.status_code, want)
+                        return ""
+                    for pr in ((r.json() or {}).get("items") or []):
+                        pid = str(((pr.get("metadata") or {}).get("id") or ""))
+                        regn = str(((pr.get("status") or {}).get("region")
+                                    or (pr.get("spec") or {}).get("region") or "")).lower()
+                        if pid and regn:
+                            self._project_region[pid] = regn
+                        if pid and regn == want:
+                            self._discovered_project = pid
+                            log.info("nebius: EU work scoped to %s (region %s), discovered from "
+                                     "the account rather than configured", pid, regn)
+                            return pid
+        except Exception as e:
+            log.error("nebius: project discovery failed (%s) — refusing rather than scoping "
+                      "calls to a project nobody chose", type(e).__name__)
+            return ""
+        log.error("nebius: the account holds no project in %s, so there is nothing to scope EU "
+                  "work to. Set FRUTEBOX_NEBIUS_PROJECT_ID or create the project.", want)
+        return ""
+
+    def configured(self) -> bool:
+        """A parseable authorized key AND a project to scope calls to — or a region to find one in.
+
+        A key alone is not the ability to call anything: every compute operation needs a
+        `parentId`, so reporting `True` without one is how a provider wins a race it cannot serve.
+        That invariant is unchanged; what changed is that the project may now be DISCOVERED from
+        `NEBIUS_REGION` instead of typed, and discovery needs an async call that cannot happen
+        inside this sync predicate. Returning False until it had run would mean it never ran — no
+        caller asks an unconfigured provider anything — so a named region counts here.
+
+        The race argument survives intact one level down: `create` resolves the project first and
+        refuses when it cannot, before anything is POSTed or billed. So the worst case is a
+        provider that enters a race and declines it for a named reason, which is what a stock-out
+        already looks like.
+        """
+        if not self._key():
+            return False
+        return bool(self._project_id() or (NEBIUS_REGION or "").strip())
+
+    # ---- auth ------------------------------------------------------------------------------
+
+    async def _access_token(self) -> str:
+        """A cached IAM token, refreshed a minute before it actually expires.
+
+        The margin is the same one Verda's token has and for the same reason: a token that passes
+        the check here and expires in flight produces a 401 on the CREATE call, and a create that
+        fails ambiguously is the one failure mode that can leave an instance running that nobody
+        recorded.
+
+        Returns `""` rather than raising, for every failure — a missing credential, an unsignable
+        key, a rejected assertion. Callers fail the way the contract says ("nothing running" /
+        "did not create"), never by raising out of a provider method.
+        """
+        now = time.time()
+        if self._token and now < self._token_expires:
+            return self._token
+        key = self._key()
+        if not key:
+            return ""
+        try:
+            assertion = nebius_jwt(key_id=str(key["id"]),
+                                   service_account_id=str(key["service_account_id"]),
+                                   private_key_pem=str(key["private_key"]))
+        except Exception as e:
+            # The TYPE only. A signing failure must not put the private key in a log.
+            log.error("nebius: could not sign the token assertion (%s) — check that the "
+                      "authorized key's private_key is an RSA PEM", type(e).__name__)
+            return ""
+        try:
+            async with httpx.AsyncClient(timeout=30) as c:
+                r = await c.post(NEBIUS_AUTH_URL, data={
+                    "grant_type": "urn:ietf:params:oauth:grant-type:token-exchange",
+                    "requested_token_type": "urn:ietf:params:oauth:token-type:access_token",
+                    "subject_token": assertion,
+                    "subject_token_type": "urn:ietf:params:oauth:token-type:jwt",
+                })
+        except Exception as e:
+            log.warning("nebius: token exchange unreachable (%s)", type(e).__name__)
+            return ""
+        if r.status_code >= 300:
+            # The STATUS, never the body: an auth error body can echo the assertion back.
+            log.error("nebius: token exchange refused the service-account assertion (HTTP %s)",
+                      r.status_code)
+            return ""
+        token = str((r.json() or {}).get("access_token") or "")
+        if not token:
+            return ""
+        self._token = token
+        self._token_expires = now + max(0.0, float((r.json() or {}).get("expires_in") or 43200)) - 60
+        return token
+
+    async def _headers(self) -> "Optional[dict]":
+        """Auth headers, or None when no token could be obtained.
+
+        None rather than an empty bearer: `Authorization: Bearer ` is an ILLEGAL header value and
+        httpx raises `LocalProtocolError` on it, so a credential problem would surface as a
+        protocol crash from inside the transport.
+        """
+        token = await self._access_token()
+        if not token:
+            return None
+        return {"Authorization": f"Bearer {token}", "content-type": "application/json"}
+
+    # ---- the EU check ----------------------------------------------------------------------
+
+    async def _assert_eu_project(self, project_id: str) -> bool:
+        """Is this project's hardware in the EU? Checked, once per project, before any create.
+
+        WHY THIS EXISTS AT ALL. `CreateInstanceRequest` carries no region: `metadata.parentId`
+        names a project and the PROJECT's `spec.region` decides where the metal is. So there is no
+        field in a create body that an EU gate could inspect — the only honest check is to ask IAM
+        what region the project is in, which is what this does.
+
+        A FAILED CHECK IS NOT A PASS. If the project cannot be read, this returns False and the
+        create is refused. That is the opposite of the usual "degrade toward launching" trade in
+        this file, and deliberately so: everywhere else a failed read costs capacity, while here it
+        would mean placing EU-labelled work on hardware whose jurisdiction was never established.
+        "We could not tell" is not a defence to a regulator — the same call `regionmap`'s residency
+        gate and `provider_of_node` already make.
+        """
+        if project_id in self._eu_checked:
+            return True
+        headers = await self._headers()
+        if headers is None:
+            return False
+        try:
+            async with httpx.AsyncClient(timeout=30) as c:
+                r = await c.get(f"{self._BASE}{NEBIUS_PROJECTS_PATH}/{_urlquote(project_id)}",
+                                headers=headers)
+        except Exception as e:
+            log.error("nebius: could not read project %s to establish its region (%s) — refusing "
+                      "to create. An unverified jurisdiction is not an EU one.",
+                      project_id, type(e).__name__)
+            return False
+        if r.status_code >= 300:
+            log.error("nebius: could not read project %s to establish its region (HTTP %s) — "
+                      "refusing to create.", project_id, r.status_code)
+            return False
+        region = str(((r.json() or {}).get("spec") or {}).get("region") or "").strip().lower()
+        if not region:
+            log.error("nebius: project %s reports no region — refusing to create.", project_id)
+            return False
+        if region not in NEBIUS_EU_REGIONS:
+            log.error("nebius: project %s is in region %r, which is not EU. Permitted: %s. "
+                      "(eu-north2 is ICELAND — EEA, not EU.)",
+                      project_id, region, ",".join(sorted(NEBIUS_EU_REGIONS)))
+            return False
+        self._eu_checked.add(project_id)
+        self._project_region[project_id] = region
+        log.info("nebius: project %s confirmed in EU region %s", project_id, region)
+        return True
+
+    # ---- enumeration -----------------------------------------------------------------------
+
+    async def _list(self) -> "Optional[List[dict]]":
+        """Every instance in the project, across pages, or None when it could not be ASKED.
+
+        None IS NOT AN EMPTY LIST. An unreadable list read as "nothing is there" is this
+        codebase's most expensive recurring mistake, and here it would mean a teardown reporting a
+        clear label while instances bill.
+
+        PAGINATION IS FOLLOWED, which matters more than it looks: a truncated first page read as
+        the whole fleet is the same defect wearing a different hat — the pool would miss its own
+        instances and `start()` would buy duplicates. The page loop is bounded so a server that
+        keeps handing back the same token cannot spin here forever.
+        """
+        headers = await self._headers()
+        if headers is None:
+            return None
+        project = await self._resolve_project()
+        if not project:
+            return None
+        out: List[dict] = []
+        token = ""
+        try:
+            async with httpx.AsyncClient(timeout=30) as c:
+                for _ in range(50):
+                    params = {"parentId": project, "pageSize": "100"}
+                    if token:
+                        params["pageToken"] = token
+                    r = await c.get(f"{self._BASE}{NEBIUS_INSTANCES_PATH}", headers=headers,
+                                    params=params)
+                    if r.status_code >= 300:
+                        log.warning("nebius: instance list HTTP %s", r.status_code)
+                        return None
+                    body = r.json() or {}
+                    out.extend(i for i in (body.get("items") or []) if isinstance(i, dict))
+                    token = str(body.get("nextPageToken") or "")
+                    if not token:
+                        return out
+        except Exception as e:
+            log.warning("nebius: could not list instances (%s)", type(e).__name__)
+            return None
+        log.warning("nebius: instance list did not terminate after 50 pages — returning what was "
+                    "read so far rather than looping, but treat this fleet view as partial")
+        return out
+
+    @staticmethod
+    def _state(row: dict) -> str:
+        return str(((row.get("status") or {}).get("state") or "")).strip().upper()
+
+    @staticmethod
+    def _label(row: dict) -> str:
+        return str(((row.get("metadata") or {}).get("name") or ""))
+
+    @staticmethod
+    def _id(row: dict) -> str:
+        return str(((row.get("metadata") or {}).get("id") or ""))
+
+    def _matching(self, rows: "List[dict]", label: str,
+                  states: "Optional[frozenset]" = None) -> List[Instance]:
+        out: List[Instance] = []
+        for row in rows:
+            if self._label(row) != label:
+                continue
+            state = self._state(row)
+            if states is not None and state not in states:
+                continue
+            out.append(Instance(id=self._id(row), label=label, status=state))
+        return out
+
+    async def find(self, label: str) -> List[Instance]:
+        """THE BASE PRIMITIVE: everything in the project carrying this label.
+
+        GONE MEANS ABSENT. There is no status this treats as dead — every state the list returns is
+        an instance that exists and can bill, `DELETING` included, because a deletion in flight is
+        not a deletion observed.
+        """
+        rows = await self._list()
+        return self._matching(rows or [], label)
+
+    async def find_live(self, label: str) -> List[Instance]:
+        """CAPACITY: only `RUNNING`. A `STOPPED` instance keeps its disks and serves nothing, and a
+        `CREATING` one cannot take a turn yet — counting either as capacity holds a pool slot that
+        nothing is serving from."""
+        rows = await self._list()
+        return self._matching(rows or [], label, NEBIUS_SERVING_STATES)
+
+    async def find_all(self, label: str) -> List[Instance]:
+        """TEARDOWN: everything that could still bill — which here is everything that is listed."""
+        rows = await self._list()
+        return self._matching(rows or [], label)
+
+    async def status(self, label: str) -> dict:
+        """The vendor's own state for each instance under this label, unflattened.
+
+        `{"ok": False}` when the project could not be asked — never an empty `instances` list,
+        which would read as "the label is clear".
+        """
+        rows = await self._list()
+        if rows is None:
+            return {"ok": False, "provider": self.name, "label": label,
+                    "detail": "could not list instances — this is NOT 'the label is clear'"}
+        mine = [r for r in rows if self._label(r) == label]
+        return {
+            "ok": True,
+            "provider": self.name,
+            "label": label,
+            "project": self._project_id(),
+            "instances": [{"id": self._id(r), "state": self._state(r),
+                           "serving": self._state(r) in NEBIUS_SERVING_STATES,
+                           "billing": True,
+                           "boot_disk": (((r.get("spec") or {}).get("bootDisk") or {})
+                                         .get("existingDisk", {}) or {}).get("id", ""),
+                           "platform": (((r.get("spec") or {}).get("resources") or {})
+                                        .get("platform", "")),
+                           "preset": (((r.get("spec") or {}).get("resources") or {})
+                                      .get("preset", ""))}
+                          for r in mine],
+        }
+
+    async def list_account(self) -> "Optional[List[dict]]":
+        """Every instance in the PROJECT, label-agnostic, normalised. `None` when unaskable.
+
+        "Account" is the project here, because that is the widest thing one credential can
+        enumerate — Nebius scopes every compute read to a `parentId`. SO THIS IS NOT A WHOLE-TENANT
+        SWEEP, and saying so matters: an orphan in a DIFFERENT project of the same tenant is
+        invisible to it, and would stay invisible while billing. `podreaper` reports the project it
+        swept for exactly that reason.
+        """
+        rows = await self._list()
+        if rows is None:
+            return None
+        return [{"id": self._id(r),
+                 "label": self._label(r),
+                 "status": self._state(r),
+                 "created_at": ((r.get("metadata") or {}).get("createdAt") or ""),
+                 "price_per_hour": None,     # the vendor publishes no price on the instance
+                 "location": self._project_id(),
+                 "billing": True}            # listed means present means billable
+                for r in rows]
+
+    # ---- create / destroy ------------------------------------------------------------------
+
+    async def create(self, label: str, spec: dict) -> bool:
+        """Create ONE instance carrying THIS label, in a project proven to be in the EU.
+
+        THE SPEC COMES FROM THE OPERATOR, like `RUNPOD_POD_SPEC` and `ALIBABA_ECS_SPEC` (the
+        2026-09-24 `VAST_POD_SPEC` ruling): `platform`, `preset`, the boot image and the subnet are
+        the decisions that pick hardware and cost money, and a provider that guesses them deploys
+        the wrong machine and bills for it. This refuses without them rather than inventing an
+        H100 preset.
+
+        THE BOOT DISK IS VM-MANAGED ON PURPOSE, and it is a money decision rather than a style one.
+        The vendor: "If VM-managed disks are attached to your VM, they are deleted along with the
+        VM automatically" — while standalone disks are not. So a managed boot disk makes `destroy`
+        complete by construction, which is the opposite of Verda, where the volume has to be named
+        explicitly. `forbidDeletion` is never set, for the same reason.
+        """
+        project = await self._resolve_project()
+        if not project:
+            log.error("nebius: refusing to create %r without NEBIUS_PROJECT_ID — every compute "
+                      "call is scoped to a project, and the project decides the region", label)
+            return False
+
+        platform = str(spec.get("platform") or "").strip()
+        preset = str(spec.get("preset") or "").strip()
+        image_family = str(spec.get("imageFamily") or spec.get("image_family") or "").strip()
+        image_id = str(spec.get("imageId") or spec.get("image_id") or "").strip()
+        subnet = str(spec.get("subnetId") or spec.get("subnet_id") or "").strip()
+        if not platform or not preset:
+            log.error("nebius: refusing to create %r without a platform AND a preset. These pick "
+                      "the hardware and the bill; set FRUTEBOX_NEBIUS_POD_SPEC.", label)
+            return False
+        if not (image_family or image_id):
+            log.error("nebius: refusing to create %r without a boot image (imageFamily or "
+                      "imageId) — there is no sane default for what the machine boots.", label)
+            return False
+        if not subnet:
+            log.error("nebius: refusing to create %r without a subnetId — a guessed subnet is a "
+                      "machine on the wrong network, or an unreachable one.", label)
+            return False
+
+        # THE EU CHECK IS BEFORE THE CREATE, not after and not alongside. See `_assert_eu_project`.
+        if not await self._assert_eu_project(project):
+            return False
+
+        # `managedDisk` IS A RESOURCE, NOT A SPEC, and only a live call could say so. The published
+        # OpenAPI flattens `AttachedDiskSpec.managedDisk` to `any`, so the fields went straight in —
+        # and the vendor answered (measured 2026-10-18):
+        #     spec.boot_disk.managed_disk.name: value is required
+        #     spec.boot_disk.managed_disk.spec: value is required
+        # i.e. it wants a NAMED disk wrapping its own spec, the same metadata/spec shape every
+        # other Nebius resource has. Named after the instance so a stray disk is traceable to the
+        # thing that made it.
+        disk_spec: Dict[str, object] = {
+            "type": str(spec.get("diskType") or spec.get("disk_type") or "NETWORK_SSD"),
+            "sizeGibibytes": str(int(spec.get("diskGib") or spec.get("disk_gib") or 128)),
+        }
+        if image_id:
+            disk_spec["sourceImageId"] = image_id
+        else:
+            disk_spec["sourceImageFamily"] = {"imageFamily": image_family}
+        disk: Dict[str, object] = {"name": f"{label}-boot", "spec": disk_spec}
+
+        body: Dict[str, object] = {
+            "metadata": {
+                "parentId": project,
+                # The CALLER's label, never the spec's. A provider that lets the spec's name
+                # through is the 2026-08-21 billing bug reintroduced: the wake cannot find what it
+                # started. Nebius spells the label `metadata.name`.
+                "name": label,
+            },
+            "spec": {
+                "resources": {"platform": platform, "preset": preset},
+                # managedDisk, so the vendor deletes it with the instance. See the docstring.
+                "bootDisk": {"attachMode": "READ_WRITE", "managedDisk": disk},
+                "networkInterfaces": [{"name": "eth0", "subnetId": subnet,
+                                       "ipAddress": {}}],
+            },
+        }
+        if spec.get("cloudInitUserData") or spec.get("cloud_init_user_data"):
+            body["spec"]["cloudInitUserData"] = str(          # type: ignore[index]
+                spec.get("cloudInitUserData") or spec.get("cloud_init_user_data"))
+        if spec.get("publicIp") or spec.get("public_ip"):
+            # An EXPLICIT opt-in. A public address is a cost and an exposure, and the node reaches
+            # the gateway outbound, so nothing here needs one by default.
+            body["spec"]["networkInterfaces"][0]["publicIpAddress"] = {}   # type: ignore[index]
+        if spec.get("serviceAccountId"):
+            body["spec"]["serviceAccountId"] = str(spec["serviceAccountId"])  # type: ignore[index]
+
+        headers = await self._headers()
+        if headers is None:
+            return False
+        try:
+            async with httpx.AsyncClient(timeout=90) as c:
+                r = await c.post(f"{self._BASE}{NEBIUS_INSTANCES_PATH}", headers=headers, json=body)
+        except Exception as e:
+            # AN AMBIGUOUS CREATE IS THE WORST OUTCOME IN THIS FILE — the 2026-09-17 orphan was a
+            # create that timed out, was concluded not to have happened, and was honoured
+            # afterwards. So this says so loudly enough for the reaper to be run.
+            log.error("nebius: create %r FAILED IN FLIGHT (%s). An instance may exist that nothing "
+                      "recorded — list the project before retrying.", label, type(e).__name__)
+            return False
+        if r.status_code >= 300:
+            log.error("nebius: create %r HTTP %s", label, r.status_code)
+            return False
+        return True
+
+    async def destroy(self, instance_id: str) -> bool:
+        """Terminate. 404 counts as success — already gone is the state we wanted.
+
+        TERMINATE NEVER STOP: this calls DELETE, and `/compute/v1/instances/stop` is never called
+        from this module at all. A stopped Nebius instance keeps its disks and keeps billing, which
+        is the same trap as a stopped RunPod pod keeping its slot.
+
+        NO VOLUME BOOKKEEPING IS NEEDED HERE, and that is a property of the create rather than an
+        omission: `create` always attaches a VM-MANAGED boot disk, which the vendor deletes with
+        the instance. A disk attached by hand, or an `existingDisk` someone configures later, would
+        survive. There is no volume sweep in this repo to fall back on (`volumes.py` is pure
+        policy, not an inventory), but the spec path that could introduce a standalone disk is not
+        reachable from `create` — it always attaches a managed one — so this is a gap only for a
+        disk somebody attaches by hand.
+        """
+        headers = await self._headers()
+        if headers is None:
+            return False
+        try:
+            async with httpx.AsyncClient(timeout=60) as c:
+                r = await c.delete(
+                    f"{self._BASE}{NEBIUS_INSTANCES_PATH}/{_urlquote(str(instance_id))}",
+                    headers=headers)
+        except Exception as e:
+            log.error("nebius: delete %s failed (%s) — reporting False so the caller looks, "
+                      "rather than a teardown that did not happen", instance_id, type(e).__name__)
+            return False
+        return r.status_code < 300 or r.status_code == 404
+
+
+# ---- Alibaba Cloud ECS, INTERNATIONAL only (28 §A, 2026-10-12) -----------------------------
+#
+# PRC-INCORPORATED, SO IT IS REGION-LOCKED BY CONSTRUCTION. The seed row carries
+# `region_locked: true` and `regions: [ap-southeast]`, and `providers.eligible()` therefore excludes
+# it from every EU/UK/US launch AND from every launch whose region is unstated. That second half is
+# the one that needed fixing: `eligible()` skips region narrowing entirely when no region is given
+# (the warm pool reconciles that way by design), so `regions` alone left this provider eligible for
+# any unlabelled job. "Unstated" is not "permitted" — see `ProviderRow.region_locked`.
+#
+# TARGET IS ALIBABA CLOUD INTERNATIONAL, not mainland China: `ecs.ap-southeast-1.aliyuncs.com`
+# (Singapore), verified against the regional endpoint list 2026-10-12. The credential is a RAM
+# user's, never the root account's, and it is read through `_provider_credential` like every other.
+#
+# TERMINATE, NEVER STOP — AND THE API MAKES THAT A DELIBERATE CHOICE. `DeleteInstance` with
+# `Force=false` REQUIRES the instance to be in the Stopped state first, and a stopped-but-unreleased
+# ECS instance still bills for its disks. So this adapter always passes `Force=true`, which releases
+# a RUNNING instance directly and never calls `StopInstance` at all — there is no code path here
+# that stops anything, and `test_alibaba_provider.py` asserts the string is absent from the module.
+# Alibaba's own wording: "After an instance is released, all physical resources used by the instance
+# are reclaimed."
+#
+# TWO BILLING LEAKS THE DOCS NAME, both closed at create time rather than hoped about:
+#   * a disk with `DeleteWithInstance=false` survives the instance as a pay-as-you-go disk, so the
+#     spec's system disk is never allowed to set it false;
+#   * an EIP is NOT released with the instance, so no public IP is allocated
+#     (`InternetMaxBandwidthOut=0`) and there is nothing left behind to release separately.
+#
+# THE SPEC COMES FROM THE OPERATOR, like `RUNPOD_POD_SPEC`: image, instance type, security group and
+# vSwitch are the decisions that cost money and pick hardware, and a provider that guesses them
+# deploys the wrong machine and bills for it (the 2026-09-24 `VAST_POD_SPEC` ruling). `create`
+# refuses without them rather than inventing a gn-series type.
+ALIBABA_ENDPOINT = envvar("ALIBABA_ENDPOINT", "ecs.ap-southeast-1.aliyuncs.com").strip()
+ALIBABA_REGION_ID = envvar("ALIBABA_REGION_ID", "ap-southeast-1").strip()
+#: ECS API version, from the operation reference (`api-ecs-2014-05-26-*`).
+ALIBABA_API_VERSION = "2014-05-26"
+#: SHA-256 of the empty body, which every GET/RPC call here sends. Named because it appears in both
+#: the canonical request and the `x-acs-content-sha256` header and the two must agree.
+_EMPTY_SHA256 = "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
+
+
+def _alibaba_spec() -> dict:
+    """The operator's launch spec as JSON, or `{}` when unset."""
+    raw = (envvar("ALIBABA_ECS_SPEC", "") or "").strip()
+    if not raw:
+        return {}
+    try:
+        spec = json.loads(raw)
+    except Exception:
+        log.error("ALIBABA_ECS_SPEC is not valid JSON — refusing to launch on a half-read spec")
+        return {}
+    return spec if isinstance(spec, dict) else {}
+
+
+def alibaba_signature(method: str, params: Dict[str, str], *, access_key_id: str,
+                      access_key_secret: str, host: str, action: str, nonce: str,
+                      date: str) -> Dict[str, str]:
+    """Sign an RPC-style request with ACS3-HMAC-SHA256 and return the headers to send.
+
+    A PURE FUNCTION, deliberately: it takes the credential rather than reading it, so the signer can
+    be tested against a known vector without a key in the environment and without a network call.
+    The algorithm is from Alibaba's own V3 request-structure reference (read 2026-10-12):
+
+      canonical request = METHOD \n CanonicalURI \n CanonicalQueryString \n CanonicalHeaders \n
+                          SignedHeaders \n HashedPayload
+      string to sign    = "ACS3-HMAC-SHA256" \n hex(sha256(canonical request))
+      signature         = hex(hmac_sha256(secret, string to sign))
+      Authorization     = ACS3-HMAC-SHA256 Credential=<id>,SignedHeaders=<h>,Signature=<sig>
+
+    CanonicalURI is "/" for RPC APIs, which every ECS operation used here is. Query parameters are
+    sorted by name and encoded per RFC 3986 with `*` as %2A, space as %20 and `~` left alone —
+    `quote(safe="-_.~")` gives exactly that, and getting it wrong is a 403 that reads like a bad key.
+    """
+    canonical_query = "&".join(
+        f"{_urlquote(k, safe='-_.~')}={_urlquote(str(v), safe='-_.~')}"
+        for k, v in sorted(params.items()))
+    headers = {
+        "host": host,
+        "x-acs-action": action,
+        "x-acs-content-sha256": _EMPTY_SHA256,
+        "x-acs-date": date,
+        "x-acs-signature-nonce": nonce,
+        "x-acs-version": ALIBABA_API_VERSION,
+    }
+    signed_names = sorted(headers)
+    canonical_headers = "".join(f"{n}:{headers[n].strip()}\n" for n in signed_names)
+    signed_headers = ";".join(signed_names)
+    canonical_request = "\n".join([
+        method.upper(), "/", canonical_query, canonical_headers, signed_headers, _EMPTY_SHA256,
+    ])
+    string_to_sign = "ACS3-HMAC-SHA256\n" + hashlib.sha256(
+        canonical_request.encode()).hexdigest()
+    signature = hmac.new(access_key_secret.encode(), string_to_sign.encode(),
+                         hashlib.sha256).hexdigest()
+    return {
+        **headers,
+        "Authorization": (f"ACS3-HMAC-SHA256 Credential={access_key_id},"
+                          f"SignedHeaders={signed_headers},Signature={signature}"),
+    }
+
+
+class AlibabaProvider:
+    """Alibaba Cloud ECS (gn-series GPU), international regions only.
+
+    `region_locked` in the seed row is what keeps it out of EU/UK/US and unlabelled work; this class
+    does not re-implement that gate, for the reason `providers.eligible` gives — one filter, in one
+    place, or the two spellings drift.
+    """
+
+    name = "alibaba"
+
+    #: ECS reports `Status` per instance (Running / Stopped / Starting / Stopping / Pending), so this
+    #: provider CAN tell serving from merely existing — and must, because a Stopped instance still
+    #: bills for its disks. Declared True, and both enumerations are implemented below; declaring it
+    #: and not implementing them is what `test_gpuproviders.py`'s contract test refuses.
+    DISTINGUISHES_SERVING = True
+
+    #: Statuses that are NOT serving but ARE still billing. The same distinction Vast's `exited`
+    #: taught: "not serving" and "not billing" are different facts and one list cannot answer both.
+    _NOT_SERVING = frozenset({"stopped", "stopping", "pending", "starting"})
+
+    def _key(self) -> "tuple[str, str]":
+        return (_provider_credential("alibaba", "ALIBABA_CLOUD_ACCESS_KEY_ID"),
+                _provider_credential("alibaba", "ALIBABA_CLOUD_ACCESS_KEY_SECRET"))
+
+    def configured(self) -> bool:
+        """BOTH halves of the credential AND an operator spec. An access key id with no secret is
+        not a credential, and either one alone reporting `configured: true` is how a provider wins a
+        race it cannot start."""
+        kid, secret = self._key()
+        return bool(kid and secret and _alibaba_spec())
+
+    def _headers(self, action: str, params: Dict[str, str]) -> dict:
+        kid, secret = self._key()
+        return alibaba_signature(
+            "GET", params, access_key_id=kid, access_key_secret=secret,
+            host=ALIBABA_ENDPOINT, action=action,
+            nonce=uuid.uuid4().hex,
+            date=time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()))
+
+    async def _call(self, action: str, params: Dict[str, str]) -> dict:
+        """One signed RPC call. `{}` on any failure — a provider that cannot be read is skipped by
+        the race, never treated as empty-and-therefore-idle."""
+        kid, secret = self._key()
+        if not (kid and secret):
+            return {}
+        q = {"RegionId": ALIBABA_REGION_ID, **params}
+        headers = self._headers(action, q)
+        async with httpx.AsyncClient(timeout=30) as c:
+            r = await c.get(f"https://{ALIBABA_ENDPOINT}/", headers=headers, params=q)
+            if r.status_code >= 300:
+                # The STATUS and the action, never the body: an Alibaba error echoes the request,
+                # and this is the kind of line that ends up pasted into an issue.
+                log.warning("alibaba %s: HTTP %s", action, r.status_code)
+                return {}
+            try:
+                return r.json() or {}
+            except Exception:
+                return {}
+
+    async def _listed(self, label: str) -> List[dict]:
+        """Every instance whose name carries this label, in WHATEVER state.
+
+        Raw and unfiltered, like Vast's `_labelled`: which statuses count is the CALLER's question,
+        and a pre-filtered list is what hid a paid-for instance from the census and the teardown at
+        the same time.
+        """
+        data = await self._call("DescribeInstances",
+                                {"InstanceName": label, "MaxResults": "100"})
+        return list(((data.get("Instances") or {}).get("Instance")) or [])
+
+    async def find(self, label: str) -> List[Instance]:
+        return await self.find_live(label)
+
+    async def find_live(self, label: str) -> List[Instance]:
+        """CAPACITY: Running only. A Stopped instance serves nothing, and counting it would let it
+        hold the pool's only slot and block its own replacement."""
+        return [Instance(id=str(i.get("InstanceId") or ""), label=label)
+                for i in await self._listed(label)
+                if str(i.get("Status", "")).lower() not in self._NOT_SERVING]
+
+    async def find_all(self, label: str) -> List[Instance]:
+        """TEARDOWN breadth: everything ECS still lists, Stopped included — because a stopped
+        instance still bills for its disks, which is exactly the leak `destroy` exists to close."""
+        return [Instance(id=str(i.get("InstanceId") or ""), label=label)
+                for i in await self._listed(label)]
+
+    async def create(self, label: str, spec: dict) -> "dict | bool":
+        """RunInstances. REFUSES without an operator spec rather than inventing hardware."""
+        base = _alibaba_spec()
+        if not base:
+            raise RuntimeError(
+                "alibaba: no launch spec — set FRUTEBOX_ALIBABA_ECS_SPEC to a JSON object with at "
+                "least ImageId, InstanceType, SecurityGroupId and VSwitchId. Refusing to guess an "
+                "instance type for a provider that bills.")
+        kid, secret = self._key()
+        if not (kid and secret):
+            return False
+        params = {
+            "InstanceName": label,          # the caller's label, never the spec's
+            "Amount": "1",
+            # NO PUBLIC IP. An EIP is not released with the instance, so allocating one leaves a
+            # billable resource behind that teardown cannot see.
+            "InternetMaxBandwidthOut": "0",
+            **{k: str(v) for k, v in base.items() if k != "InstanceName"},
+            # LAST, so a spec cannot turn it off: a system disk kept past the instance becomes a
+            # pay-as-you-go disk that nothing in this codebase is looking for.
+            "SystemDisk.DeleteWithInstance": "true",
+        }
+        data = await self._call("RunInstances", params)
+        ids = list((data.get("InstanceIdSets") or {}).get("InstanceIdSet") or [])
+        if not ids:
+            return False
+        return {"id": str(ids[0]), "name": label}
+
+    async def destroy(self, instance_id: str) -> bool:
+        """DeleteInstance with `Force=true` — release a RUNNING instance directly.
+
+        THE FORCE FLAG IS THE WHOLE POINT. With `Force=false` Alibaba requires the instance to be
+        Stopped first, which would mean calling `StopInstance` — and a stopped-but-unreleased ECS
+        instance still bills for its disks. So this never stops anything; it releases, and Alibaba
+        reclaims the physical resources.
+        """
+        data = await self._call("DeleteInstance",
+                                {"InstanceId": str(instance_id), "Force": "true"})
+        # A successful RPC returns a RequestId. `{}` is the failure shape from `_call`.
+        return bool(data.get("RequestId"))
+
+
+# ---- Phala (the TEE lane's confidential-compute provider, plan 08 / 28 §A3) -----------------
+#
+# ITS OWN ADAPTER AND ITS OWN SPEC, never borrowed. The 2026-09-24 ruling on `VAST_POD_SPEC` is the
+# reason: "a provider that borrows another's spec deploys the wrong machine and bills for it." A TEE
+# provider borrowing a GPU provider's spec would be that failure with an attestation claim on top.
+#
+# THE API SHAPE, now from Phala's own OpenAPI rather than from guesswork (read 2026-10-07, and the base
+# supplied by the owner the same day). Every one of these is quoted from the spec embedded in
+# `docs.phala.com/api-reference/cvms/*`:
+#
+#     POST   /api/v1/cvms/provision      provision-dstack-app   -> caches the compose, returns compose_hash
+#     POST   /api/v1/cvms                create-cvm-from-provision (the COMMIT) -> requires app_id + compose_hash
+#     GET    /api/v1/cvms                list-cvms
+#     DELETE /api/v1/cvms/{cvm_id}       delete-cvm             -> id in the PATH, not the body
+#
+# Authentication is the header `X-API-Key`. The earlier revision of this class refused to act because the
+# paths were unconfirmed; they are confirmed now, so the defaults below are real and no operator
+# configuration is needed to reach the API. The override survives because the base is the one thing that
+# has already been wrong twice: the registry row said `api.phala.network` (an API that is not there) and
+# `cloud.phala.com` is the DASHBOARD. Phala's own SDK calls this override `PHALA_CLOUD_API_PREFIX`.
+#
+# `configured()` STILL REQUIRES BOTH a credential and a known shape. That is unchanged on purpose: it is
+# what stops an operator who blanks the base from having a provider that reports ready and cannot call
+# anything.
+PHALA_BASE = envvar("PHALA_API_BASE", "https://cloud-api.phala.com/api/v1").rstrip("/")
+#: `provision,commit,list,delete` — relative to `PHALA_BASE`, in that order. `{cvm_id}` is substituted.
+PHALA_PATHS = [p.strip() for p in
+               envvar("PHALA_PATHS", "/cvms/provision,/cvms,/cvms,/cvms/{cvm_id}").split(",")
+               if p.strip()]
+
+
+class PhalaProvider:
+    """Phala confidential VMs, through the same `GpuProvider` protocol as every other backend.
+
+    `class: tee` in `registry/providers.yaml`, so §A4's class gate keeps it out of the GPU race whatever
+    the warm-pool allow-list says, and the §16 lane toggle (`FRUTEBOX_TEE_LANE`, default OFF) keeps the
+    whole lane unreachable until an operator asks for it. Attestation does NOT go through our verifier:
+    `tee.DIRECT_NRAS_PROVIDERS` already lists `phala`, so its evidence goes straight to NVIDIA's NRAS.
+    """
+
+    name = "phala"
+
+    #: Phala answers one question about an instance: is it listed. It cannot distinguish a CVM that is
+    #: SERVING from one that merely exists, so the ambiguity is declared rather than discovered — the
+    #: same declaration DataCrunch makes, and `nodewake` resolves it toward suspected_billing.
+    DISTINGUISHES_SERVING = False
+
+    def _key(self) -> str:
+        return _provider_credential("phala", "PHALA_API_KEY")
+
+    def _shape_known(self) -> bool:
+        """Is the API shape confirmed? Four paths and a base, or nothing."""
+        return bool(PHALA_BASE) and len(PHALA_PATHS) == 4
+
+    def configured(self) -> bool:
+        """A credential AND a confirmed API shape. A key alone is not the ability to call anything, and
+        reporting `True` on a key alone is how a provider wins a race it cannot serve."""
+        return bool(self._key()) and self._shape_known()
+
+    def _headers(self) -> dict:
+        return {"X-API-Key": self._key(), "content-type": "application/json"}
+
+    def _path(self, which: str) -> str:
+        order = ("provision", "commit", "list", "delete")
+        return f"{PHALA_BASE}{PHALA_PATHS[order.index(which)]}"
+
+    async def _labelled(self, label: str) -> List[dict]:
+        if not self.configured():
+            return []
+        async with httpx.AsyncClient(timeout=30) as c:
+            r = await c.get(self._path("list"), headers=self._headers())
+            if r.status_code >= 300:
+                return []
+            body = r.json() or {}
+            rows = body if isinstance(body, list) else (body.get("items") or body.get("data") or [])
+            return [i for i in rows if str(i.get("name") or i.get("app_name") or "") == label]
+
+    async def find(self, label: str) -> List[Instance]:
+        """THE ONE ENUMERATION THIS API GIVES, and deliberately the only one implemented.
+
+        No `find_live` and no `find_all`: `DISTINGUISHES_SERVING = False` says this provider cannot tell a
+        CVM that is SERVING from one that merely exists, and the module-level `find_live`/`find_all` already
+        fall back to this single question for exactly that case. Implementing both here would contradict the
+        declaration — `test_a_provider_that_cannot_answer_BOTH_questions_must_declare_it` catches precisely
+        that, because a declaration the code does not back up tells callers something untrue — and it would
+        duplicate a fallback the dispatch layer owns. DataCrunch has the same shape for the same reason.
+        """
+        return [{"id": str(i.get("app_id") or i.get("id") or ""), "name": label,
+                 "status": str(i.get("status") or "")}
+                for i in await self._labelled(label)]
+
+    async def create(self, label: str, spec: dict) -> "dict | bool":
+        """Provision, then commit — Phala's two-phase deployment, which is why this is not one POST.
+
+        REFUSES rather than guesses when the API shape is unconfirmed. A create that posts to an invented
+        path either 404s (a confusing failure) or, worse, succeeds against something unintended.
+        """
+        if not self._shape_known():
+            raise RuntimeError(
+                "phala: API shape not configured — set FRUTEBOX_PHALA_API_BASE and FRUTEBOX_PHALA_PATHS "
+                "(provision,commit,list,delete) from Phala's API reference. Refusing to guess endpoint "
+                "paths for a provider that bills.")
+        if not self._key():
+            return False
+        body = dict(spec or {})
+        body.setdefault("name", label)
+        async with httpx.AsyncClient(timeout=120) as c:
+            pr = await c.post(self._path("provision"), headers=self._headers(), json=body)
+            if pr.status_code >= 300:
+                return False
+            prov = pr.json() or {}
+            # THE COMMIT'S REQUIRED PAIR, per `create-cvm-from-provision`: `app_id` and `compose_hash`.
+            #
+            # `app_env_encrypt_pubkey` is deliberately NOT sent. It is a provision OUTPUT — the key an
+            # operator encrypts environment variables WITH, producing the optional `encrypted_env` — not a
+            # commit field. Sending it would be inventing a parameter the spec does not have. It is carried
+            # back to the caller instead, so whoever adds env encryption has it; this class does not
+            # encrypt anything, and pretending otherwise would be worse than the gap.
+            commit = {"app_id": prov.get("app_id") or body.get("app_id"),
+                      "compose_hash": prov.get("compose_hash")}
+            cr = await c.post(self._path("commit"), headers=self._headers(), json=commit)
+            if cr.status_code >= 300:
+                return False
+            made = cr.json() or {}
+        return {"id": str(made.get("id") or made.get("vm_uuid") or made.get("app_id") or ""),
+                "name": label,
+                # For whoever adds environment encryption: this is what it is encrypted WITH.
+                "app_env_encrypt_pubkey": prov.get("app_env_encrypt_pubkey")}
+
+    async def destroy(self, instance_id: str) -> bool:
+        """`DELETE /cvms/{cvm_id}` — the id is a PATH parameter, not a body field.
+
+        An earlier revision of this sent `{"app_id": ...}` as a DELETE body, which the spec does not
+        describe: it would have deleted nothing and reported success on whatever the base path answered.
+        `destroy_verified` in the dispatch layer is what would have caught it in the end, by re-reading the
+        listing — but a teardown that silently deletes the wrong thing is not a thing to leave to a backstop.
+        """
+        if not self._shape_known():
+            return False
+        url = self._path("delete").replace("{cvm_id}", str(instance_id))
+        async with httpx.AsyncClient(timeout=60) as c:
+            r = await c.request("DELETE", url, headers=self._headers())
+        return r.status_code < 300 or r.status_code == 404
+
+
+async def derive_lambda_launch(api_key: Optional[str] = None, *,
+                               instance_type: str = "") -> Dict[str, str]:
+    """28 §A5 — discover Lambda's account-scoped launch details FROM the key.
+
+    OPTION 1 SHAPE (owner ruling 2026-09-22), the same as RunPod's: the operator makes the
+    decision that costs money — here `LAMBDA_INSTANCE_TYPE`, which `create` already refuses to
+    launch without — and the code discovers the account-scoped consequences of it. This NEVER
+    chooses an instance type.
+
+    WHAT IT FIXES. `create` falls back to `region_name="us-west-1"` when `LAMBDA_REGION` is
+    unset. That is the same defect class as pairing volume X's id with volume Y's datacenter:
+    an instance type that has capacity only in `us-east-1` is launched into `us-west-1` and
+    fails — and a region and a list of SSH key names are account RESOURCES, exactly the thing
+    §A5 says a person should not be copying out of a console.
+
+    Returns {} rather than raising: a missing derivation is a launch that proceeds on whatever
+    the operator did set, not a reason to refuse to provision.
+    """
+    key = api_key or _provider_credential("lambda", "LAMBDA_API_KEY")
+    if not key or not instance_type:
+        return {}
+    base, headers = LambdaProvider._BASE, {"Authorization": f"Bearer {key}"}
+    out: Dict[str, str] = {}
+    try:
+        async with httpx.AsyncClient(timeout=20.0) as client:
+            types = await client.get(f"{base}/instance-types", headers=headers)
+            keys = await client.get(f"{base}/ssh-keys", headers=headers)
+    except Exception:
+        return {}
+
+    # Shapes are read DEFENSIVELY — every lookup tolerates a missing key and an unexpected
+    # container — because this has not been run against a live Lambda account and a wrong guess
+    # here must degrade to {} rather than to a confident wrong region.
+    try:
+        if types.status_code == 200:
+            data = (types.json() or {}).get("data") or {}
+            entry = data.get(instance_type) if isinstance(data, dict) else None
+            regions = (entry or {}).get("regions_with_capacity_available") or []
+            names = [str(r.get("name")) for r in regions if isinstance(r, dict) and r.get("name")]
+            if names:
+                # First with capacity. Not a cost choice — Lambda prices an instance type the
+                # same everywhere; this only answers "where can it actually start".
+                out["LAMBDA_REGION"] = names[0]
+    except Exception:
+        pass
+    try:
+        if keys.status_code == 200:
+            rows = (keys.json() or {}).get("data") or []
+            names = [str(k.get("name")) for k in rows if isinstance(k, dict) and k.get("name")]
+            if names:
+                out["LAMBDA_SSH_KEYS"] = ",".join(names)
+    except Exception:
+        pass
+    return out
+
+
+async def derive_runpod_volume(api_key: Optional[str] = None, *,
+                               volume_id: str = "") -> Dict[str, str]:
+    """28 §A5 — discover RunPod's account-scoped volume ids FROM the key.
+
+    The owner supplies a credential; the code discovers the rest. A network volume id and its
+    datacenter are account RESOURCES, not secrets, and asking a person to copy them out of a
+    console is how they end up wrong — pointing a pod at a volume in another region fails at
+    launch, after the GPU is already billing.
+
+    Lives here because this is the single RunPod door (KB §0): every RunPod call in the codebase
+    goes through this module, and `tests/test_gpu_single_door.py` fails if one appears
+    elsewhere. Returns {} rather than raising — a missing volume is a slower cold start, not a
+    reason to refuse to provision.
+
+    PASS `volume_id` TO ASK ABOUT ONE SPECIFIC VOLUME. Without it this guesses — "seed" in the
+    name, else the largest — which is the right guess when nothing is known and the WRONG one
+    when the operator has already named a volume. Deriving a datacenter by heuristic and pairing
+    it with an id the operator chose is how volume X ends up pinned to volume Y's datacenter: a
+    launch that fails after the GPU is already billing. Asked about a specific volume, this
+    returns that volume's own datacenter or nothing at all.
+    """
+    key = api_key or _provider_credential("runpod", "RUNPOD_API_KEY")
+    if not key:
+        return {}
+    try:
+        async with httpx.AsyncClient(timeout=20.0) as client:
+            r = await client.get(
+                "https://rest.runpod.io/v1/networkvolumes",
+                headers={"Authorization": f"Bearer {key}"},
+            )
+        if r.status_code != 200:
+            return {}
+        payload = r.json()
+    except Exception:
+        return {}
+
+    volumes = payload if isinstance(payload, list) else (payload.get("data") or [])
+    if not volumes:
+        return {}
+
+    # The seeded-weights volume is the one worth using: it is what turns a ~94-minute cold
+    # download into a ~90-second load. Prefer it by name, else fall back to the largest, which is
+    # the only other defensible guess about which volume holds model weights.
+    if volume_id:
+        match = [v for v in volumes if str(v.get("id") or "") == volume_id]
+        if not match:
+            # The named volume is not in this account. Say nothing rather than guess: a wrong
+            # datacenter here is a failed launch, and silence leaves the API to infer it.
+            return {}
+        chosen = match[0]
+    else:
+        seeded = [v for v in volumes if "seed" in str(v.get("name", "")).lower()]
+        chosen = (seeded or sorted(volumes, key=lambda v: int(v.get("size") or 0), reverse=True))[0]
+    out = {}
+    if chosen.get("id"):
+        out["RUNPOD_NETWORK_VOLUME_ID"] = str(chosen["id"])
+    if chosen.get("dataCenterId"):
+        out["RUNPOD_VOLUME_DATACENTER"] = str(chosen["dataCenterId"])
+    return out
+
+
+PROVIDERS: Dict[str, GpuProvider] = {
+    # Phala is `class: tee` in `registry/providers.yaml`, so §A4's class gate keeps it out of the GPU
+    # race whatever the warm-pool allow-list says, and the §16 lane toggle keeps the lane unreachable
+    # by default. It is registered here so the capability query (`providers doctor`) can REPORT it: a
+    # provider missing from the registry does not report as broken, it does not report at all.
+    p.name: p for p in (RunPodProvider(), VastProvider(), LambdaProvider(),
+                        DataCrunchProvider(), PhalaProvider(), NebiusProvider(),
+                        # Registered so `providers doctor` can REPORT it. Its residency fence is the
+                        # seed row's `region_locked`, enforced in `providers.eligible` — not here,
+                        # and not twice.
+                        AlibabaProvider())  # type: ignore[misc]
+}
+
+
+def configured_providers() -> List[str]:
+    """Which providers this deployment can actually use. For ops and for honest errors."""
+    return [n for n, p in PROVIDERS.items() if p.configured()]
+
+
+# ---- ops CLI — so no shell script ever hand-rolls a RunPod call again ----------------------
+#
+# `scripts/bench_run.sh` used to carry its own curl to REST + a GraphQL podTerminate — an
+# UNVERIFIED terminate, the exact §3 wrong pattern, living in an ops script where no test looks.
+# Usage:  RUNPOD_API_KEY=... python -m frutebox.gpuproviders <list|stop-label LABEL [PROVIDER]|terminate POD_ID>
+
+def _cli() -> int:
+    import asyncio as _a
+    import sys
+
+    rp = PROVIDERS.get("runpod")
+    cmd = sys.argv[1] if len(sys.argv) > 1 else "list"
+    if cmd == "list":
+        # `_list_pods_or_none`, NOT `list_pods`. The difference is the whole point of this command.
+        #
+        # OBSERVED 2026-09-28 from the backend lane: with no resolvable credential this printed
+        # "0 pod(s)" and exited 0. That is the reading an operator takes to mean "the account is
+        # clean, nothing is billing" — and it is produced by the one condition under which we know
+        # nothing at all. `list_pods` flattens a transport or auth failure to `[]` by design
+        # (right for planning, where an empty answer means "plan for none"); a human asking what is
+        # on the account must be told the ask failed.
+        pods = _a.run(rp._list_pods_or_none())
+        if pods is None:
+            print("CANNOT ENUMERATE: no resolvable credential or the provider call failed. "
+                  "This is NOT 'no pods' — pods may be running and BILLING. Check the provider "
+                  "console.", file=sys.stderr)
+            return 3
+        for p in pods:
+            print(f"{p.get('id')}  {p.get('name')}  {p.get('desiredStatus')}  "
+                  f"runtime={'yes' if p.get('runtime') else 'no'}")
+        print(f"{len(pods)} pod(s)")
+        return 0
+    if cmd == "stop-label" and len(sys.argv) > 2:
+        # OPTIONAL PROVIDER, defaulting to runpod. Hand-terminating by label is what an operator
+        # is told to do when the wake path reports a suspected-billing instance
+        # (`nodewake._abandon_unconfirmed`), and that instance is on whichever provider won the
+        # race — which since merit order shipped is routinely not RunPod. A repair instruction
+        # that can only reach one provider is not a repair instruction.
+        target = PROVIDERS.get(sys.argv[3]) if len(sys.argv) > 3 else rp
+        if target is None:
+            print(f"unknown provider {sys.argv[3]!r}; known: {', '.join(sorted(PROVIDERS))}",
+                  file=sys.stderr)
+            return 2
+        res = _a.run(stop(target, sys.argv[2]))
+        print(res)
+        return 0 if res.get("ok") else 1
+    if cmd == "terminate" and len(sys.argv) > 2:
+        return 0 if _a.run(rp.terminate(sys.argv[2])) else 1
+    if cmd == "stop-all":
+        # OURS ONLY. This used to terminate EVERY pod on the account, and the account is SHARED
+        # with another project (owner, 2026-09-28) — so the bench script's cost-safety trap would
+        # have destroyed a third party's running work, from a `trap ... EXIT`, with no confirmation
+        # and no way to undo it. The reaper elsewhere in this file already refuses to touch names
+        # outside our scope for exactly this reason; this path predated that rule and never got it.
+        #
+        # `--everything` still exists because a genuine "kill absolutely all billing" exists as an
+        # intent — but it has to be ASKED FOR, out loud, and it prints what it is about to do.
+        everything = "--everything" in sys.argv[2:]
+        prefix = "frutebox-"
+
+        # AND THE LISTING ITSELF MUST BE HONEST. Built on `list_pods`, an unauthenticated or failed
+        # listing returned `[]`: the loop terminated nothing, the function returned True and the trap
+        # exited 0 — a successful teardown reported for an account it could not see. Scoping the
+        # sweep and knowing whether you can see the account are two different safety properties, and
+        # this command needs both: one bounds what it kills, the other bounds what it CLAIMS.
+        async def _all():
+            pods = await rp._list_pods_or_none()
+            if pods is None:
+                log.error("stop-all CANNOT LIST the account — nothing was terminated and NOTHING "
+                          "IS PROVEN STOPPED. Pods may still be BILLING.")
+                return False
+            ok = True
+            mine = [p for p in pods
+                    if everything or str(p.get("name") or "").startswith(prefix)]
+            skipped = len(pods) - len(mine)
+            if skipped:
+                print(f"leaving {skipped} pod(s) alone — not named {prefix}* "
+                      f"(shared account; use --everything to override)")
+            for pod in mine:
+                pid = str(pod.get("id") or "")
+                if pid:
+                    print(f"terminating {pid} {pod.get('name')!r}")
+                    ok = await rp.terminate(pid) and ok
+            return ok
+        return 0 if _a.run(_all()) else 1
+    if cmd == "availability":
+        # WHICH CARDS CAN ACTUALLY BE RENTED RIGHT NOW, and what they cost.
+        #
+        # Without this, finding capacity means ATTEMPTING a create per card, and every miss costs
+        # ~75s because RunPod's "no instances available" reply is ambiguous (a pod may have been
+        # created) so the provider reconciles against the live pod list before giving up. Eight
+        # combinations is ~10 minutes, which does not fit inside Cloud Run's 300s request cap —
+        # that is what made the fallback walk unusable on 2026-09-28.
+        #
+        # `lowestPrice` comes back null for a GPU with no stock, so this is a real availability
+        # signal and not just a price list. Read-only: it rents nothing.
+        async def _avail():
+            types = await rp.gpu_prices()
+            if not types:
+                print("no answer from the provider (credential missing or unreachable)",
+                      file=sys.stderr)
+                return 1
+            rows = []
+            for t in types:
+                lp = t.get("lowestPrice") or {}
+                rows.append((
+                    t.get("displayName") or t.get("id"),
+                    t.get("memoryInGb"),
+                    t.get("securePrice"),
+                    t.get("communityPrice"),
+                    lp.get("uninterruptablePrice"),
+                    lp.get("minimumBidPrice"),
+                ))
+            rows.sort(key=lambda r: (r[4] is None, r[4] if r[4] is not None else 9e9))
+            print(f"{'gpu':<28}{'vram':>6}{'secure':>9}{'comm':>9}"
+                  f"{'on-demand':>11}{'spot':>9}   available")
+            for name, vram, sec, comm, od, bid in rows:
+                avail = "YES" if (od or bid) else "no stock"
+                def f(x): return "-" if x is None else f"{x:g}"
+                print(f"{str(name):<28}{str(vram or '-'):>6}{f(sec):>9}{f(comm):>9}"
+                      f"{f(od):>11}{f(bid):>9}   {avail}")
+            return 0
+        return _a.run(_avail())
+
+    print("usage: python -m frutebox.gpuproviders "
+          "<list|availability|stop-label LABEL [PROVIDER]|terminate POD_ID|stop-all [--everything]>",
+          file=sys.stderr)
+    return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(_cli())