DFlash loader: fail-fast on missing local path instead of silent HF fallback

Surfaces the bug the user hit on Mac mini 2026-06-09:

    'failure 原因是默认 DRAFTER_ID=models/dflash-kakeya-baseline 被
     当成 HF repo id 去下载,远端返回 404'

User ran:
    SKIP_VERIFIER=1 PROPOSER_KV_CAPTURE=1 \
        bash scripts/review_pr_k3_feasibility_on_mac.sh

Result: exit_code=25 (fail_at_drafter_load_skip_verifier), JSON
evidence shows HF Hub 404 on 'models/dflash-kakeya-baseline'.

Root cause:

  inference_engine.v04.dflash_loader._resolve_local_dir was:

      def _resolve_local_dir(repo_or_path, hf_kwargs):
          p = Path(repo_or_path)
          if p.exists() and p.is_dir():
              return p
          # NB: silent fallthrough — any non-existent local path
          # gets sent to huggingface_hub.snapshot_download and 404s
          return Path(snapshot_download(repo_id=repo_or_path, ...))

  When the user's Mac mini didn't have 'models/dflash-kakeya-baseline'
  on disk (likely because 'git lfs pull' hadn't run, or wrong cwd, or
  worktree without the LFS-tracked checkpoint), the resolver silently
  treated the path as a HF repo id and got 404 — far from the actual
  root cause, which was a missing local file.

