[0.16.1] llama_bin.txt path added

Author: pytraveler

CHANGELOG.md

@@ -6,6 +6,32 @@ The version in `pyproject.toml`, the git tag and the release on GitHub always sa
 the same thing; the release workflow refuses a tag that disagrees with
 `pyproject.toml`, or one that neither changelog has a section for.
 
+## 0.16.1 - 2026-08-22
+
+### Added
+
+- **A path in a file, for a server whose environment is not yours to set.** One
+  line in `ComfyUI/user/minimax_h3_rewriter/llama_bin.txt` — the folder your
+  llama.cpp was built in, or the binary itself — and the node runs that build.
+  It is read after `MINIMAX_H3_LLAMA_BIN` and before everything else.
+
+  This is what `MINIMAX_H3_LLAMA_BIN` cannot do on a server. An export reaches a
+  server started from that same shell and nothing else: a systemd unit, a
+  container entrypoint or a launcher script hands the process an environment of
+  its own and never reads your `~/.bashrc`, so the variable is simply absent
+  where it matters — and so is anything you added to `PATH` the same way. The
+  file is read by the node itself, and does not care who started ComfyUI.
+
+### Changed
+
+- **When no llama.cpp is found anywhere, the refusal prints what this process
+  actually had.** The variable and whether it is set here, the file and whether
+  it exists, the unpacked runtime folder, and `PATH` with its entry count — plus,
+  on Linux, the one command that shows the running server's real environment.
+  "Put it on PATH" is useless advice to someone who did exactly that in a shell
+  the server never saw, so the message reports the search rather than repeating
+  the instruction.
+
 ## 0.16.0 - 2026-08-21
 
 ### Added

CHANGELOG_RU.md

@@ -6,6 +6,31 @@
 workflow релиза отклонит тег, который расходится с `pyproject.toml`, и тег, для
 которого нет раздела ни в одном из двух changelog'ов.
 
+## 0.16.1 - 2026-08-22
+
+### Добавлено
+
+- **Путь в файле — для сервера, чьё окружение задаёте не вы.** Одна строчка в
+  `ComfyUI/user/minimax_h3_rewriter/llama_bin.txt` — папка, в которой собран ваш
+  llama.cpp, или сам бинарник, — и нода запускает эту сборку. Файл читается
+  после `MINIMAX_H3_LLAMA_BIN` и раньше всего остального.
+
+  Именно этого `MINIMAX_H3_LLAMA_BIN` не может на сервере. `export` доходит до
+  сервера, запущенного из этой же оболочки, и больше никуда: юнит systemd,
+  entrypoint контейнера или скрипт-лаунчер выдают процессу собственное окружение
+  и `~/.bashrc` не читают, так что переменной там просто нет — как нет и того,
+  что вы тем же способом дописали в `PATH`. Файл читает сама нода, и ей всё
+  равно, кто запустил ComfyUI.
+
+### Изменено
+
+- **Если llama.cpp не нашёлся нигде, отказ печатает, что было у этого процесса на
+  самом деле.** Переменная и стоит ли она здесь, файл и есть ли он, папка
+  распакованного рантайма и `PATH` со счётом записей — а под Linux ещё и та самая
+  команда, которая показывает настоящее окружение работающего сервера. «Положите
+  в PATH» — бесполезный совет тому, кто ровно это и сделал в оболочке, которой
+  сервер не видел, так что сообщение показывает поиск, а не повторяет указание.
+
 ## 0.16.0 - 2026-08-21
 
 ### Добавлено

README.md

@@ -1122,21 +1122,37 @@ when the binaries are in use:
 | `cpu` | 17 MB | no GPU at all |
 
 **An llama.cpp you already have is run as it is.** Before fetching anything the
-node looks in three places, in order: the path in `MINIMAX_H3_LLAMA_BIN`, then
-its own `runtime/` folder, then `PATH`. A build you compiled yourself therefore
-needs no setting at all — put its `build/bin` on `PATH`, or name it outright:
+node looks in four places, in order: the path in `MINIMAX_H3_LLAMA_BIN`, the
+path written in `ComfyUI/user/minimax_h3_rewriter/llama_bin.txt`, its own
+`runtime/` folder, then `PATH`. A build you compiled yourself therefore needs no
+setting at all — put its `build/bin` on `PATH`, or name it outright:
 
 ```sh
 export MINIMAX_H3_LLAMA_BIN=/opt/llama.cpp/build/bin   # the folder, or the binary in it
 ```
 
