freesolo-flash-dev 0.2.35__tar.gz → 0.2.36__tar.gz

{freesolo_flash_dev-0.2.35 → freesolo_flash_dev-0.2.36}/Dockerfile.worker

@@ -63,7 +63,7 @@ RUN pip install --no-cache-dir \
     "tilelang==0.1.11" \
     "apache-tvm-ffi==0.1.11" \
     "hf_transfer" \
-    "freesolo>=0.2.52" \
+    "freesolo>=0.2.54" \
     "runpod"
 # Gated-DeltaNet (Qwen3.5/3.6) runs on flash-linear-attention's Triton kernels. On consumer cards
 # (Ampere/Ada/Blackwell) the Triton path is correct. On Hopper (sm90) fla's GDN chunk_bwd is

{freesolo_flash_dev-0.2.35 → freesolo_flash_dev-0.2.36}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: freesolo-flash-dev
-Version: 0.2.35
+Version: 0.2.36
 Summary: Flash — managed LoRA post-training (SFT/GRPO) for Freesolo environments, driven by the `flash` CLI
 Project-URL: Homepage, https://github.com/freesolo-co/flash
 Project-URL: Repository, https://github.com/freesolo-co/flash
@@ -18,7 +18,7 @@ Requires-Python: <3.13,>=3.11
 Provides-Extra: dev
 Requires-Dist: datasets>=2.19; extra == 'dev'
 Requires-Dist: fastapi; extra == 'dev'
-Requires-Dist: freesolo>=0.2.52; extra == 'dev'
+Requires-Dist: freesolo>=0.2.54; extra == 'dev'
 Requires-Dist: httpx>=0.27; extra == 'dev'
 Requires-Dist: huggingface-hub>=0.34; extra == 'dev'
 Requires-Dist: mypy>=1.13.0; extra == 'dev'
@@ -31,7 +31,7 @@ Provides-Extra: gpu
 Requires-Dist: accelerate>=1.4; extra == 'gpu'
 Requires-Dist: bitsandbytes>=0.49; extra == 'gpu'
 Requires-Dist: datasets>=2.19; extra == 'gpu'
-Requires-Dist: freesolo>=0.2.52; extra == 'gpu'
+Requires-Dist: freesolo>=0.2.54; extra == 'gpu'
 Requires-Dist: huggingface-hub>=0.34; extra == 'gpu'
 Requires-Dist: peft>=0.19; extra == 'gpu'
 Requires-Dist: torch==2.10.0; extra == 'gpu'
@@ -41,7 +41,7 @@ Requires-Dist: vllm==0.19.1; extra == 'gpu'
 Provides-Extra: server
 Requires-Dist: datasets>=2.19; extra == 'server'
 Requires-Dist: fastapi; extra == 'server'
-Requires-Dist: freesolo>=0.2.52; extra == 'server'
+Requires-Dist: freesolo>=0.2.54; extra == 'server'
 Requires-Dist: httpx>=0.27; extra == 'server'
 Requires-Dist: huggingface-hub>=0.34; extra == 'server'
 Requires-Dist: runpod-flash; extra == 'server'

{freesolo_flash_dev-0.2.35 → freesolo_flash_dev-0.2.36}/flash/catalog.py

@@ -116,11 +116,8 @@ class ModelInfo:
 DEFAULT_MODEL = "Qwen/Qwen3.5-4B"
 
 SERVING_FP8_MODEL_REPOS: dict[str, str] = {
-    "openbmb/MiniCPM5-1B": "Freesolo-Co/MiniCPM5-1B-FP8",
-    "Qwen/Qwen3.5-0.8B": "Freesolo-Co/Qwen3.5-0.8B-FP8",
-    "Qwen/Qwen3.5-2B": "Freesolo-Co/Qwen3.5-2B-FP8",
-    "Qwen/Qwen3.5-4B": "Freesolo-Co/Qwen3.5-4B-FP8",
-    "Qwen/Qwen3.5-9B": "Freesolo-Co/Qwen3.5-9B-FP8",
+    "Qwen/Qwen3.5-4B": "lovedheart/Qwen3.5-4B-FP8",
+    "Qwen/Qwen3.5-9B": "lovedheart/Qwen3.5-9B-FP8",
     "Qwen/Qwen3.6-35B-A3B": "Qwen/Qwen3.6-35B-A3B-FP8",
 }
 