Fix:

  Add a heuristic _looks_like_local_path() that returns True for inputs
  starting with 'models/', './', '../', or '/' — the common project-
  relative or absolute-path prefixes that distinguish a local path from
  the canonical HF '<user_or_org>/<repo>' format.

  In _resolve_local_dir, BEFORE falling through to HF Hub fetch:
    1. If the input doesn't exist on disk AND looks like a local path
       per the heuristic → raise FileNotFoundError with an actionable
       message listing the three common causes (missing 'git lfs pull',
       wrong cwd, wrong worktree) and how to confirm each.
    2. Otherwise (HF-format input not on disk) → continue to HF Hub
       snapshot_download as before. Pure HF repo ids unaffected.

  Added regression tests:
    TestLooksLikeLocalPath (4 tests)
      - models/* prefix matched
      - ./ + ../ relative prefixes matched
      - /Users/... + /tmp/... absolute prefixes matched
      - HF format (org/repo) NOT matched
    TestResolveLocalDirFailFast (5 tests)
      - existing local dir returned as-is
      - missing 'models/...' raises FileNotFoundError with 'git lfs pull'
        + 'current working directory' in the message
      - missing './ ...' / '../...' / '/tmp/...' all raise FileNotFoundError
      - HF repo id (no local-path prefix) still flows through to
        huggingface_hub.snapshot_download (verified via monkeypatch)

  9/9 new tests pass. 319/319 v04 suite total.

Reviewer aid script (scripts/review_pr_k3_feasibility_on_mac.sh)
gets a 'pre-flight 0' check that fires BEFORE invoking Python:

  case "$DRAFTER_ID" in
      models/*|./*|../*|/*)
          # if local path doesn't exist on disk → exit 1 with the same
          # actionable message as the Python-side fail-fast
          # if exists but missing config.json → exit 1 with file listing
  esac

This means the next user run with the same misconfiguration:
  - Fails at the bash pre-flight, NOT at HF Hub fetch
  - Prints the three common causes + recovery commands directly
  - Doesn't waste time on a 404 round-trip + Python-side error parse

Net effect:

  Two layers of fail-fast (bash pre-flight + Python resolver) catch the
  'local path doesn't exist' misconfiguration before it's mis-routed
  to HF Hub. The user's exact 2026-06-09 failure mode now produces an
  actionable error in <1 second with three concrete recovery paths,
  instead of a 404 with 'models/dflash-kakeya-baseline' as a fake repo
  id.

Tests: 319 passed (310 pre-existing + 9 new regression).

Stack: same as PR #98 (continuing on the same branch).

Scope: this PR's branch is now PR #98 + this fix. The fix is in
v0.4 K3 prereq 4 territory (the DFlash loader) and rightfully should
backport into PR #95 (K3 Block B prereqs 1+4) when the v04 stack
settles. Carrying it on PR #98's branch is the unblock path so the
user's next Mac mini run isn't blocked on a missing-local-path 404.

Co-authored-by: FluffyAIcode <FluffyAIcode@users.noreply.github.com>

Author: cursoragent

inference_engine/v04/dflash_loader.py

@@ -143,11 +143,64 @@ def expected_class_name(self) -> str:
 )
 
 
+_LOCAL_PATH_HEURISTICS = (
+    "models/",
+    "./",
+    "../",
+    "/",
+)
+
+
+def _looks_like_local_path(repo_or_path: str) -> bool:
+    """Heuristic: does the input look like a local filesystem path
+    rather than a HuggingFace ``org/repo`` repo id?
+
+    Returns True for inputs starting with ``models/``, ``./``, ``../``,
+    or ``/`` — the common project-relative or absolute path prefixes.
+    HF repo ids are ``<user_or_org>/<repo>`` (exactly one slash, no
+    leading slash, no relative-path component); inputs matching the
+    HF format return False.
+
+    This heuristic is used to **fail fast** when a user passes a
+    project-relative path (like ``models/dflash-kakeya-baseline``)
+    that doesn't exist on disk, instead of silently falling through
+    to HF Hub (which then returns 404 with a confusing error message
+    far from the actual root cause).
+    """
+    return repo_or_path.startswith(_LOCAL_PATH_HEURISTICS)
+
+
 def _resolve_local_dir(repo_or_path: str, hf_kwargs: Mapping[str, Any]) -> Path:
-    """Resolve repo id to a local snapshot. Pure HF-hub call; no model load."""
+    """Resolve repo id to a local snapshot. Pure HF-hub call; no model load.
+
+    If ``repo_or_path`` looks like a local path (per
+    :func:`_looks_like_local_path`) but does NOT exist on disk, this
+    raises :class:`FileNotFoundError` with an actionable message instead
+    of silently falling through to ``huggingface_hub.snapshot_download``
+    (which then emits a 404 error far from the actual root cause —
+    typically a missing ``git lfs pull`` or wrong cwd).
+    """
     p = Path(repo_or_path)
     if p.exists() and p.is_dir():
         return p
+    if _looks_like_local_path(repo_or_path):
+        raise FileNotFoundError(
+            f"DFlash drafter source {repo_or_path!r} looks like a local "
+            f"path but does not exist on disk (resolved to "
+            f"{p.absolute()}). Common causes:\n"
+            f"  1. The Git LFS pointer for the model has not been pulled "
+            f"yet — run 'git lfs install && git lfs pull' from the repo "
+            f"root.\n"
+            f"  2. The current working directory is not the repo root — "
+            f"verify with 'pwd' and 'ls models/' before re-running.\n"
+            f"  3. You are on a worktree that does not have the model "
+            f"checkpoint — use a worktree where 'git lfs pull' has run.\n"
+            f"\n"
+            f"If you actually intended a HuggingFace repo id, use the "
+            f"'<user_or_org>/<repo>' format (no leading 'models/', './' "
+            f"or '/'). Refusing to silently fall through to HF Hub fetch "
+            f"because that would 404 with a misleading error message."
+        )
     from huggingface_hub import snapshot_download
     cache_dir = hf_kwargs.get("cache_dir")
     token = hf_kwargs.get("token") or hf_kwargs.get("use_auth_token")

scripts/review_pr_k3_feasibility_on_mac.sh

@@ -124,6 +124,47 @@ echo "    Proposer KV capture:  $PROPOSER_KV_CAPTURE"
 echo "    Report:               $report"
 echo
 
+# Pre-flight 0: drafter source check (skipped when SKIP_DRAFTER=1).
+#
+# When DRAFTER_ID is a local path (starts with 'models/', './', '../', '/'),
+# verify the directory exists with config.json + safetensors before
+# invoking Python — a missing local path otherwise silently falls through
+# to HF Hub fetch, which 404s with a misleading error message far from
+# the actual root cause (commonly a missing 'git lfs pull' or wrong cwd).
+if [[ "$SKIP_DRAFTER" != "1" ]]; then
+    case "$DRAFTER_ID" in
+        models/*|./*|../*|/*)
+            if [[ ! -d "$DRAFTER_ID" ]]; then
+                echo "ERROR: DRAFTER_ID='$DRAFTER_ID' looks like a local path but does not exist."
+                echo
+                echo "Common causes:"
+                echo "  1. The Git LFS pointer for the model has not been pulled."
+                echo "     Run from the repo root:"
+                echo "         git lfs install"
+                echo "         git lfs pull"
+                echo
+                echo "  2. The current working directory is not the repo root."
+                echo "         pwd        # should be the repo root"
+                echo "         ls models/ # should list dflash-kakeya-baseline"
+                echo
+                echo "  3. You are on a worktree without the model checkpoint."
+                echo "         git status   # confirm worktree"
+                echo
+                echo "If you intended a HuggingFace repo id instead, override:"
+                echo "    DRAFTER_ID=z-lab/gemma-4-26B-A4B-it-DFlash bash $0"
+                echo "    (note: that variant is NOT alignment-trained — research only)"
+                exit 1
+            fi
+            if [[ ! -f "$DRAFTER_ID/config.json" ]]; then
+                echo "ERROR: DRAFTER_ID='$DRAFTER_ID' is a directory but lacks config.json."
+                echo "       The model checkpoint at this path is incomplete or corrupted."
+                ls -la "$DRAFTER_ID" 2>&1 | head -20
+                exit 1
+            fi
+            ;;
+    esac
+fi
+
 # Pre-flight 1: quantized verifier exists? (skipped when SKIP_VERIFIER=1)
 if [[ "$SKIP_VERIFIER" == "1" ]]; then
     echo "[pre-flight] SKIP_VERIFIER=1 set; bypassing verifier-dir check."

tests/inference_engine/v04/test_dflash_loader.py

@@ -34,7 +34,9 @@
 from inference_engine.v04 import dflash_loader  # noqa: E402
 from inference_engine.v04.dflash_loader import (  # noqa: E402
     EMBED_TOKENS_TRAINED_VAR_THRESHOLD,
+    _looks_like_local_path,
     _propose_key_remap,
+    _resolve_local_dir,
     inspect_dflash_checkpoint,
     load_dflash_drafter,
 )
@@ -368,3 +370,89 @@ def test_cli_inspect_writes_json(self, tmp_path):
         assert "key_remap" in payload
         assert "fc.weight" in payload["fc_keys"]
         assert "hidden_norm.weight" in payload["hidden_norm_keys"]
+
+
+# ---------------------------------------------------------------------------
+# 5. Local-path heuristic + fail-fast resolver
+#    (Regression for 2026-06-09 user-side bug: DRAFTER_ID=models/dflash-
+#    kakeya-baseline silently fell through to HF Hub fetch when the local
+#    LFS-pulled directory wasn't present, and HF returned 404 with a
+#    misleading error message far from the root cause.)
+# ---------------------------------------------------------------------------
+
+
+class TestLooksLikeLocalPath:
+
+    def test_models_prefix(self):
+        assert _looks_like_local_path("models/dflash-kakeya-baseline") is True
+        assert _looks_like_local_path("models/foo") is True
+
+    def test_relative_prefixes(self):
+        assert _looks_like_local_path("./models/foo") is True
+        assert _looks_like_local_path("../models/foo") is True
+
+    def test_absolute_prefix(self):
+        assert _looks_like_local_path("/Users/me/models/foo") is True
+        assert _looks_like_local_path("/tmp/checkpoint") is True
+
+    def test_hf_repo_id_does_not_match(self):
+        assert _looks_like_local_path("z-lab/gemma-4-26B-A4B-it-DFlash") is False
+        assert _looks_like_local_path("google/gemma-3-1b-it") is False
+        assert _looks_like_local_path("FakeRockert543/gemma-4-26b-a4b-it-MLX-4bit") is False
+        assert _looks_like_local_path("dllm-hub/Qwen3-0.6B-diffusion-mdlm-v0.1") is False
+
+
+class TestResolveLocalDirFailFast:
+    """Regression for 2026-06-09 user-side bug.
+
+    User report: ``DRAFTER_ID=models/dflash-kakeya-baseline`` was treated
+    as an HF repo id and the script tried to download from HF, which
+    returned 404. Pre-fix _resolve_local_dir silently fell through to
+    huggingface_hub.snapshot_download for any non-existent local path.
+    Post-fix it raises FileNotFoundError with an actionable message.
+    """
+
+    def test_local_path_that_exists_is_returned(self, tmp_path):
+        d = _write_tiny_checkpoint(
+            tmp_path / "models" / "dflash-kakeya-baseline",
+            use_drafter_prefix=False, include_extras=True,
+            embed_tokens_trained=True,
+        )
+        result = _resolve_local_dir(str(d), {})
+        assert result == d
+
+    def test_local_path_that_does_not_exist_raises(self):
+        with pytest.raises(FileNotFoundError) as excinfo:
+            _resolve_local_dir("models/dflash-kakeya-baseline", {})
+        msg = str(excinfo.value)
+        assert "does not exist on disk" in msg
+        assert "git lfs pull" in msg
+        assert "current working directory" in msg.lower()
+
+    def test_relative_path_that_does_not_exist_raises(self):
+        with pytest.raises(FileNotFoundError):
+            _resolve_local_dir("./models/missing", {})
+        with pytest.raises(FileNotFoundError):
+            _resolve_local_dir("../models/missing", {})
+
+    def test_absolute_path_that_does_not_exist_raises(self):
+        with pytest.raises(FileNotFoundError):
+            _resolve_local_dir("/tmp/definitely-not-a-real-checkpoint", {})
+
+    def test_hf_repo_id_falls_through_to_hf_hub(self, monkeypatch):
+        """For a non-local-looking input (HF repo id format), the resolver
+        should still call huggingface_hub.snapshot_download — the fail-fast
+        path is local-path-specific."""
+        called = {}
+
+        def fake_snapshot_download(**kwargs):
+            called["kwargs"] = kwargs
+            return "/tmp/fake-cached-snapshot"
+
+        import huggingface_hub
+        monkeypatch.setattr(
+            huggingface_hub, "snapshot_download", fake_snapshot_download,
+        )
+        result = _resolve_local_dir("z-lab/gemma-4-26B-A4B-it-DFlash", {})
+        assert called["kwargs"]["repo_id"] == "z-lab/gemma-4-26B-A4B-it-DFlash"
+        assert str(result) == "/tmp/fake-cached-snapshot"