+**On a server, prefer the file.** An export reaches a server started from that
+same shell and nothing else — a systemd unit, a container entrypoint or a
+launcher script hands the process an environment of its own, and never reads
+your `~/.bashrc`. One line in `llama_bin.txt` is read by the node itself and
+does not care who started ComfyUI:
+
+```sh
+echo /opt/llama.cpp/build/bin > ~/comfy/ComfyUI/user/minimax_h3_rewriter/llama_bin.txt
+```
+
 `llama_backend` then stops mattering: it picks which archive to download, not
 what an existing binary was compiled against. This is the road to a CUDA
 llama.cpp on Linux — build it once with `-DGGML_CUDA=ON`, name it here, and
 `device = cuda:0` does what it says. The caption nodes look for
 `llama-mtmd-cli` beside it; a build without that target sends the node back to
-the archive for that one job. A variable pointing at nothing is an error rather
-than a quiet download, so a typo says so instead of costing half a gigabyte.
+the archive for that one job.
+
+A path pointing at nothing is an error rather than a quiet download, so a typo
+says so instead of costing half a gigabyte. And when nothing is found anywhere,
+the refusal prints what the ComfyUI **process** actually had — the variable, the
+file, the folder and its `PATH` — instead of repeating advice you may already
+have taken in a shell it never saw.
 
 > **Why not the `llama-cpp-python` CUDA wheels.** Both current ones fail on
 > ordinary consumer hardware, in two unrelated ways:

README_RU.md

@@ -1118,21 +1118,36 @@ llama.cpp уносит дочерний процесс, а не ComfyUI вмес
 | `cpu` | 17 МБ | без GPU вовсе |
 
 **Уже собранный llama.cpp запускается как есть.** Прежде чем что-то качать,
-нода смотрит в три места по порядку: путь из `MINIMAX_H3_LLAMA_BIN`, потом
-собственная папка `runtime/`, потом `PATH`. Собственной сборке поэтому не нужно
-никаких настроек — положите её `build/bin` в `PATH` или назовите прямо:
+нода смотрит в четыре места по порядку: путь из `MINIMAX_H3_LLAMA_BIN`, путь,
+записанный в `ComfyUI/user/minimax_h3_rewriter/llama_bin.txt`, собственная папка
+`runtime/`, потом `PATH`. Собственной сборке поэтому не нужно никаких настроек —
+положите её `build/bin` в `PATH` или назовите прямо:
 
 ```sh
 export MINIMAX_H3_LLAMA_BIN=/opt/llama.cpp/build/bin   # папка или сам бинарник
 ```
 
+**На сервере надёжнее файл.** `export` доходит до сервера, запущенного из этой же
+оболочки, и больше никуда: юнит systemd, entrypoint контейнера или скрипт-лаунчер
+выдают процессу собственное окружение и ваш `~/.bashrc` не читают вовсе. Строчку в
+`llama_bin.txt` читает сама нода, и ей всё равно, кто запустил ComfyUI:
+
+```sh
+echo /opt/llama.cpp/build/bin > ~/comfy/ComfyUI/user/minimax_h3_rewriter/llama_bin.txt
+```
+
 После этого `llama_backend` перестаёт что-либо значить: он выбирает, какой архив
 скачать, а не то, с чем скомпилирован уже имеющийся бинарник. Это и есть дорога
 к CUDA-сборке llama.cpp под Linux — собрать один раз с `-DGGML_CUDA=ON`,
 назвать здесь, и `device = cuda:0` начнёт делать то, что написано. Ноды-описатели
 ищут рядом `llama-mtmd-cli`; сборка без этой цели отправит ноду за архивом ради
-одной этой задачи. Переменная, указывающая в пустоту, — ошибка, а не тихая
-загрузка: опечатка скажет о себе, а не обойдётся в полгигабайта.
+одной этой задачи.
+
+Путь, указывающий в пустоту, — ошибка, а не тихая загрузка: опечатка скажет о
+себе, а не обойдётся в полгигабайта. А если не нашлось нигде, отказ печатает, что
+было у **процесса** ComfyUI на самом деле — переменная, файл, папка и его `PATH`, —
+вместо того чтобы повторять совет, которому вы могли уже последовать в оболочке,
+которой сервер не видел.
 
 > **Почему не CUDA-колёса `llama-cpp-python`.** Оба нынешних не работают на
 > обычном потребительском железе, причём по двум независимым причинам:

minimax_h3_rewriter/llamacpp.py

@@ -24,9 +24,11 @@
 ask for it by name.
 
 None of which applies when the machine already has an llama.cpp:
-``MINIMAX_H3_LLAMA_BIN`` names one outright, PATH is read when it does not,
-and whatever is found is run as it is. That is the only road to a CUDA
-llama.cpp on Linux, since no CUDA archive is published for it.
+``MINIMAX_H3_LLAMA_BIN`` names one outright, ``llama_bin.txt`` in the user
+directory says the same to a server whose environment you cannot set, PATH is
+read when neither is there, and whatever is found is run as it is. That is the
+only road to a CUDA llama.cpp on Linux, since no CUDA archive is published for
+it.
 """
 
 from __future__ import annotations
@@ -57,6 +59,15 @@
 #: every build puts llama-mtmd-cli next to llama-completion.
 BIN_ENV = "MINIMAX_H3_LLAMA_BIN"
 
+#: The same thing written down, for a server whose environment is not yours.
+#:
+#: An export in a shell reaches a server started from that shell and nothing
+#: else: a systemd unit, a container entrypoint or a launcher script hands the
+#: process an environment of its own, and the variable above is simply absent
+#: there. This file is read from ComfyUI's own user directory instead, beside
+#: the model list -- one path in it, blank lines and '#' comments ignored.
+BIN_FILE = "llama_bin.txt"
+
 #: (sys.platform, backend) -> archive names within the release.
 #:
 #: The CUDA entry is two archives: the runtime libraries live in a separate
@@ -178,6 +189,11 @@ def install_dir(backend: str) -> str:
     return os.path.join(root(), f"{RELEASE}-{backend}")
 
 
+def bin_file() -> str:
+    """``<ComfyUI user>/minimax_h3_rewriter/llama_bin.txt``, read if it is there."""
+    return os.path.join(os.path.dirname(root()), BIN_FILE)
+
+
 def find_binary(directory: str, names: tuple[str, ...] = BINARIES) -> str:
     """Locate the completion executable inside an unpacked release, at any depth."""
     for name in names:
@@ -197,14 +213,14 @@ def installed(backend: str) -> str:
     return find_binary(directory) if os.path.isdir(directory) else ""
 
 
-def _named_binary(names: tuple[str, ...]) -> str:
-    """The binary ``BIN_ENV`` points at, or "" when the variable is unset.
+def _binary_at(value: str, names: tuple[str, ...], source: str) -> str:
+    """Resolve a path someone gave us to one of ``names``, or say why not.
 
-    A variable that is set but points nowhere useful raises rather than falls
+    A path that is given but points nowhere useful raises rather than falls
     through: naming a build is an instruction, and quietly downloading a
     different one instead would hide a typo behind half a gigabyte.
     """
-    value = (os.environ.get(BIN_ENV) or "").strip().strip('"')
+    value = (value or "").strip().strip('"')
     if not value:
         return ""
     if EXE and not os.path.exists(value) and os.path.isfile(value + EXE):
@@ -217,17 +233,34 @@ def _named_binary(names: tuple[str, ...]) -> str:
         if beside:
             return beside
         raise RuntimeError(
-            f"{BIN_ENV} is set to '{value}', and none of {', '.join(names)} is that "
-            f"file or sits beside it."
+            f"{source} is '{value}', and none of {', '.join(names)} is that file "
+            f"or sits beside it."
         )
     if os.path.isdir(value):
         found = find_binary(value, names)
         if found:
             return found
         raise RuntimeError(
-            f"{BIN_ENV} is set to '{value}', which holds none of {', '.join(names)}."
+            f"{source} is '{value}', which holds none of {', '.join(names)}."
         )
-    raise RuntimeError(f"{BIN_ENV} is set to '{value}', which does not exist.")
+    raise RuntimeError(f"{source} is '{value}', which does not exist.")
+
+
+def _named_binary(names: tuple[str, ...]) -> str:
+    """The binary ``BIN_ENV`` points at, or "" when the variable is unset."""
+    return _binary_at(os.environ.get(BIN_ENV) or "", names, BIN_ENV)
+
+
+def _file_binary(names: tuple[str, ...]) -> str:
+    """The binary ``BIN_FILE`` names, or "" when there is no such file."""
+    path = bin_file()
+    try:
+        with open(path, "r", encoding="utf-8") as handle:
+            lines = [line.strip() for line in handle]
+    except OSError:
+        return ""
+    wanted = next((line for line in lines if line and not line.startswith("#")), "")
+    return _binary_at(wanted, names, path)
 
 
 def _path_binary(names: tuple[str, ...]) -> str:
@@ -250,8 +283,8 @@ def _announce(binary: str, source: str) -> str:
 
 
 def external(names: tuple[str, ...] = BINARIES) -> str:
-    """An llama.cpp that is already here: named in the environment, or on PATH."""
-    return _named_binary(names) or _path_binary(names)
+    """An llama.cpp that is already here: given by name, or found on PATH."""
+    return _named_binary(names) or _file_binary(names) or _path_binary(names)
 
 
 def available() -> bool:
@@ -350,6 +383,7 @@ def _packaged(backend: str, auto_download: bool, progress=None) -> str:
             f"The llama.cpp {backend} runtime is not in '{directory}' and auto_download is off. "
             f"Enable it, or unpack {', '.join(names)} from "
             f"https://github.com/{REPO}/releases/tag/{RELEASE} into that folder."
+            f"\n\n{where_looked(backend)}"
         )
 
     from . import download