@@ -136,9 +133,8 @@ MODELS: dict[str, ModelInfo] = {
         recommended_gpu="RTX 4090",
         serving=ServingCapacity(
             gpu="L4",
-            serve_model_id=SERVING_FP8_MODEL_REPOS["openbmb/MiniCPM5-1B"],
             max_loras=16,
-            max_lora_rank=128,
+            max_lora_rank=64,
             max_model_len=32768,
         ),
         thinking="hybrid",
@@ -155,9 +151,8 @@ MODELS: dict[str, ModelInfo] = {
         recommended_gpu="RTX 4090",
         serving=ServingCapacity(
             gpu="L4",
-            serve_model_id=SERVING_FP8_MODEL_REPOS["Qwen/Qwen3.5-0.8B"],
             max_loras=16,
-            max_lora_rank=128,
+            max_lora_rank=64,
             max_model_len=32768,
         ),
         thinking="hybrid",
@@ -174,9 +169,8 @@ MODELS: dict[str, ModelInfo] = {
         recommended_gpu="RTX 4090",
         serving=ServingCapacity(
             gpu="L4",
-            serve_model_id=SERVING_FP8_MODEL_REPOS["Qwen/Qwen3.5-2B"],
             max_loras=16,
-            max_lora_rank=128,
+            max_lora_rank=64,
             max_model_len=32768,
         ),
         thinking="hybrid",
@@ -191,10 +185,10 @@ MODELS: dict[str, ModelInfo] = {
         min_vram_gb=32,
         recommended_gpu="RTX 5090",
         serving=ServingCapacity(
-            gpu="L40S",
+            gpu="L4",
             serve_model_id=SERVING_FP8_MODEL_REPOS["Qwen/Qwen3.5-4B"],
             max_loras=64,
-            max_lora_rank=64,
+            max_lora_rank=32,
             max_model_len=8192,
             max_num_seqs=8,
             gpu_memory_utilization=0.98,
@@ -216,10 +210,10 @@ MODELS: dict[str, ModelInfo] = {
         quant="bf16",
         recommended_gpu="A100 PCIe",
         serving=ServingCapacity(
-            gpu="L40S",
+            gpu="L4",
             serve_model_id=SERVING_FP8_MODEL_REPOS["Qwen/Qwen3.5-9B"],
             max_loras=44,
-            max_lora_rank=64,
+            max_lora_rank=32,
             max_model_len=8192,
             max_num_seqs=8,
             gpu_memory_utilization=0.98,
@@ -254,14 +248,13 @@ MODELS: dict[str, ModelInfo] = {
         quant="bf16",
         recommended_gpu="H200",
         serving=ServingCapacity(
-            gpu="A100-80GB:2",
+            gpu="A100-80GB",
             serve_model_id=SERVING_FP8_MODEL_REPOS["Qwen/Qwen3.6-35B-A3B"],
             max_loras=12,
-            max_lora_rank=64,
+            max_lora_rank=32,
             max_model_len=8192,
             max_num_seqs=8,
             max_num_batched_tokens=4096,
-            tensor_parallel_size=2,
             gpu_memory_utilization=0.98,
         ),
         thinking="hybrid",
@@ -292,8 +285,8 @@ def get_model(model_id: str) -> ModelInfo:
 def serving_lora_rank_cap(model: str | ModelInfo | None) -> int | None:
     """Return the model's serving LoRA rank cap, or None when Flash has no local cap.
 
-    Serving capacity is model-specific: small serving models currently allow rank 128, while larger
-    serving paths currently allow rank 64. Unknown/open-policy models intentionally return None instead
+    Serving capacity is model-specific: small serving models currently allow rank 64, while larger
+    serving paths currently allow rank 32. Unknown/open-policy models intentionally return None instead
     of inheriting a global fallback.
     """
     if isinstance(model, ModelInfo):

{freesolo_flash_dev-0.2.35 → freesolo_flash_dev-0.2.36}/flash/cli/commands.py

@@ -594,10 +594,17 @@ def cmd_deploy(args) -> int:
             print(render.arrow(url_note) if render.styled() else f"note: {url_note}", file=sys.stderr)
     if dep.get("state") != "dry_run":
         state = dep.get("state", "deploying")
-        status_note = (
-            f"deployment state is {state!r}; run `flash deployments` to check progress "
-            "and use `flash chat` once it is ready."
-        )
+        if state == "failed":
+            detail = str(dep.get("error") or dep.get("detail") or "unknown error")
+            status_note = (
+                f"deployment failed: {detail}; run `flash deployments` for details and "
+                f"retry `flash deploy {args.run_id}` after fixing the error."
+            )
+        else:
+            status_note = (
+                f"deployment state is {state!r}; run `flash deployments` to check progress "
+                "and use `flash chat` once it is ready."
+            )
         print(
             render.arrow(status_note) if render.styled() else f"note: {status_note}",
             file=sys.stderr,
@@ -608,7 +615,7 @@ def cmd_deploy(args) -> int:
                 render.arrow(skip_note) if render.styled() else f"note: {skip_note}",
                 file=sys.stderr,
             )
-    return 0
+    return 1 if dep.get("state") == "failed" else 0
 
 
 def cmd_export(args) -> int:
@@ -678,6 +685,17 @@ def cmd_deployments(args) -> int:
 
 
 def cmd_chat(args) -> int:
+    from flash.schema import parse_checkpoint_ref
+
+    parsed = parse_checkpoint_ref(args.run_id)
+    if parsed is None:
+        print(
+            f"invalid run/checkpoint reference {args.run_id!r} "
+            "(expected <run_id> or <run_id>/step-N)",
+            file=sys.stderr,
+        )
+        return 1
+    base_run_id, _step = parsed
     client = client_from_config()
     messages = [{"role": "user", "content": args.message}]
     system = getattr(args, "system", None)
@@ -689,7 +707,7 @@ def cmd_chat(args) -> int:
     if stream is not None:
         wrote = False
         for chunk in stream(
-            args.run_id,
+            base_run_id,
             messages=messages,
             temperature=args.temperature,
             max_tokens=args.max_tokens,
@@ -701,7 +719,7 @@ def cmd_chat(args) -> int:
         return 0
 
     resp = client.chat(
-        args.run_id,
+        base_run_id,
         messages=messages,
         temperature=args.temperature,
         max_tokens=args.max_tokens,

{freesolo_flash_dev-0.2.35 → freesolo_flash_dev-0.2.36}/flash/client/http.py

@@ -301,10 +301,18 @@ class ApiClient:
         max_tokens: int = 512,
         timeout: float | None = None,
     ) -> dict:
+        from flash.schema import parse_checkpoint_ref
+
+        parsed = parse_checkpoint_ref(run_id)
+        if parsed is None:
+            raise ClientError(
+                "invalid run id: expected RUN_ID or RUN_ID/step-N for a deployed checkpoint"
+            )
+        base_run_id, _step = parsed
         _validate_chat_messages(messages)
         return self._request(
             "POST",
-            f"/v1/runs/{run_id}/chat",
+            f"/v1/runs/{base_run_id}/chat",
             body={"messages": messages, "temperature": temperature, "max_tokens": max_tokens},
             timeout=timeout if timeout is not None else 30 * 60,
         )
@@ -316,12 +324,20 @@ class ApiClient:
         temperature: float = 0.0,
         max_tokens: int = 512,
     ) -> Iterator[str]:
+        from flash.schema import parse_checkpoint_ref
+
+        parsed = parse_checkpoint_ref(run_id)
+        if parsed is None:
+            raise ClientError(
+                "invalid run id: expected RUN_ID or RUN_ID/step-N for a deployed checkpoint"
+            )
+        base_run_id, _step = parsed
         _validate_chat_messages(messages)
         headers = {"Content-Type": "application/json"}
         if self.api_key:
             headers["Authorization"] = f"Bearer {self.api_key}"
         req = urllib.request.Request(
-            f"{self.api_url}/v1/runs/{run_id}/chat",
+            f"{self.api_url}/v1/runs/{base_run_id}/chat",
             method="POST",
             data=json.dumps(
                 {

{freesolo_flash_dev-0.2.35 → freesolo_flash_dev-0.2.36}/flash/engine/worker/perf/__init__.py

@@ -14,8 +14,6 @@ import contextlib
 import os
 import sys
 
-# back-compat re-export from flash.engine.vram
-from flash.engine.vram import _LIGER_LONG_CTX_TOKENS, _LIGER_MIN_PARAMS_B
 from flash.engine.worker.perf.attn import (
     _attn_impl_for_capability,
     _flash_attn_3_available,
@@ -323,9 +321,7 @@ def _ensure_fla_fastpath_on_hopper() -> None:
 
 __all__ = [
     "RETRIABLE_INFRA_MARKER",
-    "_LIGER_LONG_CTX_TOKENS",
     "_LIGER_MIN_PARAMS",
-    "_LIGER_MIN_PARAMS_B",
     "_LONG_CONTEXT_TOKENS",
     "RetriableInfraError",
     "_GpuPeakSampler",

{freesolo_flash_dev-0.2.35 → freesolo_flash_dev-0.2.36}/flash/envs/registry.py

@@ -4,7 +4,7 @@ from __future__ import annotations
 
 from .base import Environment
 
-FREESOLO_WORKER_SPEC = "freesolo>=0.2.52"
+FREESOLO_WORKER_SPEC = "freesolo>=0.2.54"
 
 
 def worker_pip_for_env(env_id: str) -> list[str]:

freesolo_flash_dev-0.2.36/flash/lora_rank.py

@@ -0,0 +1,193 @@
+"""LoRA adapter rank parsing and control-plane preflight helpers."""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Callable, Mapping
+from typing import TYPE_CHECKING, Any
+
+from flash.catalog import serving_lora_rank_cap
+
+if TYPE_CHECKING:
+    from flash.spec import JobSpec
+
+_VL_WARMSTART_RECOMBINE_PREFIXES = ("Qwen/Qwen3.5-", "Qwen/Qwen3.6-")
+
+AdapterConfigLoader = Callable[[str, str | None], Mapping[str, Any]]
+
+
+def resolve_adapter_ref(adapter_ref: str) -> tuple[str, str] | None:
+    """Resolve an internal storage ref into ``(repo, artifact_prefix)``."""
+    from flash.schema import parse_adapter_storage_ref
+
+    return parse_adapter_storage_ref(adapter_ref)
+
+
+def adapter_config_path_from_ref(adapter_ref: str) -> tuple[str, str]:
+    resolved = resolve_adapter_ref(adapter_ref)
+    if resolved is None:
+        raise ValueError(
+            "train.init_from_adapter could not be resolved to an internal adapter storage ref"
+        )
+    repo, prefix = resolved
+    return repo, f"{prefix}/adapter/adapter_config.json"
+
+
+def _positive_int(value: Any, *, source: str, field: str) -> int:
+    if isinstance(value, bool):
+        raise ValueError(
+            f"could not verify adapter rank: {source} has invalid rank metadata ({field})"
+        )
+    try:
+        rank = int(value)
+    except (TypeError, ValueError) as exc:
+        raise ValueError(
+            f"could not verify adapter rank: {source} has invalid rank metadata ({field})"
+        ) from exc
+    if rank <= 0:
+        raise ValueError(f"could not verify adapter rank: {source} has non-positive rank {rank}")
+    return rank
+
+
+def rank_from_adapter_config(config: Mapping[str, Any], *, source: str) -> int:
+    """Return the max LoRA rank advertised by PEFT adapter metadata."""
+    if not isinstance(config, Mapping):
+        raise ValueError(f"could not verify adapter rank: {source} is not a JSON object")
+    ranks: list[int] = []
+    if config.get("r") is not None:
+        ranks.append(_positive_int(config["r"], source=source, field="r"))
+    if "rank_pattern" in config and config["rank_pattern"] is not None:
+        rank_pattern = config["rank_pattern"]
+        if not isinstance(rank_pattern, Mapping):
+            raise ValueError(
+                f"could not verify adapter rank: {source} has invalid rank metadata "
+                "(rank_pattern)"
+            )
+        ranks.extend(
+            _positive_int(v, source=source, field="rank_pattern") for v in rank_pattern.values()
+        )
+    if not ranks:
+        raise ValueError(f"could not verify adapter rank: {source} has no LoRA rank metadata")
+    return max(ranks)
+
+
+def uniform_rank_from_adapter_config(config: Mapping[str, Any], *, source: str) -> int:
+    """Return a uniform adapter rank for the VL SFT+GRPO recombine path."""
+    if not isinstance(config, Mapping):
+        raise ValueError(f"adapter rank preflight: {source} is not a JSON object")
+    if config.get("r") is None:
+        raise ValueError(
+            f"adapter rank preflight: {source} must contain a positive integer `r`"
+        )
+    rank = _positive_int(config["r"], source=source, field="r")
+    for key in ("rank_pattern", "alpha_pattern"):
+        pattern = config.get(key)
+        if pattern is None:
+            continue
+        if not isinstance(pattern, Mapping):
+            raise ValueError(
+                f"adapter rank preflight: {source} has invalid {key}={pattern!r}; "
+                "VL warm-start recombine requires a uniform LoRA rank/alpha"
+            )
+        if pattern:
+            raise ValueError(
+                f"adapter rank preflight: {source} has non-empty {key}={pattern!r}; "
+                "VL warm-start recombine requires a uniform LoRA rank/alpha"
+            )
+    return rank
+
+
+def load_hf_adapter_config(adapter_ref: str, token: str | None = None) -> Mapping[str, Any]:
+    """Read ``adapter_config.json`` for a Flash adapter ref from Hugging Face datasets."""
+    repo, filename = adapter_config_path_from_ref(adapter_ref)
+    try:
+        from huggingface_hub import hf_hub_download
+    except ImportError as exc:  # pragma: no cover - package extra is present in supported installs
+        raise ValueError(
+            "could not verify train.init_from_adapter rank: huggingface_hub is not installed"
+        ) from exc
+    try:
+        local = hf_hub_download(
+            repo_id=repo,
+            filename=filename,
+            repo_type="dataset",
+            token=token,
+        )
+    except Exception as exc:
+        raise ValueError(
+            f"could not verify train.init_from_adapter rank: failed to read {repo}:{filename}"
+        ) from exc
+    try:
+        with open(local, encoding="utf-8") as f:
+            config = json.load(f)
+    except Exception as exc:
+        raise ValueError(
+            f"could not verify train.init_from_adapter rank: invalid JSON in {repo}:{filename}"
+        ) from exc
+    if not isinstance(config, Mapping):
+        raise ValueError(
+            f"could not verify train.init_from_adapter rank: {repo}:{filename} "
+            "is not a JSON object"
+        )
+    return config
+
+
+def _uses_vl_warmstart_recombine(model: str) -> bool:
+    return model.startswith(_VL_WARMSTART_RECOMBINE_PREFIXES)
+
+
+def preflight_init_adapter_lora_rank(
+    spec: JobSpec,
+    *,
+    token: str | None = None,
+    config_loader: AdapterConfigLoader | None = None,
+) -> None:
+    """Reject warm-start adapters that cannot fit the model's serving LoRA rank cap.
+
+    The control plane calls this before creating/submitting a run. It intentionally uses only
+    ``adapter_config.json`` so the preflight stays CPU-only and catches undeployable adapters before
+    any training GPU is allocated.
+    """
+    adapter_storage_ref = (spec.train.init_from_adapter or "").strip()
+    if not adapter_storage_ref:
+        return
+    max_lora_rank = serving_lora_rank_cap(spec.model)
+    if max_lora_rank is None:
+        return
+
+    repo, filename = adapter_config_path_from_ref(adapter_storage_ref)
+    source = f"{repo}:{filename}"
+    loader = config_loader or load_hf_adapter_config
+    config = loader(adapter_storage_ref, token)
+
+    adapter_rank = rank_from_adapter_config(config, source=source)
+    if adapter_rank > max_lora_rank:
+        raise ValueError(
+            f"train.init_from_adapter={adapter_storage_ref!r} has rank {adapter_rank}, exceeding "
+            f"{spec.model}'s serving max_lora_rank={max_lora_rank}; use a lower-rank adapter "
+            "or raise the serving cap after real-GPU validation"
+        )
+
+    if spec.algorithm != "grpo" or not _uses_vl_warmstart_recombine(spec.model):
+        return
+
+    sft_rank = uniform_rank_from_adapter_config(config, source=source)
+    grpo_rank = int(spec.train.lora_rank)
+    recombined_rank = sft_rank + grpo_rank
+    if recombined_rank <= max_lora_rank:
+        return
+
+    allowed_grpo_rank = max_lora_rank - sft_rank
+    if allowed_grpo_rank >= 1:
+        guidance = f"set GRPO train.lora_rank <= {allowed_grpo_rank}"
+    else:
+        allowed_sft_rank = max_lora_rank - grpo_rank
+        if allowed_sft_rank >= 1:
+            guidance = f"retrain the SFT adapter at rank <= {allowed_sft_rank}"
+        else:
+            guidance = f"lower both SFT and GRPO ranks so their sum is <= {max_lora_rank}"
+    raise ValueError(
+        "train.init_from_adapter rank preflight failed: recombined SFT+GRPO adapter would be "
+        f"rank {recombined_rank} (SFT rank {sft_rank} + GRPO rank {grpo_rank}), exceeding "
+        f"{spec.model}'s serving max_lora_rank={max_lora_rank}; {guidance}"
+    )

{freesolo_flash_dev-0.2.35 → freesolo_flash_dev-0.2.36}/flash/providers/runpod/train/deps.py

@@ -30,7 +30,7 @@ WORKER_DEPS = [
     "flashinfer-python==0.6.6",
     "bitsandbytes>=0.49",
     "datasets>=4.7,<6",
-    # >=0.2.52: includes robust JSONL loading and corrected package metadata.
+    # >=0.2.54: includes robust JSONL loading and corrected package metadata.
     FREESOLO_WORKER_SPEC,
     "huggingface_hub>=0.25",
     "accelerate>=1.4",

{freesolo_flash_dev-0.2.35 → freesolo_flash_dev-0.2.36}/flash/runner/__init__.py

@@ -387,10 +387,7 @@ def _resolve_init_from_adapter(
     ref = spec.train.init_from_adapter
     if not ref:
         return spec
-    from flash.schema import checkpoint_storage_ref, parse_adapter_storage_ref, parse_checkpoint_ref
-
-    if parse_adapter_storage_ref(ref) is not None:
-        return spec
+    from flash.schema import checkpoint_storage_ref, parse_checkpoint_ref
 
     parsed = parse_checkpoint_ref(ref)
     if parsed is None:
@@ -431,6 +428,25 @@ def _resolve_init_from_adapter(
                 f"train.init_from_adapter references {src_run_id}/step-{step}, but that "
                 "deployable checkpoint was not found"
             )
+    else:
+        if src_status.state not in {"done", "deployed"}:
+            raise ValueError(
+                f"train.init_from_adapter references run {src_run_id!r}, but that run is "
+                f"{src_status.state!r}; use a completed source run or a concrete "
+                f"{src_run_id}/step-N checkpoint"
+            )
+        from flash.runner.checkpoints import CheckpointListingError, final_adapter_exists
+
+        try:
+            exists = final_adapter_exists(src_spec)
+        except CheckpointListingError as exc:
+            raise ValueError(str(exc)) from exc
+        if not exists:
+            raise ValueError(
+                f"train.init_from_adapter references run {src_run_id!r}, but its final "
+                "adapter was not found; use a concrete checkpoint ref like "
+                f"{src_run_id}/step-N if one exists"
+            )
     storage = checkpoint_storage_ref(src_spec.train.hf_repo, src_spec.phase, src_run_id, step)
     return replace(spec, train=replace(spec.train, init_from_adapter=storage))
 
@@ -459,6 +475,10 @@ def submit_job(
         owner_org_id=owner_org_id,
         owner_key_id=owner_key_id,
     )
+    if not dry_run:
+        from flash.lora_rank import preflight_init_adapter_lora_rank
+
+        preflight_init_adapter_lora_rank(worker_spec, token=os.environ.get("HF_TOKEN"))
     # env ref->sha pin is deferred (background) or after status save (sync) — never on creation path.
     status = RunStatus(
         run_id=public_spec.run_id,

{freesolo_flash_dev-0.2.35 → freesolo_flash_dev-0.2.36}/flash/runner/checkpoints.py

@@ -39,6 +39,15 @@ def _adapter_file_re(base: str) -> re.Pattern[str]:
     return re.compile(re.escape(base) + r"/checkpoints/step-(\d+)/adapter/([^/]+)$")
 
 
+def _adapter_folder_has_required_files(files: list[str], prefix: str) -> bool:
+    names = {
+        path.removeprefix(f"{prefix}/adapter/")
+        for path in files
+        if path.startswith(f"{prefix}/adapter/") and "/" not in path.removeprefix(f"{prefix}/adapter/")
+    }
+    return "adapter_config.json" in names and not names.isdisjoint(_ADAPTER_WEIGHT_FILES)
+
+
 def _repo_files(spec: JobSpec, *, strict: bool) -> list[str]:
     repo = spec.train.hf_repo
     if not repo:
@@ -110,3 +119,15 @@ def checkpoint_step_exists(spec: JobSpec, step: int) -> bool:
         int(item.get("step", -1)) == int(step)
         for item in _checkpoints_from_files(spec, _repo_files(spec, strict=True))
     )
+
+
+def final_adapter_exists(spec: JobSpec) -> bool:
+    """Authoritatively verify that the run-level final adapter exists in the artifact repo."""
+    try:
+        files = _repo_files(spec, strict=True)
+    except CheckpointListingError as exc:
+        cause = exc.__cause__ or exc
+        raise CheckpointListingError(
+            f"could not verify final adapter for {spec.run_id}: {cause}"
+        ) from cause
+    return _adapter_folder_has_required_files(files, adapter_prefix(spec))