Skip to content

Free, open-source AI video generator for Mac. Run LTX-2.5 and MiniMax H3 (Hailuo) locally on Apple Silicon: text-to-video and image-to-video with sound, lip-sync, character LoRA training, songs from lyrics (YuE2) and image editing (Qwen-Image-Edit). One-click install via Pinokio. Offline: no cloud, no API key, no NVIDIA GPU.

fix(helper): drain stranded ready event from _read_until + runtime fingerprint (v3.0.11)

mrbizarro093a9f0563e7
diff --git a/VERSION b/VERSION
index a909317..778bf95 100644
--- a/VERSION
+++ b/VERSION
@@ -1 +1 @@
-3.0.10
+3.0.11
diff --git a/docs/STATE.md b/docs/STATE.md
index dd3f289..373a7ce 100644
--- a/docs/STATE.md
+++ b/docs/STATE.md
@@ -1,6 +1,6 @@
# Phosphene — project state, history, open work
-**Public release: `v3.0.10`.** The entire v3.0 line shipped — v3.0.0 (Characters / Voice / Image Studio / A2V, May 23) → v3.0.1 (FFLF crash fix) → v3.0.2 (Boost/Turbo accel restored after a 2-month silent regression) → v3.0.3 (HiDream hidden, #15) → v3.0.4 (CivitAI SSL) → v3.0.5 (A2V kwarg signature shim, #5) → v3.0.6 (deep-review hardening) → v3.0.7 (GPU-race fix + /status version surfacing) → **v3.0.8 (ltx-2-mlx v0.14.8 catch-up — codec-only patches, I2V "mosaic"/Metal-watchdog fix #17, ASCII version-skew handshake fix)** → **v3.0.9 (custom I2V Width×height inputs restored for power users; Train-tab dev-transformer Download "unknown install key" fix — form-encoding, reported by @cocktailpeanut)** → **v3.0.10 (model-integrity self-heal — boot scan + `/status.model_integrity` + a one-click Repair banner for corrupt/partial weights, the leading *non-Metal* "mosaic" garbage-decode cause; safetensors header+size check)**. See §4 for the full version history. The May-17 Codex C+ UI restructure (capability tiers, Q4 surface, Character as 5th mode pill, accel kill, HQ-speed move) and the Train-tab / LoRA-chrome work that followed are all baseline now, folded into v3.0.x. There is no `v2.0.6` tag.
+**Public release: `v3.0.10`.** The entire v3.0 line shipped — v3.0.0 (Characters / Voice / Image Studio / A2V, May 23) → v3.0.1 (FFLF crash fix) → v3.0.2 (Boost/Turbo accel restored after a 2-month silent regression) → v3.0.3 (HiDream hidden, #15) → v3.0.4 (CivitAI SSL) → v3.0.5 (A2V kwarg signature shim, #5) → v3.0.6 (deep-review hardening) → v3.0.7 (GPU-race fix + /status version surfacing) → **v3.0.8 (ltx-2-mlx v0.14.8 catch-up — codec-only patches, I2V "mosaic"/Metal-watchdog fix #17, ASCII version-skew handshake fix)** → **v3.0.9 (custom I2V Width×height inputs restored for power users; Train-tab dev-transformer Download "unknown install key" fix — form-encoding, reported by @cocktailpeanut)** → **v3.0.10 (model-integrity self-heal — boot scan + `/status.model_integrity` + a one-click Repair banner for corrupt/partial weights, the leading *non-Metal* "mosaic" garbage-decode cause; safetensors header+size check)** → **v3.0.11 (latent helper-handshake hang fixed: `_read_until` mixed `select()` on the raw fd with a buffered `readline()`, so any event the helper emitted *right before* `ready` — a version-skew line, the new runtime fingerprint — got stranded in the TextIOWrapper buffer and the panel hung 120 s → "helper failed to start: None". This is the true root cause behind the mislabeled "⚠️-emoji" handshake break. Now reads the raw fd via `os.read()` into a carry buffer and drains every complete line before re-`select()`-ing. PLUS: every render log self-documents its runtime — mlx/mlx-metal version + Apple chip + macOS — surfaced in `/status`, the `helper ready ·` line, and a standalone `runtime |` line, the exact data needed to triangulate the remaining MLX-numerical "mosaic")**. **v3.0.11 is on `beta`, validated on the dev panel (handshake fix confirmed + clean 58 s T2V render end-to-end), pending promote to public.** See §4 for the full version history. The May-17 Codex C+ UI restructure (capability tiers, Q4 surface, Character as 5th mode pill, accel kill, HQ-speed move) and the Train-tab / LoRA-chrome work that followed are all baseline now, folded into v3.0.x. There is no `v2.0.6` tag.
Current `dev` head: see `git log -1` for the live SHA. `dev` tracks `beta/main` (private repo — see §1).
diff --git a/mlx_ltx_panel.py b/mlx_ltx_panel.py
index afbf4bc..e8d1de4 100644
--- a/mlx_ltx_panel.py
+++ b/mlx_ltx_panel.py
@@ -4285,6 +4285,9 @@ class WarmHelper:
stdin=subprocess.PIPE, stdout=subprocess.PIPE, stderr=subprocess.STDOUT,
text=True, bufsize=1, start_new_session=True,
)
+ # Fresh fd → drop any bytes carried over from a prior helper's pipe
+ # so _read_until's line buffer starts clean for this process.
+ self._read_carry = b""
ready = self._read_until(["ready", "error", "exit"], timeout=120)
if not ready or ready.get("event") != "ready":
raise RuntimeError(f"helper failed to start: {ready}")
@@ -4293,14 +4296,21 @@ class WarmHelper:
k: ready.get(k) for k in (
"ltx_version", "ltx_version_expected", "ltx_version_match",
"model", "gemma", "low_memory",
+ "mlx_version", "mlx_metal_version", "chip", "macos",
)
}
_vtag = ""
if ready.get("ltx_version") is not None:
_vtag = (f" · ltx-2-mlx={ready.get('ltx_version')}"
- + ("" if ready.get("ltx_version_match") else " ⚠️SKEW"))
+ + ("" if ready.get("ltx_version_match") else " SKEW"))
+ # Self-documenting env on the ready line — mlx + chip are the data we
+ # need on mosaic / garbled-output reports (an MLX numerical bug per
+ # chip/mlx, not a crash). ASCII only (emoji here can break stdout).
+ _env = (f" · mlx={ready.get('mlx_version')}" if ready.get("mlx_version") else "")
+ if ready.get("chip"):
+ _env += f" · {ready.get('chip')}"
push(f"helper ready · model={ready.get('model')} · "
- f"low_memory={ready.get('low_memory')}{_vtag}")
+ f"low_memory={ready.get('low_memory')}{_vtag}{_env}")
def _read_until(self, target_events: list[str], timeout: float | None = None,
log_hook: callable | None = None,
@@ -4320,10 +4330,30 @@ class WarmHelper:
deadline = time.time() + timeout if timeout else None
# Poll-and-check loop: blocking readline() used to mean a hung helper
# froze the worker thread until /stop. select() with a small interval
- # gives us deterministic deadline enforcement; readline() is only
- # called once we know there's data waiting.
+ # gives us deterministic deadline enforcement.
+ #
+ # CRITICAL (2026-06-05): we read the RAW fd with os.read() and split
+ # lines ourselves instead of select()+stdout.readline(). The old code
+ # mixed select() on the OS fd with a buffered TextIOWrapper.readline().
+ # When the helper emits a burst — e.g. a "log" line immediately
+ # followed by "ready" — a single readline() pulls BOTH lines off the
+ # pipe into Python's userspace buffer and returns only the first. The
+ # second ("ready") then sits in the TextIOWrapper buffer, NOT on the
+ # OS fd, so select() never reports it readable; if the helper then
+ # goes silent (exactly what it does after "ready"), _read_until hung
+ # for the full timeout → "helper failed to start: None". This was
+ # dormant for as long as "ready" was the helper's first emitted event;
+ # any pre-ready line (the version-skew log, the runtime fingerprint)
+ # exposed it. os.read() only ever returns bytes select() already saw,
+ # and we drain EVERY complete line from the carry buffer before
+ # waiting on select() again — so no line is ever stranded.
poll_interval = 0.5
- stdout = self.proc.stdout
+ try:
+ fd = self.proc.stdout.fileno()
+ except (OSError, ValueError):
+ return None
+ if not hasattr(self, "_read_carry"):
+ self._read_carry = b""
while True:
if deadline and time.time() > deadline:
return None
@@ -4334,18 +4364,25 @@ class WarmHelper:
synth = panic_check()
if synth is not None:
return synth
- rlist, _, _ = select.select([stdout], [], [], poll_interval)
- if not rlist:
- continue # idle slice — re-check deadline
- try:
- line = stdout.readline()
- except (OSError, ValueError):
- # Pipe closed underneath us (kill from another thread).
- return None
- if not line:
- # EOF — helper closed stdout (likely crashed or was killed).
- return None
- line = line.strip()
+ nl = self._read_carry.find(b"\n")
+ if nl < 0:
+ # No complete line buffered — wait for more bytes on the fd.
+ rlist, _, _ = select.select([fd], [], [], poll_interval)
+ if not rlist:
+ continue # idle slice — re-check deadline
+ try:
+ chunk = os.read(fd, 65536)
+ except (OSError, ValueError):
+ # Pipe closed underneath us (kill from another thread).
+ return None
+ if not chunk:
+ # EOF — helper closed stdout (likely crashed or was killed).
+ return None
+ self._read_carry += chunk
+ continue # loop back to drain complete lines from the buffer
+ raw = self._read_carry[:nl]
+ self._read_carry = self._read_carry[nl + 1:]
+ line = raw.decode("utf-8", "replace").strip()
if not line:
continue
try:
@@ -8079,6 +8116,12 @@ class Handler(BaseHTTPRequestHandler):
payload["ltx_version"] = HELPER.ready_info.get("ltx_version")
payload["ltx_version_expected"] = HELPER.ready_info.get("ltx_version_expected")
payload["ltx_version_match"] = HELPER.ready_info.get("ltx_version_match")
+ # Runtime fingerprint (mlx/chip/macOS) for triaging the "mosaic"
+ # MLX-numerical bug — surfaces in every bug report's /status.
+ payload["mlx_version"] = HELPER.ready_info.get("mlx_version")
+ payload["mlx_metal_version"] = HELPER.ready_info.get("mlx_metal_version")
+ payload["chip"] = HELPER.ready_info.get("chip")
+ payload["macos"] = HELPER.ready_info.get("macos")
# Per-kind avg ETA: image jobs are 30s–2min, video jobs are
# 5–30min. Computing queue ETA from one mixed avg makes an
# image queued after a few videos show "~30 min" — the
diff --git a/mlx_warm_helper.py b/mlx_warm_helper.py
index bfef4a8..7427074 100644
--- a/mlx_warm_helper.py
+++ b/mlx_warm_helper.py
@@ -1774,6 +1774,51 @@ if not _LTX_VERSION_INFO["match"]:
f"against {_LTX_EXPECTED_VERSION}; behavior on this version is "
f"unvalidated. {_LTX_VERSION_INFO['note']}".strip())})
+# ---- runtime fingerprint (mlx / chip / OS) ----------------------------------
+# Every render log then self-documents the exact environment — the data we keep
+# having to ask for on "mosaic" / garbled-output reports. Those are an MLX
+# numerical-correctness issue on specific chip+mlx combos (the render completes
+# and writes a normal-size file full of garbage pixels — not a crash, OOM, or
+# corrupt weights), so the mlx/mlx-metal version and the Apple chip are exactly
+# what's needed to triangulate. Never raises.
+def _detect_runtime_env() -> dict:
+ env = {"mlx": None, "mlx_metal": None, "mlx_lm": None,
+ "chip": None, "macos": None, "arch": None}
+ try:
+ import importlib.metadata as _md
+ for _k, _dist in (("mlx", "mlx"), ("mlx_metal", "mlx-metal"), ("mlx_lm", "mlx-lm")):
+ try:
+ env[_k] = _md.version(_dist)
+ except Exception:
+ pass
+ except Exception:
+ pass
+ try:
+ import platform as _pf
+ env["arch"] = _pf.machine()
+ env["macos"] = _pf.mac_ver()[0] or None
+ except Exception:
+ pass
+ try:
+ import subprocess as _sp
+ _chip = _sp.run(["sysctl", "-n", "machdep.cpu.brand_string"],
+ capture_output=True, text=True, timeout=3).stdout.strip()
+ env["chip"] = _chip or None
+ except Exception:
+ pass
+ return env
+
+
+_RUNTIME_ENV = _detect_runtime_env()
+# ASCII only — this is emitted to the helper's stdout, which the panel reads to
+# parse events; a non-ASCII byte there can break the read on a non-UTF-8 locale
+# (the same failure mode the version-skew emoji had). No "·" / emoji here.
+emit({"event": "log",
+ "line": (f"runtime | mlx={_RUNTIME_ENV.get('mlx')} "
+ f"mlx-metal={_RUNTIME_ENV.get('mlx_metal')} | "
+ f"chip={_RUNTIME_ENV.get('chip')} | "
+ f"macOS={_RUNTIME_ENV.get('macos')} ({_RUNTIME_ENV.get('arch')})")})
+
# ---- ready -------------------------------------------------------------------
emit({
"event": "ready",
@@ -1784,6 +1829,10 @@ emit({
"ltx_version": _LTX_VERSION_INFO["version"],
"ltx_version_expected": _LTX_EXPECTED_VERSION,
"ltx_version_match": _LTX_VERSION_INFO["match"],
+ "mlx_version": _RUNTIME_ENV.get("mlx"),
+ "mlx_metal_version": _RUNTIME_ENV.get("mlx_metal"),
+ "chip": _RUNTIME_ENV.get("chip"),
+ "macos": _RUNTIME_ENV.get("macos"),
})