@@ -431,23 +465,71 @@ def report(position: int, label: str, _name=name) -> None:
     return binary
 
 
+def where_looked(backend: str) -> str:
+    """The places that were searched and what each held, as a block of text.
+
+    "Put it on PATH" is useless advice to someone who did exactly that in a
+    shell the server never saw, so a refusal reports the environment this
+    process actually has rather than repeating the instruction.
+    """
+    named = os.environ.get(BIN_ENV)
+    entries = [entry for entry in os.environ.get("PATH", "").split(os.pathsep) if entry]
+    shown = os.pathsep.join(entries)
+    if len(shown) > 400:
+        shown = shown[:400] + " ..."
+    directory = install_dir(resolve_backend(backend))
+    written = bin_file()
+
+    lines = [
+        f"Where this ComfyUI process (pid {os.getpid()}) looked:",
+        f"  {BIN_ENV}: " + (f"'{named}'" if named else "not set in this process"),
+        f"  {written}: " + ("read" if os.path.isfile(written) else "no such file"),
+        f"  unpacked runtime: {directory}"
+        + ("" if os.path.isdir(directory) else " (not there)"),
+        f"  PATH: {len(entries)} entries, none holding {' or '.join(BINARIES)}",
+        f"    {shown}",
+    ]
+    if not named:
+        lines.append(
+            "An export in your shell reaches a server started from that shell and "
+            "nothing else -- a service is handed an environment of its own."
+        )
+    if sys.platform == "linux":
+        lines.append(
+            f"See what this process really has: tr '\\0' '\\n' "
+            f"< /proc/{os.getpid()}/environ | grep -E '^(PATH|{BIN_ENV})='"
+        )
+    lines.append(
+        f"The way that needs no environment at all: write the path to your build "
+        f"into {written}, or put the build itself in {directory}."
+    )
+    return "\n".join(lines)
+
+
 def ensure(backend: str, auto_download: bool, progress=None) -> str:
     """Return the path to the completion binary, fetching the release if needed.
 
-    Four places, in this order: what ``BIN_ENV`` names, because naming a build
-    is an instruction; then what this pack has already unpacked, which is the
-    pinned, known-good one; then PATH, so an llama.cpp compiled on this machine
-    is used rather than a second copy downloaded beside it; then the download.
-
-    That third step is the only road to a CUDA llama.cpp on Linux, where
-    upstream publishes no CUDA archive at all. It is also why ``llama_backend``
-    stops mattering once a build is found: it picks which archive to fetch, not
-    what an existing binary was compiled against.
+    Five places, in this order: what ``BIN_ENV`` names and what ``BIN_FILE``
+    names, because giving a path is an instruction; then what this pack has
+    already unpacked, which is the pinned, known-good one; then PATH, so an
+    llama.cpp compiled on this machine is used rather than a second copy
+    downloaded beside it; then the download.
+
+    Those given paths are the only road to a CUDA llama.cpp on Linux, where
+    upstream publishes no CUDA archive at all. They are also why
+    ``llama_backend`` stops mattering once a build is found: it picks which
+    archive to fetch, not what an existing binary was compiled against. When
+    there is no archive to fetch either, the refusal carries the search rather
+    than repeating advice the reader may already have taken.
     """
     named = _named_binary(BINARIES)
     if named:
         return _announce(named, f"named in {BIN_ENV}")
 
+    written = _file_binary(BINARIES)
+    if written:
+        return _announce(written, f"named in {bin_file()}")
+
     backend = resolve_backend(backend)
     existing = installed(backend)
     if existing:
@@ -457,13 +539,20 @@ def ensure(backend: str, auto_download: bool, progress=None) -> str:
     if on_path:
         return _announce(on_path, "found on PATH")
 
+    try:
+        assets(backend)
+    except RuntimeError as error:
+        raise RuntimeError(
+            f"{error}\n\n{where_looked(backend)}"
+        ) from error
+
     return _packaged(backend, auto_download, progress)
 
 
 def ensure_mtmd(backend: str, auto_download: bool, progress=None) -> str:
     """Return the path to ``llama-mtmd-cli``, fetching the release if needed.
 
-    The same four places in the same order, since the captioner is built beside
+    The same five places in the same order, since the captioner is built beside
     the completion binary and ships in the same archive: a captioner run on a
     machine that has already rewritten a prompt downloads nothing.
 
@@ -475,6 +564,10 @@ def ensure_mtmd(backend: str, auto_download: bool, progress=None) -> str:
     if named:
         return _announce(named, f"named in {BIN_ENV}")
 
+    written = _file_binary(MTMD_BINARIES)
+    if written:
+        return _announce(written, f"named in {bin_file()}")
+
     directory = install_dir(resolve_backend(backend))
     unpacked = find_binary(directory, MTMD_BINARIES) if os.path.isdir(directory) else ""
     if unpacked: