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.
Python ai-filmmakingai-videoai-video-generatorapple-siliconhailuoimage-to-videolip-synclocal-ailora-trainingltx-2ltx-2-5ltx-videomacosminimax-h3mlxmusic-generationoffline-aipinokiotext-to-videovideo-generation
release(v4.19.4): renders work again where a library update broke them
mrbizarroda1006cbb97e
diff --git a/CLAUDE.md b/CLAUDE.mdindex f5c1fc2..3538c79 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -2,16 +2,17 @@This file is the single source of truth for how an AI assistant shouldwork on this codebase. Read it first, every session, before touching-any file. The generic Pinokio scaffolding starts at "## Generic Pinokio-Development Guide" further down — that's the upstream template. This top-section overrides it where they conflict.+any file. Generic Pinokio launcher rules live in Pinokio's own guide+(`CLAUDE.md` / `AGENTS.md` in the Pinokio home, e.g. `~/pinokio/CLAUDE.md`,+plus `~/pinokio/prototype/PINOKIO.md`); this file overrides it where they+conflict.---## 0. Current state — read `docs/STATE.md` first**THE RELEASE FACTS IN THIS SECTION ARE OLD.** `VERSION` on this branch and-`docs/STATE.md` are the two things that are current; the v3.0 history below is+`docs/STATE.md` are the two things that are current; the v3.0 history in `docs/HISTORY.md` iskept as background and nothing else. As of 2026-08-19: `VERSION` reads**4.6.0**, and public `main` is at **v4.5.0** — v4.6.0 was promoted andwithdrawn the same day (the Editor shipped before the owner had cut with it),@@ -19,99 +20,7 @@ so what a user can install and what this branch is are two different numbers.Which release the front page advertises, and when v4.6.0 goes back out, arethe owner's calls; do not settle them from a doc-hygiene pass.-### Historical — the v3.0 line--Public release was **v3.0.6**. The v3.0 line launched 2026-05-23 and has-shipped six patch releases: v3.0.0 (Characters/Voice/Image Studio/A2V) →-v3.0.1 (FFLF crash fix) → v3.0.2 (Boost/Turbo accel restored after a-2-month silent regression) → v3.0.3 (HiDream hidden, issue #15) → v3.0.4-(CivitAI SSL cert) → v3.0.5 (A2V kwarg signature shim, #5) → v3.0.6-(deep-review hardening: CivitAI token-leak fix, dead-HDR revival,-GPU-contention guard, boot version-gate). Published git tags: `v2.0.0`–-`v2.0.5` then `v3.0.0`–`v3.0.6` — there is **no `v2.0.6` tag** (that was-the dev codename that became v3.0.0). The `VERSION` file should read-`3.0.6`. Versioning: `3.0.x` for patches. Pre-2.0 commit messages /-comments still use the `Y1.NNN` counter (Y1.001 → Y1.039) — historical;-do not introduce new `Y` labels.--The authoritative current engineering snapshot is `docs/STATE.md`-(current capabilities, version history, known bugs). The `## 2.0`-capability list-below is retained as historical baseline — everything in it shipped; the-v3.0 additions (Characters, voice LoRA, Image Studio, A2V, Train tab,-capability tiers) are now baseline too.--### What ships in 2.0 (capabilities checklist)--- **Four modes**: T2V, I2V, FFLF (keyframe interpolation), Extend.-- **Joint audio + video** in a single LTX 2.3 forward pass — sound is- generated WITH the video. Lip-sync, footsteps, ambient noise all- align at the frame level. mlx 0.31.1 pin is what keeps the vocoder- output at healthy levels (-9 to -15 dB peak on dialogue prompts).-- **Quality tiers**: `quick` / `balanced` / `standard` / `high`. The- earlier `draft` key was renamed; do not reintroduce it. `high` =- Q8 two-stage HQ pipeline + TeaCache, requires Q8 download.-- **Speed modes** for Standard renders: `exact` (full sampler) /- `boost` (skip up to 2 stable middle steps via adaptive caching) /- `turbo` (skip up to 3). 23–34 % wall-time savings on stable scenes.- Disabled for High, Extend, and FFLF where step-skipping breaks- quality contracts.-- **Sharp upscale** = PiperSR (CoreML) on the Apple Neural Engine.- Real x2 detail recovery before the ffmpeg fit/encode tail; ~26 s- overhead on a 5 s × 1024×576 native. The earlier "model" upscale- path (LTX latent x2) was retired in Y1.026; it remains hidden- behind `LTX_ENABLE_MODEL_UPSCALE=1` for lab archaeology only.-- **VAE temporal streaming** — long clips no longer freeze at the- final decode. Patch in `patch_ltx_codec.py` defaults to- `LTX_VAE_STREAMING=auto`: streams when latent frames > 121 (≈ 5 s),- full-decodes shorter clips. Helper-side env-var override keeps- installs that haven't re-applied the patch on the right path too.-- **Filtered hf downloads** (Y1.024+): Q4 ≈ 20 GB, Q8 ≈ 37 GB,- Gemma ≈ 7.5 GB, optional spatial upscaler ≈ 1 GB. Older builds- pulled the full upstream repos and bloated to Q4=56 GB / Q8=82 GB- by including duplicate transformer variants and unused upscalers.- `update.js` deletes the dupes on existing installs.-- **Hardware-tier auto-config** (`base` / `standard` / `high` / `pro`)- with realistic per-tier time estimates surfaced on the Quality- pills. Compact-tier users see honest "~12 min" instead of M-Studio- numbers.-- **Now-card progress bar** (Y1.039) — phase-aware, denoise-step-aware.- Computed server-side from history bucket + helper log signals.- Replaces the old `elapsed / global_avg` ratio that mis-paced both- Quick and High renders.-- **Gallery race-free** (Y1.039) — `list_outputs()` skips files that- ffmpeg is still writing (in-flight skip + 2 s mtime cutoff), and- the `/file` URL carries an `&v=<mtime>` cache-bust so the browser- fetches the freshest bytes when a file is replaced.-- **CivitAI LoRA browser** built into the panel. `mlx_models/loras/`- is scanned at boot; sidecar JSON metadata travels with each safetensors.-- **Phosphene 2.0 release badge** — violet `2.0` chip next to the- wordmark in the panel header. Distinct from the amber `DEV` profile- badge so dev/prod tabs are distinguishable at a glance.--### Empirical benchmarks (M4 Max 64 GB, "Comfortable" tier)--All numbers are real wall-clock from sidecar `elapsed_sec` on Y1.039 /-v2.0.0 runs today. Output mp4 carries audio in every case.--| Config | Frames | Wall |-|---|---|---|-| T2V Quick · exact · 640×480 | 121 (5 s) | ~ 2 m 14 s |-| T2V Standard · exact · 1280×704 | 121 (5 s) | ~ 7 m 40 s |-| T2V Standard · boost · 1280×704 | 121 (5 s) | ~ 6 m 20 s |-| T2V Standard · turbo · 1280×704 | 121 (5 s) | ~ 5 m 26 s |-| T2V High Q8 · 1280×704 | 121 (5 s) | ~ 11 m 51 s |-| T2V Balanced · turbo · 720p Sharp | 121 (5 s) | **~ 3 m 30 s** |-| T2V Balanced · turbo · 720p Sharp | 241 (10 s) | **~ 8 m 07 s** |-| I2V Standard · exact · 1280×704 | 121 (5 s) | ~ 7 m 51 s |-| I2V Balanced · turbo · 720p Sharp | 121 (5 s) | ~ 3 m 37 s |-| I2V Balanced · turbo · 720p Sharp | 241 (10 s) | ~ 8 m 26 s |-| FFLF · clamped to 768 px (Comfortable cap) | 121 (5 s) | ~ 5 m 29 s |-| Extend · 768 px (Comfortable cap), +3 s | source 121 → output 184 | ~ 15 m 50 s |--The marquee number for the launch thread is the-**Balanced + Turbo + 720p Sharp** recipe: 5-sec clip in 3 m 30 s, 10-sec-in 8 m 07 s. That's the recommended default for "fast HD with audio".+Full v3.0 history, the 2.0 capability checklist and benchmark table: `docs/HISTORY.md`.### Repository layout (now — both clones documented)@@ -252,10 +161,11 @@ These are not arbitrary — every pin is a paid lesson:| Pin | Why ||---|---|| `python>=3.11` (force `uv venv --python 3.11`) | Pinokio's `venv:` shortcut defaults to conda's base 3.10. ltx-core-mlx requires `>=3.11`. |-| `mlx==0.31.1` | mlx 0.31.2 introduced a numerical regression that attenuates LTX 2.3 vocoder output by ~22 dB. Verified: same model + same prompt + same seed → -42 dB peak on 0.31.2 vs -9 dB peak on 0.31.1. **2026-08-28 — 0.32.1 / 0.32.2 measured and held back, on MEMORY, not audio.** The audio blocker is 0.31.2-specific and gone by 0.32 (isolated vocoder delta **0.000001 dB**; five renders per arm: max_volume -1.7 vs -1.8 dB, -9.2 vs -9.3 LUFS, no time shift — claimed 22 dB, measured 0.1). Speed is real too: Q8 1024×576 121f **139.8 s → 133.6 s (-4.5%)**, all in DiT load + VAE decode. What holds it back: 0.31.1's peak footprint tracks the WORKLOAD, 0.32.x's tracks the MACHINE — it takes ~95% of the ceiling MLX derives from RAM (`0.95 * hw.memsize`, identical formula on both), so it scales down with the Mac but never stops filling it. `/usr/bin/time -l` peak, same prompt/seed/dims, MLX memory+cache limits set to each Mac's derived value: Q4 768×432 — 16 GB **17.41 → 20.35** (0.32.2: 19.35), 32 GB **25.66 → 33.18** (97% of physical), 64 GB **25.53 → 54.28**; Q8 1024×576 — 48 GB **39.49 → 49.95** (97% of physical). On the 64 GB box the Q4 render moved system pressure **58% → 84%** with +1.5 GB swap, the Q8 one hit **87%** — past the 82% at which `plan_memory_policy()` forces the streamed decode (~30 s on a 5 s clip, more than the 4.5% the move earns). **Ruled out:** Metal residency sets (new in 0.32) — `MLX_RESIDENCY_SET_MAX_PCT=0` reproduces the footprint to within 300 KB over three runs. The growth is allocator **cache**, so an explicit `mx.set_cache_limit()` is the prerequisite — **shipped, on this pin, ahead of any version move**: `mlx_warm_helper.py` now caps the cache at **one eighth of physical RAM** (floor 2 GiB, ceiling 8 GiB), applied at helper start and re-asserted before every render because the pipelines drop it to 0 on paths we do not take. On 0.31.1 that is Q4 768x432 121f **25.53 -> 16.50 GB for 71.45 -> 68.84 s** and Q8 1024x576 at the 48 GiB tier **39.49 -> 25.39 GB for 139.84 -> 138.71 s**, both sha256-identical to the uncapped render. **And the pin cannot move alone** — see `scripts/check_post_update.js`. **2026-08-28, second pass: the cap shipped and the move was REFUSED AGAIN.** With the policy applied to both versions, 0.32.1's peak as a share of physical RAM is 16 GiB **101% → 116%**, 32 GiB 75% → 68%, 48 GiB Q8 **77% → 82%**, 64 GiB **37% → 41%** — three of four tiers worse than 0.31.1 uses today, and the Comfortable 48 GiB tier lands ON the 82% line `plan_memory_policy()` treats as pressured. The cap cannot reach it because the excess is not cache: at an identical cap, 0.32.1's **active** memory is +12.0 GB on Q4 and +29.2 GB on Q8. Cache **0** does get it under (Q8@48 GiB 32.25 GB, Q4@16 GiB 17.04 GB) and erases the entire speed win at the same time. There is no cache setting where 0.32.1 beats 0.31.1+policy on both axes, so mflux stays at 0.18.0 too. |+| `mlx==0.31.1` | 0.31.2 attenuates the LTX 2.3 vocoder ~22 dB (-42 dB vs -9 dB peak, same seed). 0.32.x fixed audio but was REFUSED twice (2026-08-28): its active memory is higher, putting 3 of 4 RAM tiers at a higher share of physical RAM and the 48 GB tier on the 82% pressure line. `mlx_warm_helper.py` caps the MLX cache at 1/8 RAM (2–8 GiB). mflux stays 0.18.0. **The pin cannot move alone:** mlx and mflux constrain each other — move both in ONE commit; `scripts/check_post_update.js` (`PIN_PAIR`) is the gate. Full measurements: `docs/DEPENDENCY_PINS.md`. || `mlx-lm==0.31.1` `mlx-metal==0.31.1` | Same release line, kept consistent with mlx. || `huggingface-hub>=1.0` | `hf` CLI replaced `huggingface-cli`; older Pinokio bundles ship < 1.0. |-| `ltx-2-mlx` PINNED to the FORK TAG **`v0.14.19+ltx25.7`** (`mrbizarro/ltx-2-mlx` = v0.14.19 `1192051` + the LTX-2.5 port + the schedule/sampler/live-preview work + the i2v anchor re-pin on BOTH loops + `+ltx25.7`: IC-LoRA `source_video=`, the seam Upscale ×2 renders through — the tag's own history is in `scripts/pinokio/ltx_checkout.sh`) | **The pin is a TAG and it lives in `scripts/pinokio/ltx_checkout.sh`**, which is the ONE checkout implementation both lanes call (install.js dispatches it; scripts/post_update.sh calls it). It was a bare SHA through v3.8.3 and was reachable only by luck — a force-push would have stranded every install with an un-fetchable pin and a dead Update button. `check_ltx_pin.js` is the gate. The packages report **`0.14.19+ltx25.7`**; `_LTX_EXPECTED_VERSION` in mlx_warm_helper.py must equal that string or every render logs VERSION SKEW — move the two together. This pin is what lets **LTX-2.5 render through the panel**, and on **dev/beta** 2.5 is the registry DEFAULT (2.3 stays installed, selectable via `LTX_MODEL_VERSION=ltx23`). **v3.8.x did NOT register `ltx25` at all** and shipped 2.3 as the only generation, because the 2.5 weight packs were not publicly downloadable when it was cut — a fresh install would have booted into a generation it could not fetch. They are published now, and **v4.0.0 closes that divergence**: 2.5 is the registered default everywhere. If you ever need to curate a release back to a single generation, it is one `MODEL_VERSIONS` dict plus its three `required_files.json` rows (watch the `kind: "base"` trap: any base row is mandatory for an install to read complete, in the panel *and* in `pinokio.js`). The **pin diverged for the same reason**: v3.8.x shipped `871694d` / `0.14.19+ltx25.1`, one commit behind, because `e6be9d6` (the 2.5 sampler + stage-2 schedule, below) had no 2.3 regression evidence behind it at cut time. It does now — a 2.3 sha256-identity pair across the change — so the next release should choose the pin deliberately rather than inherit either. The base tag v0.14.19 landed 2026-08-11 (a catch-up from v0.14.8, itself a 2026-06-01 catch-up from v0.14.0). **STAY PINNED** — this is NOT "main HEAD", and not upstream's tip either. The v0.14.8 bump had pulled dgrauet's native `_pre_denoise_flush` (the Metal-watchdog fix for the I2V "mosaic" on memory-pressured Macs, #17), budget-aware VAE decode tiling and first-class `frame_rate`, which cut us from 7 runtime patches to 1 (codec-only). The v0.14.19 bump keeps that shape and adds: checkpoint-read `av_ca_timestep_scale_multiplier` (0.14.11 — **audio/dialogue weighting changes on every render**, toward upstream parity, plus `LTXModelConfig.from_checkpoint_dir()`), `frame_rate` forwarded at the A2V/lipdub call sites and no more shortest-stream mux truncation (0.14.15), quantized transformers at any `group_size` (0.14.16), and GPU-watchdog explanation + DiT-freed-before-VAE-decode + a Gemma cache-limit fix (0.14.19). **The `+ltx25.2` bump (2026-08-12) is the first one that changes what a 2.5 render computes**, and only a 2.5 render: (a) the **euler-ancestral sampler is finally REACHED** — it had been implemented with 48 tests and zero callers, so every prior 2.5 render silently used the 2.3 Euler step, against upstream's own `ANCESTRAL_SAMPLER_SINCE_VERSION = (2, 5)` and all three official ComfyUI 2.5 templates; keyframe/flf2v deliberately stays on Euler because the flf2v template pins eta to 0. (b) **stage 2's first sigma is now the vendor's 0.85**, read from `video_ltx2_5_t2v.json` node 395, where we had been using 2.3's 0.909375 — a refine pass starting at the wrong noise level. Both are version-keyed off the checkpoint's own `model_version`, and 2.3 output is proven **sha256-identical** before and after. **No model re-download**: 0.14.13+ prefers a versioned `transformer-distilled-*.safetensors` and falls back to the unversioned name, and update.js trims the `-1.1` variants, so file resolution is identical to v0.14.8. Bumping the pin further is a deliberate, tested operation — read the release notes, bump `_LTX_EXPECTED_VERSION` in mlx_warm_helper.py, smoke-test the matrix on dev, then bump BOTH install.js and update.js in one commit. **The `+ltx25.4` bump (2026-08-14, v4.0.2) is the i2v anchor.** The conditioning item was always built correctly — `frame_idx=0`, `strength=1.0`, `mask_value=0`, a hard latent replace — and both loops forced those tokens back into the model's **x0 estimate** every step. Under Euler that was sufficient by arithmetic accident: velocity `(x - x0)/sigma` is exactly 0 at a pinned token, so the step returns it unchanged. The **euler-ancestral** step 2.5 selects has no such property: it rescales every token by `alpha_next/alpha_down` and adds fresh Gaussian noise, unmasked. Measured on the real 2.5 schedule the anchor is **halved and buried under noise 0.86x its own scale after step 1**, so every forward from step 2 on saw garbage where the image should be and the composition was decided without it; the terminal step stamped the image back in, which is why the delivered frame 0 always matched while the clip was a different shot. The fix re-composites the **sample** against `clean_latent`/`denoise_mask` after the ancestral step at all three sites, guarded by the existing uniform-mask flags — the other half of what ComfyUI's 2.5 i2v graph does. Proven, not argued: **t2v at a fixed seed is sha256-identical** before and after (`fbf09533583c423ab9ad3c0a437aee3484f15c0c5cceb2b1fc4ecc6d59071abb`), and frame-vs-input normalised cross-correlation at seed 424242 moves **0.0934 -> 0.7878** (frame 36) and **0.0902 -> 0.7187** (frame 72) while frame 0 holds at ~0.975. Every Euler lane — 2.3 i2v, keyframe/flf2v with its deliberate `eta=0`, a2v, extend, restore, ic_lora, lipdub — never reaches the branch. **The `+ltx25.5` bump (2026-08-15, v4.0.7) closes that on res_2s too**, which is the lane 2.5's HQ tiers run: the owner reported a reference image producing a high-quality clip of something else on High / High-720p. `res2s_denoise_loop` takes `repin_masked_sample` (default False = the old bytes) and `ti2vid_two_stages_hq` resolves it **per generation**, so 2.5 anchors i2v for real while 2.3 is byte-identical BY CONSTRUCTION — the reason this was deferred in +ltx25.4 is answered by construction rather than by measurement. `denoise_loop` takes the same flag defaulting True, so passing False deliberately restores the drift: that is **Inspire**, shipped as an explicit i2v mode (`loose_reference` through `generate_two_stage`/`generate_and_save` on both pipelines, forwarded only when true). `tests/test_repin_masked_sample.py` pins all four directions. The historic `dcd639e (0.1.0)` detour broke the Extend `cfg_scale` API; do not revisit. |+| **`scripts/pinokio/engine_constraints.txt`** (the engine venv's known-good set: transformers <5.13, tokenizers <0.23, huggingface-hub 1.x, the mlx trio) | **Every** `uv pip install` / `pip install` into `ltx-2-mlx/env` passes it with `-c` — post_update.sh, ltx_engine_env.sh, mflux_pack.sh, a2v_stems_deps.sh, install_qwen.js, install_sharp.js; `check_post_update.js` fails the build on a bare one. **Never `--upgrade` a package with a deep tree** (litellm, smolagents, transformers, mflux): uv's `--upgrade` is eager and re-resolves everything under it. 4.19.4: `--upgrade litellm` moved tokenizers to 0.23.3, transformers <5.13 refused to import, and every render failed until a later step happened to move it back. |+| `ltx-2-mlx` PINNED to the FORK TAG **`v0.14.19+ltx25.7`** (`mrbizarro/ltx-2-mlx`) | **STAY PINNED** — not main HEAD, not upstream's tip. The pin is a TAG and lives in `scripts/pinokio/ltx_checkout.sh`, the ONE checkout implementation (install.js and `scripts/post_update.sh` both call it); `check_ltx_pin.js` is the gate. The packages report **`0.14.19+ltx25.7`**; `_LTX_EXPECTED_VERSION` in mlx_warm_helper.py must equal that string or renders log VERSION SKEW — move the two together. The pin is what lets LTX-2.5 render (registry default everywhere since v4.0.0; 2.3 stays selectable via `LTX_MODEL_VERSION=ltx23`). The `+ltx25.N` tags carry the 2.5 sampler/schedule, i2v anchor re-pin (both loops, incl. res_2s), and IC-LoRA `source_video=`; 2.3 output is proven sha256-identical across them. `repin_masked_sample=False` is deliberate (that is **Inspire**), not a bug to fix — the fork's `tests/test_repin_masked_sample.py` pins it. To curate a release to one generation: one `MODEL_VERSIONS` entry plus its `required_files.json` rows — and any `kind: "base"` row is mandatory for an install to read complete, in the panel *and* `pinokio.js`. To bump: read upstream notes, bump `_LTX_EXPECTED_VERSION`, smoke-test on dev, bump install.js and update.js in one commit. Per-tag history and proofs: `docs/DEPENDENCY_PINS.md`. The `dcd639e (0.1.0)` detour broke Extend `cfg_scale`; do not revisit. || `hatchling<1.32` (build-time only, `pip-build-constraints.txt`) | Not a runtime dep — the **wheel build backend** for the three vendored `ltx-*` packages. All three declare `readme = "../../README.md"`, which hatchling 1.32.0 turned into a hard error, so both installer paths died at `metadata-generation-failed` on *every* pinned tag from the day 1.32 shipped. **Both are now `uv pip install --build-constraints ../pip-build-constraints.txt`** — install.js always was, update.js as of the v3.8.0 port-back. **NOT `PIP_CONSTRAINT=`**: modern pip spawns its build-dependency sub-install with `_PIP_IN_BUILD_IGNORE_CONSTRAINTS=1` and drops the env constraint on purpose, so that spelling silently resolved hatchling 1.32.0 and failed anyway (proven on pip 26.1/26.2.1, relative and absolute paths). pip's `--build-constraint` flag would work but does not exist on older pips, and Update runs on venvs seeded years apart. Remove only when a pinned upstream tag stops pointing `readme` outside the package dir. |When changing a version, document the test that proved the new pin is OK.@@ -800,341 +710,9 @@ The thresholds are intentional. M-Studio 64 GB is the canonical"standard" hardware. Anything below 48 GB cannot fit Q8 weights(transformer-dev.safetensors is 19.18 GiB plus working tensors).-## 15a. `panel_settings.json` schema--User-controllable preferences. Persisted at `<repo>/state/panel_settings.json`-(Y1.004+); pre-Y1.004 lived at `<repo>/panel_settings.json` and is migrated-on first boot by `_migrate_state_dir()`. State directory is gitignored.--The whole `state/` dir is symlinked into Pinokio's fs.link drive so it-survives Reset → Reinstall (see "Persistent storage / fs.link" in install.js-+ update.js). All persisted-state files (`panel_settings.json`,-`panel_queue.json`, `panel_hidden.json`) live there.--Read at panel startup; mutated via `POST /settings`. The helper subprocess-inherits codec env vars from this at spawn — when settings change, the-panel kills the helper so the next job picks up new values.--```jsonc-{- "version": 2, // bumped from v1 when secrets added- // Metadata so the UI knows which preset to highlight as active.- // "custom" means pix_fmt + crf were set manually outside any preset.- "output_preset": "standard" | "archival" | "web" | "custom",- "output_pix_fmt": "yuv420p" | "yuv444p" | "yuv422p"- | "yuv420p10le" | "yuv422p10le" | "yuv444p10le",- "output_crf": "0".."30", // string (passed via env vars)-- // Secrets. Stored locally only, never sent over the network except- // as Authorization headers / ?token= URL params to the upstream- // services (civitai.com, huggingface.co). NEVER returned by GET- // /settings — the public response surfaces booleans only.- "civitai_api_key": "", // empty = not configured- "hf_token": "" // empty = not configured-}-```--### `GET /settings` security contract--The full settings dict — including `civitai_api_key` and `hf_token` —-is read by the backend only. The HTTP API exposes a *masked* view via-`get_settings_public()`:--```jsonc-{- "version": 2,- "output_preset": "standard",- "output_pix_fmt": "yuv420p",- "output_crf": "18",- "has_civitai_key": false, // bool, never the value- "has_hf_token": false // bool, never the value-}-```--This applies on every response that includes settings — success path,-validation errors, helper-restart confirmations. A user with the panel-proxied through ngrok / tunneled to the LAN never leaks their saved-secrets through a status poll.--### Token resolution priority--`_active_civitai_key()` and `_active_hf_token()` resolve the active-token in this order:--1. The saved value in `panel_settings.json` (set via the Settings- modal). This is the path normal users take.-2. The corresponding env var (`CIVITAI_API_KEY` / `HF_TOKEN`). Power- users with shell-level config keep working unchanged.--Empty string in #1 falls through to #2. The settings UI's "Clear"-button writes an empty string to #1, so a user who configured a key-in the UI and then wants to revert to env-var-based config can do-so cleanly.--For HF specifically, `huggingface_hub.snapshot_download` *also* reads-`~/.cache/huggingface/token` (the file `hf auth login` writes). We-don't override that file — if neither settings nor `HF_TOKEN` env is-set, the library falls back to that cached file. This means power-users who already ran `hf auth login` get gated LoRAs working without-touching the panel's token settings.--Preset table is the single source of truth, defined in `OUTPUT_PRESETS`-in `mlx_ltx_panel.py`:--| key | pix_fmt | crf | Approx 5s @ 1280×704 | Use case |-|---|---|---|---|---|-| `standard` ⭐ default | yuv420p | 18 | ~7 MB | Visually lossless, plays everywhere (X / IG / Discord) |-| `archival` (UI label "Video production") | yuv444p | 0 | ~50 MB | Mathematically lossless, full 4:4:4 chroma. For color grading, compositing, VFX, anywhere downstream re-encode is expected. Internal key kept as `archival` for backwards compat with settings files saved before the rename. |-| `web` | yuv420p | 23 | ~3 MB | Smallest, mobile / embedding |--`+faststart` is always applied (codec patch) regardless of preset, so-gallery thumbnails always render the first frame instantly.--When adding a new preset: edit `OUTPUT_PRESETS` in `mlx_ltx_panel.py`-and the `order` array in the settings modal JS (`openSettingsModal`).-The blurb shown in the UI is read from the server at modal-open time,-so server is the source of truth — no JS strings to keep in sync.--## 15b. LoRA system--LTX 2.3 supports LoRA adapters via the upstream `apply_loras()` function-in `ltx_core_mlx.loader.fuse_loras`. The fusion is **weight-level**: at-pipeline load time, each LoRA's `(lora_A, lora_B)` matrix pair is-multiplied + added to the corresponding base-model weight, modified in-place, then quantized. This is *not* a runtime adapter — switching-LoRAs requires reloading the pipeline.--### Integration hook--The base `TextToVideoPipeline.load()` checks-`getattr(self, "_pending_loras", None)` and, if present, calls-`_fuse_pending_loras(transformer_weights, lora_paths)` before-quantizing the transformer. Set `pipe._pending_loras = [(path, strength), ...]`-between construction and the first job.--The wrapper in `mlx_warm_helper.py:_attach_loras` does this. It also-resolves HuggingFace repo IDs (`Lightricks/LTX-2.3-22b-IC-LoRA-HDR`)-to local files via `snapshot_download`, picking the largest-`.safetensors` in the repo (LoRA repos sometimes ship auxiliary files-like scene embeddings alongside the main weights).--### Pipeline cache invalidation--`get_pipe(kind, loras=...)` keys the cache on `(kind, frozen LoRA set)`.-Changing the LoRA set forces a pipeline rebuild — the cached pipeline's-weights have the previous LoRA set fused in and there's no clean way-to "unfuse." Cost is the standard ~30s pipeline reload.--The frozen LoRA set is order-insensitive (set hash, not list hash) —-fusion is commutative so `[A, B]` and `[B, A]` produce identical-weights and should hit the same cache entry.--### `mlx_models/loras/` directory--User-installed LoRAs live as `<name>.safetensors` files at the install-root's `mlx_models/loras/` directory. An optional sidecar JSON next to-each `.safetensors` carries display metadata:--```jsonc-{- "name": "Crisp Enhance",- "description": "Sharper detail and edge enhancement.",- "trigger_words": [], // optional, prepended to prompt at submit- "recommended_strength": 0.8, // 0.0..1.5 typical, displayed as default in slider- "preview_url": "https://...", // optional, shown in the picker- "base_model": "LTXV 2.3",- "civitai_id": 2530917, // optional, for attribution- "civitai_version_id": 2844417,- "civitai_url": "https://civitai.com/models/2530917",- "downloaded_at": "2026-05-01T..."-}-```--Sidecar absent → panel falls back to the filename as the display name-and zero metadata. Sidecar shape matches the JSON `_civitai_download`-writes, so a CivitAI install lands a usable picker entry without any-hand-editing.--### Curated LoRA registry--`CURATED_LORAS` in `mlx_ltx_panel.py` lists Lightricks' official LoRAs-that we know about. Currently:--| key | repo | UI surface | Note |-|---|---|---|---|-| `hdr` | `Lightricks/LTX-2.3-22b-IC-LoRA-HDR` | "HDR" toggle in form | Hidden from picker (`is_hdr_toggle: True`); exposed as a plain checkbox |-| `motion-track` | `Lightricks/LTX-2.3-22b-IC-LoRA-Motion-Track-Control` | Listed in picker | IC-LoRA, needs video conditioning (not yet wired in panel UI) |-| `union-control` | `Lightricks/LTX-2.3-22b-IC-LoRA-Union-Control` | Listed in picker | Same |--All three are **gated** on Hugging Face — users must accept the license-on the model page AND have a valid HF token (`hf auth login`) before-the helper's `snapshot_download` will work. The helper translates the-upstream `GatedRepoError` into a clear actionable error.--### Job spec extension--The `generate` and `extend` actions accept an optional `loras` param:--```jsonc-{- "action": "generate",- "id": "...",- "params": {- "mode": "t2v",- "prompt": "...",- "loras": [- {"path": "/abs/path/to/style.safetensors", "strength": 0.8},- {"path": "Lightricks/LTX-2.3-22b-IC-LoRA-HDR", "strength": 1.0}- ],- ...- }-}-```--Path may be a local file or an HF repo id. Strength is clamped to-±2.0 by the panel before sending; values outside the typical 0.0..1.5-range are usually nonsense and risk numerical issues during fusion.--### HDR toggle semantics--The `hdr` boolean on the job (separate from `loras`) is a UI shortcut.-Worker-side, `run_job_inner` resolves it to-`{"path": "Lightricks/LTX-2.3-22b-IC-LoRA-HDR", "strength": 1.0}`-and appends to the LoRA list before calling the helper. Users see-"HDR" as a feature; the LoRA implementation is hidden.--### CivitAI bridge--CivitAI's REST API is the de-facto LoRA distribution hub for LTX 2.3.-Two endpoints proxy through the panel:--- `/civitai/search` filtered to `baseModels=LTXV 2.3` (the canonical- string CivitAI uses for LTX-2.3 LoRAs as of 2026-05). Cursor-paginated.-- `/civitai/download` streams a `.safetensors` into `mlx_models/loras/`- + writes a sidecar JSON.--Both endpoints accept an optional `CIVITAI_API_KEY` env var. As of 2025,-CivitAI requires a token for most LoRA downloads (search still works-without). The token goes in `?token=<key>` on the URL — many CDN hops-only honor that form, not the Authorization header.--### Adding a new curated LoRA--1. Edit `CURATED_LORAS` in `mlx_ltx_panel.py` with `id`, `name`,- `description`, `repo_id`, `default_strength`, and either- `is_hdr_toggle: True` (= surfaces as a header pill, hidden from- picker) or `False` (= shows in picker as a usable entry).-2. If `is_hdr_toggle`, also add the HTML toggle pill (next to "No- music"), the JS sync block, and the `make_job` resolution that maps- the boolean to the curated repo id.--## 16. `required_files.json` schema--Single source of truth for "what counts as installed." Read by:-- `pinokio.js` → menu rendering (Install vs Resume Install vs Start)-- `mlx_ltx_panel.py` → `/status` and per-job validation-- (indirectly) `install.js` and `download_q8.js` — their `hf download`- paths must match the `local_dir` declared here.--```jsonc-{- "_comment": "...",- "repos": [- {- "key": "q4" | "gemma" | "q8",- "kind": "base" | "optional", // "base" = blocks Start, "optional" = unlock features- "name": "human-readable label",- "blurb": "what this is for",- "repo_id": "<hf-org/repo>", // for `hf download`- "local_dir": "mlx_models/<repo-name>", // relative to install root- "size_gb": 25, // approximate, displayed in UI- "files": [ // every required file inside local_dir- "transformer-distilled.safetensors",- "connector.safetensors",- ...- ]- }- ],- "env": {- "marker_paths": [ // OR-checked; first existing path wins- "ltx-2-mlx/env/pyvenv.cfg", // canonical Pinokio install- "ltx-2-mlx/.venv/pyvenv.cfg", // alternate manual layouts- ...- ]- },- "min_size_bytes": 1024 // file must be >= this to count as "complete"-}-```--When the upstream model layout changes, **edit this file first**. The-menu, panel, and install scripts auto-pick up the change.--## 17. Helper protocol (panel ↔ helper)--The helper subprocess (`mlx_warm_helper.py`) speaks newline-delimited-JSON over stdin/stdout. The panel's `WarmHelper` class wraps it.--### Actions panel sends--```jsonc-// Generation request (T2V, I2V, I2V-clean-audio)-{ "action": "generate",- "id": "<job-id>",- "params": { "mode": "t2v"|"i2v"|"i2v_clean_audio",- "prompt": "...", "output_path": "...",- "height": 704, "width": 1280, "frames": 121,- "seed": 42, "steps": 8, "image": "<path>" } }--// Extend request-{ "action": "extend",- "id": "<job-id>",- "params": { "video_path": "...", "prompt": "...",- "extend_frames": 5, "extend_direction": "after",- "extend_steps": 12, "cfg_scale": 1.0,- "output_path": "...", "seed": 42 } }--// Keyframe (FFLF)-{ "action": "keyframe", "id": "...", "params": {...} }--// Prompt rewrite (Gemma)-{ "action": "enhance", "prompt": "..." }-```--### Events helper emits--```jsonc-{ "event": "ready", "model": "<path>", "low_memory": true } // on startup-{ "event": "log", "line": "free-form panel log line" } // any informational message-{ "event": "done", "id": "...", "output": "<path>",- "elapsed_sec": 33.6, "seed_used": 42 }-{ "event": "error", "id": "...", "error": "<message>",- "trace": "<python traceback>" }-{ "event": "exit", "reason": "python_normal_exit"- | "sigterm(15)"- | "sigterm(2)"- | "idle" } // graceful exit-{ "event": "enhanced", "original": "...", "enhanced": "..." } // /prompt/enhance result-```+## 15a–17. Reference — see `docs/PANEL_REFERENCE.md`-**No exit event + stdout pipe closes = non-graceful death** (SIGKILL,-SIGSEGV, SIGABRT, SIGBUS). The panel inspects `proc.poll()` returncode-and translates the negative signal number to a name in the user-facing-error.--### Step breadcrumb log lines--The helper emits these inside `generate`/`extend` actions so the panel-can localize a silent death to a phase:--```-step:get_pipe kind=t2v-step:get_pipe done-step:generate_and_save mode=i2v 1280x704 121f steps=8-step:generate_and_save done-```--When a job dies silently, the panel log's last `step:*` line tells you-which phase (pipeline init vs actual generation).+`panel_settings.json` schema and `GET /settings` secrets contract, the LoRA system (`mlx_models/loras/`, `CURATED_LORAS`, CivitAI bridge), `required_files.json` schema, and the panel↔helper JSON protocol. Edit `required_files.json` first when the model layout changes; `GET /settings` never returns secret values.## 18. Memory budget model@@ -1171,7 +749,7 @@ pipelines' own low-memory paths call `set_cache_limit(0)` and never put itback. Override with `LTX_MLX_CACHE_GIB` (a number in GiB, `0` for no cache,`off` for MLX's default). It takes about a third off the peak footprint ofevery render at no wall-clock cost, and `test_mlx_cache_policy.py` pins the-value at each tier. The numbers are in §4's mlx row.+value at each tier. The numbers are in `docs/DEPENDENCY_PINS.md` (mlx row).macOS `jetsam` is the OOM killer. It enforces memory pressure basedon a percentage that varies with paging activity, swap usage, and other@@ -1179,175 +757,7 @@ heuristics — there is no fixed "kill at X% pressure" rule. ClosingChrome, Slack, iOS Simulator before a Standard render is the safestsingle thing a user can do.-## 19. Debug recipes--### "Helper died silently — where did it die?"--```bash-# Scan the panel log for the last step:* breadcrumb-curl -s http://127.0.0.1:8198/status | python3 -c \- "import json,sys; [print(l) for l in json.load(sys.stdin)['log'] if 'step:' in l][-3:]"-```--If last step is `step:get_pipe` → death during pipeline init (model-load). Likely OOM or weight-corrupt. If last step is-`step:generate_and_save` → death during gen (denoise / VAE decode).-Likely OOM peak or Metal kernel issue.--For non-OOM crashes, check `~/Library/Logs/DiagnosticReports/python3.11_*.crash`-or `*.ips` from around the crash time.--### "Panel says port 8198 already in use"--```bash-lsof -nP -iTCP:8198 -sTCP:LISTEN # who has it-pkill -f mlx_ltx_panel.py # nuke all panels-```--Common cause: a previous manual `python mlx_ltx_panel.py` is still-running. Pinokio's start.js can't take over a port someone else owns.-**Don't spawn the panel manually unless you're going to kill it before-handing back.**--### "I edited the UI but the browser hasn't changed"--The frontend lives in files under `webapp/` (docs/ARCHITECTURE.md), and-what you must restart depends on which file:--- **CSS (`webapp/style/panel.css`) or JS (`webapp/js/*.js`)** — served- from disk on every request with `Cache-Control: no-cache`. NO panel- restart needed; just hard-refresh the browser (Cmd+Shift+R).-- **Markup (`webapp/index.html`)** — read ONCE at panel import (the- served page is pinned to the booted process on purpose; see the- build-stamp comment in the template). Restart the panel (Pinokio- Stop → Start, or `pkill -f mlx_ltx_panel.py` then Start), then- hard-refresh.-- **Python (`mlx_ltx_panel.py`, `panel/routes_*.py`)** — restart the- panel.--### "I edited the helper or a patch but nothing changed"--```bash-# 1. Re-apply patches (idempotent, applies to site-packages)-cd ~/pinokio/api/phosphene.git-./ltx-2-mlx/env/bin/python3.11 patch_ltx_codec.py--# 2. Restart the helper subprocess (panel keeps running)-curl -X POST http://127.0.0.1:8198/helper/restart--# 3. Submit a test job-curl -X POST http://127.0.0.1:8198/run \- -d "mode=t2v" -d "prompt=quick test" \- -d "width=512" -d "height=288" -d "frames=49" \- -d "steps=8" -d "quality=draft"--# 4. Wait for done-until [ "$(curl -s http://127.0.0.1:8198/status | python3 -c 'import json,sys;d=json.load(sys.stdin);print(0 if d.get(\"current\") else 1)')" = "1" ]; do sleep 5; done-```--### "How loud / clean is the audio in this clip?"--```bash-FFPROBE="/Volumes/Topaz Video AI 4.0.6/Topaz Video AI.app/Contents/MacOS/ffprobe"-FFMPEG="/Volumes/Topaz Video AI 4.0.6/Topaz Video AI.app/Contents/MacOS/ffmpeg"-"$FFMPEG" -i out.mp4 -af "volumedetect" -f null - 2>&1 | grep -E "max_volume|mean_volume"-```--Healthy on dialogue: `max_volume` between -2 and -15 dB. Below -25 dB-peak is the regression fingerprint — usually means a wrong mlx version.--### "Re-encode for X / web (yuv420p, faststart, 8 Mbps)"--```bash-"$FFMPEG" -y -i in.mp4 \- -c:v h264_videotoolbox -profile:v high -pix_fmt yuv420p \- -b:v 8M -maxrate 12M -bufsize 16M \- -movflags +faststart \- -c:a aac -b:a 192k \- out_x.mp4-```--X (Twitter) rejects yuv444p with a misleading "aspect ratio" error.-Use this recipe for any social upload.--### "Stuck queue / can't cancel"--```bash-curl -X POST http://127.0.0.1:8198/stop # cancel current job-curl -X POST http://127.0.0.1:8198/queue/clear # empty the queue-curl -X POST http://127.0.0.1:8198/helper/restart # nuke the helper-```--### "Force re-download a corrupt model file"--```bash-# Delete the file in question, then click Install in Pinokio (resumes-# only the missing files; intact ones are skipped via `hf` hash check).-rm ~/pinokio/api/phosphene.git/mlx_models/ltx-2.3-mlx-q4/<bad-file>.safetensors-# Then in Pinokio: Phosphene → Install (or Resume Install)-```--### "Force a different hardware tier for testing"--```bash-LTX_TIER_OVERRIDE=base ./run_panel.sh # pretend this Mac is < 48 GB-```--`run_panel.sh` actively unsets this on every run unless explicitly set-on the command line — there's a hard-learned bug history about leaked-overrides bleeding across panel restarts.--### "What does `/status` actually return?"--```bash-curl -s http://127.0.0.1:8198/status | python3 -m json.tool | head -60-```--Top-level keys: `running`, `paused`, `current`, `queue`, `history`,-`log`, `tier`, `memory`, `helper`, `download`, `repos_ready`,-`repos_total`, `base_available`, `q8_available`, `q8_missing`,-`comfy_pids`, `outputs`, `server_now`, `avg_elapsed_sec`.--## 20. Patch authoring template (`patch_ltx_codec.py`)--When adding a new patch:--```python-# ---- Patch N: <one-line summary> ---------------------------------------------# Why: <symptom + root cause + why this fix>. Reference upstream-# file:line and any external context (commit SHA, GitHub issue, paper).-PATCH_<NAME>_OLD = '''<exact text expected to be in the upstream file>'''-PATCH_<NAME>_NEW = '''<replacement text — include a `# PATCHED (LTX23MLX): ...` comment>'''-```--Then in `main()`:--```python-target = _find("<relative/path/to/upstream.py>")-outcome = apply_patch(- target, PATCH_<NAME>_OLD, PATCH_<NAME>_NEW,- marker="<unique substring that proves NEW is on disk>",- label="<NAME>",- upgrade_marker="<optional: substring that distinguishes a newer NEW from an older NEW>",-)-# If this patch is optional (don't fail install on drift):-if outcome in (OUTCOME_DRIFT, OUTCOME_MISSING):- print(" [<NAME>] note: ...", file=sys.stderr)- outcome = OUTCOME_ALREADY-outcomes.append(("<NAME>", outcome))-```--Conventions:-- `marker` is a substring **inside** `PATCH_<NAME>_NEW` that's unlikely- to appear in the unpatched file. Convention: include- `PATCHED (LTX23MLX...)` somewhere in the new text.-- `upgrade_marker` lets you ship a v2 of a patch without forcing users- to nuke their venv. Example: codec patch's `+faststart` was added- later; `upgrade_marker="+faststart"` distinguishes v1 (no faststart)- from v2 and rewrites the line in place.-- Patches that target an upstream code structure that may legitimately- vanish (e.g. an internal helper that gets refactored away) should be- marked **optional** in main() so install warns instead of fails.+## 19–20. Debug recipes and patch authoring — see `docs/DEBUG_RECIPES.md`## 21. Glossary@@ -1408,7 +818,7 @@ Tracked here so they don't get lost between sessions.a future attempt is a pin move plus this measurement, not are-derivation. What would change the answer is an upstream fix to0.32.x's active-memory appetite, not another knob on our side. Full- tables in the mlx row of §4 and in `install.js` above the pin. The old+ tables in `docs/DEPENDENCY_PINS.md` and in `install.js` above the pin. The old"bisect 0.31.1 → 0.31.2" task is retired — 0.32 fixed it upstream.- **A2V (audio-to-video) mode** — `ltx-2-mlx` upstream has`a2vid_two_stage.py` and `a2vid_two_stage_hq.py` but the panel@@ -1451,567 +861,12 @@ This heading is kept rather than deleted because the section it replacessurvived three months of "read CLAUDE.md first" sessions, teaching every oneof them about a subsystem it could not find.------# Generic Pinokio Development Guide--(Everything below this line is the upstream Pinokio scaffolding shipped-with every new project. Useful as a reference when working with the-launcher scripts but the Phosphene-specific rules above take-precedence on conflict.)--# Development Guide for Pinokio Projects--## Non-Negotiable Execution Workflow--To guarantee every contribution follows this guide precisely, obey this checklist **before any edits** and **again before finalizing**. Do not skip or reorder.-1. **AGENTS Snapshot:** Re-open this file and write down (in your working notes or response draft) the exact sections relevant to the requested task. No work begins until this snapshot exists.-2. **Destination Resolution:** Before creating or editing any Pinokio launcher files, resolve `PINOKIO_HOME` to an absolute path and record the intended destination root. If running outside Pinokio's own managed runtime, resolve in this order: `~/.pinokio/config.json` `home`, then `GET http://127.0.0.1:42000/pinokio/home` and use its `path` value, and if loopback is unreachable but `access` exists in `~/.pinokio/config.json`, retry the same request against `<protocol>://<host>:<port>/pinokio/home`, then the `PINOKIO_HOME` environment variable. If `PINOKIO_HOME` is still unresolved, stop and ask the user. Never silently use the current workspace as the launcher destination.-3. **Example Lock-in:** Identify the closest matching script in `~/pinokio/prototype/system/examples`. Record its path and keep it open while editing. Every launcher change must mirror that reference unless the user explicitly instructs otherwise.-4. **Pre-flight Checklist:** Convert the applicable rules from this document and `PINOKIO.md` at ~/pinokio/prototype/PINOKIO.md into a task-specific checklist (install/start/reset/update structure, regex patterns, menu defaults, log checks, destination path, etc.). Confirm each item is ticked **before** making changes.-5. **Mid-task Verification:** Any time you touch a Pinokio script, cross-check the corresponding example line to ensure syntax and structure match. Document the reference (example path + line) in your reasoning.-6. **Exit Checklist:** Before responding to the user, revisit the pre-flight checklist and explicitly confirm every item is satisfied. If anything diverges from the example or these rules, fix it first.--If any step cannot be completed, stop immediately and ask the user how to proceed. These six steps are mandatory for every session.--### Critical Pattern Lock: Capturing Web UI URLs--When writing `start.js` (or any script that needs to surface a web URL for a server):--1. **Always copy the capture block from an example such as `system/examples/mochi/start.js`.**-```javascript-on: [{- event: "/(http:\\/\\/[0-9.:]+)/",- done: true-}]-```--2. **Set the local variable using the captured match exactly as below (The regex capture object is passed in as `input.event`, so need to use the index 1 inside the parenthesis):**-```javascript-{- method: "local.set",- params: {- url: "{{input.event[1]}}"- }-}-```--3. Always try to come up with the most generic regex.-4. During the exit checklist, explicitly confirm that the `url` local variable is set via `local.set` API by using the captured regex object as passed in as `input.event` from the previous `shell.run` step.--Deviation from this pattern requires written approval from the user.--- Make sure to keep this entire document and `PINOKIO.md` at ~/pinokio/prototype/PINOKIO.md in memory with high priority before making any decision. Pinokio is a system that makes it easy to write launchers through scripting by providing various cross-platform APIs, so whenever possible you should prioritize using Pinokio API over lower level APIs.-- When writing pinokio scripts, ALWAYS check the examples folder (in ~/pinokio/prototype/system/examples folder) to see if there are existing example scripts you can imitate, instead of assuming syntax.-- When implementing pinokio script APIs and you cannot infer the syntax just based on the examples, always search the API documentation `PINOKIO.md` at ~/pinokio/prototype/PINOKIO.md to use the correct syntax instead of assuming the syntax.-- When trying to fix something or figure out what's going on, ALWAYS start by checking the `logs` folder before doing anything else, as mentioned in the "Troubleshooting with Logs" section.-- Finally, make sure to ALWAYS follow all the items in the "best practices" section below.--## Determine User Intent-If the initial prompt is simply a URL and nothing else, check the website content and determine the intent, and ask the user to confirm. For example a URL may point to--1. A Tutorial: the intent may be to implement a demo for the tutorial and build a launcher.-2. A Demo: the intent may be a 1-click launcher for the demo-3. Open source project: the intent may be a 1-click launcher for the project-4. Regular website: the intent may be to clone the website and a launcher.-5. There can be other cases, but try to guess.--## Working With Launchers--Apply this section only when the task is to create, modify, debug, review, or document a Pinokio launcher project.--If the request is not about launcher work, do not force an app-launcher vs plugin-launcher decision.--When the task does involve launcher work, first determine whether the request is for an app launcher or a plugin launcher. These are separate project types and must not be mixed.--### Mandatory Destination Resolution-- Before creating, editing, or moving any launcher files, resolve `PINOKIO_HOME` to an absolute path.-- If running outside Pinokio's own managed runtime, resolve `PINOKIO_HOME` in this order:- 1. `~/.pinokio/config.json` -> `home`- 2. `GET http://127.0.0.1:42000/pinokio/home` -> `path`- 3. If loopback is unreachable but `access` exists in `~/.pinokio/config.json`, retry the same request against `<protocol>://<host>:<port>/pinokio/home`- 4. `PINOKIO_HOME` environment variable-- Normalize the resolved value to an absolute path before using it.-- If neither source yields a valid `PINOKIO_HOME`, stop immediately and ask the user how to proceed. Do not guess. Do not silently fall back to the current workspace.-- If the current workspace is outside the resolved `PINOKIO_HOME/api` and `PINOKIO_HOME/plugin` trees, treat the current workspace only as source material, reference material, or evidence. Do not create the launcher in that workspace.-- Before any file creation, record and verify the exact target path:- - app launcher: `PINOKIO_HOME/api/<unique_name>`- - plugin launcher: `PINOKIO_HOME/plugin/<unique_name>`-- If the unique folder name is not obvious, ask the user before creating the target folder.--### 1. App launchers-- App launchers must live under `PINOKIO_HOME/api/<unique_name>`.-- App launchers are usually project-local launchers that manage one app in its own launcher/app folder.-- If you are already inside the target app launcher folder, build in that folder.-- If you are not already inside an app launcher folder, create a new folder under `PINOKIO_HOME/api/<unique_name>`.-- If the folder name is not obvious from the project or the user has not provided one, ask the user to confirm the folder name before creating it.-- Do not place app launchers under `PINOKIO_HOME/plugin`.--### 2. Plugin launchers-- Plugin launchers must live under `PINOKIO_HOME/plugin/<unique_name>`.-- Plugin launchers are reusable shared tools that are installed once and then used across many different folders.-- Standalone plugin launchers should keep `path: "plugin"` in the root `pinokio.js` so Pinokio installs them into `PINOKIO_HOME/plugin`.-- If you are already inside the target plugin launcher folder, build in that folder.-- If you are not already inside a plugin launcher folder, create a new folder under `PINOKIO_HOME/plugin/<unique_name>`.-- If the folder name is not obvious from the project or the user has not provided one, ask the user to confirm the folder name before creating it.-- Do not place plugin launchers under `PINOKIO_HOME/api`.-- When a plugin is meant to operate on the user's current project, its `run` step should target the caller's folder with `{{args.cwd}}` instead of the plugin folder itself.--### 3. Apply structure rules only after choosing the launcher type-- App launchers and plugin launchers are peers. Do not treat a plugin launcher as a special case of an app launcher, or vice versa.-- Decide the launcher type and destination folder first, then apply the project structure and script rules below.--## Project Structure--Pinokio projects normally follow a standardized structure with app logic separated from launcher scripts:--Pinokio projects follow a standardized structure with app logic separated from launcher scripts:--```-project-root/-├── app/ # Self-contained app logic (can be standalone repo)-│ ├── package.json # Node.js projects-│ ├── requirements.txt # Python projects-│ └── ... # Other language-specific files-├── README.md # Documentation-├── install.js # Installation script-├── start.js # Launch script-├── update.js # Update script (for updating the scripts and app logic to the latest)-├── reset.js # Reset dependencies script-├── pinokio.js # UI generator script-└── pinokio.json # Metadata (title, description, icon)-```--- Keep app code in `/app` folder only (never in root)-- Store all launcher files in project root (never in `/app`)-- `/app` folder should be self-contained and publishable--The only exceptions are serverless web apps---purely frontend only web applications that do NOT have a server component and connect to 3rd party API endpoints--in which case the folder structure looks like the following (No need for launcher scripts since the index.html will automatically launch. The only thing needed is the metadata file named pinokio.json):+Reference material moved out of this file (read when relevant):-```-project-root/-├── index.html # The serverless web app entry point-├── ...-├── README.md # Documentation-└── pinokio.json # Metadata (title, description, icon)-```--IMPORTANT: ALWAYS try to follow the best practices in the examples folder (~/pinokio/prototype/system/examples) instead of trying to come up with your own structure. The examples have been optimized for the best user experience.--## Launcher Project Working Directory--- The project working directory for a script is always the same directory as the script location.-- For example, when you run `shell.run` API inside `pinokio/start.js`, the default path for shell execution is `pinokio`.-- If the launcher files are in the project root path, then the default path for shell execution is the project root.-- Therefore, it is important to specify the correct `path` attribute when running `shell.run` API commands.--Example: in the following project structure:--```-project-root/-├── pinokio/ # Pinokio launcher folder-│ ├── start.js # Launch script-│ ├── pinokio.js # UI generator script-│ └── pinokio.json # Metadata (title, description, icon)-└─── backend/- ├── requirements.txt # App dependencies- └── app.py # App code-```--The `pinokio/start.js` should use the correct path `../backend` as the `path` attribute, as follows:--```-{- run: [{- ...- }, {- method: "shell.run",- params: {- message: "python app.py",- venv: "env",- path: "../backend"- }- }, {- ...- }]-}-```--## Development Workflow--### 1. Understanding the Project-- Check `SPEC.md` in project root. If the file exists, use that to learn about the project details (what and how to build)-- If no `SPEC.md` exists, build based on user requirements-### 2. Modifying Existing Launcher Projects-If we are starting with existing launcher script files, work with the existing files instead of coming up with your own.-- **Preserve existing functionality:** Only modify necessary parts-- **Don't touch working scripts:** Unless adding/updating specific commands-- **Follow existing conventions:** Match the style and structure already present-### 3. Try to adopt from examples as much as possible-- If starting from scratch, first determine what type of project you will be building, and then check the examples folder (~/pinokio/prototype/system/examples) to see if you can adopt them instead of coming up everything from scratch.-- Even if there are no relevant examples, check the examples to get inspiration for how you would structure the script files even if you have to write from scratch.-### 4. Writing from scratch as a last resort-If there are relevant examples to adopt from, write the scripts from scratch, but just make sure to follow the requirements in the next section.-### 5. Debugging-When the user reports something is not working, ALWAYS inspect the logs folder to get all the execution logs. For more info on how this works, check the "Troubleshooting with Logs" section below.--## Script Requirements--### 1. 1-click launchable-- The main purpose of Pinokio is to provide an easy interface to invoke commands, which may include launching servers, installing programs, etc. Make sure the final product provides ways to install, launch, reset, and update whatever is needed.--### 2. Write Documentation-- ALWAYS write a documentation. A documentation must be stored as `README.md` in the project root folder, along with the rest of the pinokio launcher script files. A documentation file must contain:- - What the app does- - How to use the app- - API documentation for programmatically accessing the app's main features (Javascript, Python, and Curl)--## Types of launchers-## 1. Launching servers-- When an app requires launching a server, here are the commonly used scripts:- - `install.js`: a script to install the app- - `start.js`: a script to start the app- - `reset.js`: a script to reset all the dependencies installed in the `install.js` step. used if the user wants to restart from scratch- - `update.js`: a script to update the launcher AND the app in case there are new updates. Involves pulling in the relevant git repositories installed through `install.js` (often it's the script repo and some git repositories cloned through the install steps if any)- - `pinokio.js`: the launcher script that ties all of the above scripts together by providing a UI that links to these scripts.- - `pinokio.json`: For metadata--Here's a basic server launcher script example (`start.js`). Unless there's a special reason you need to use another pattern, this is the most recommended pattern. Use this or adopt it as needed, but NEVER try something else unless there's a good reason you should not take this approach:--```javascript-module.exports = {- // By setting daemon: true, the script keeps running even after all items in the `run` array finishes running. Mandatory for launching servers, since otherwise the shells running the server process will get killed after the scripts finish running.- daemon: true,- run: [- {- // The "shell.run" API for running a shell session- method: "shell.run",- params: {- // Edit 'venv' to customize the venv folder path- venv: "env",- // Edit 'env' to customize environment variables (see documentation)- env: { },- // Edit 'path' to customize the path to start the shell from- path: "app",- // Edit 'message' to customize the commands, or to run multiple commands- message: [- "python app.py",- ],- on: [{- // The regular expression pattern to monitor.- // Whenever each "event" pattern occurs in the shell terminal, the shell will return,- // and the script will go onto the next step.- // The regular expression match object will be passed on to the next step as `input.event`- // Useful for capturing the URL at which the server is running (in case the server prints some message about where the server is running)- "event": "/(http:\/\/\\S+)/",-- // Use "done": true to move to the next step while keeping the shell alive.- // Use "kill": true to move to the next step after killing the shell.- "done": true- }]- }- },- {- // This step sets the local variable 'url'.- // This local variable will be used in pinokio.js to display the "Open WebUI" tab when the value is set.- method: "local.set",- params: {- // the input.event is the regular expression match object from the previous step- // In this example, since the pattern was "/(http:\/\/\\S+)/", input.event[1] will include the exact http url match caputred by the parenthesis.- // Therefore setting the local variable 'url'- url: "{{input.event[1]}}"- }- }- ]-}-```--## 2. Launching serverless web apps--- In case of purely static web apps WITHOUT servers or backends (for example an HTML based app that connects to 3rd party servers--either remote or localhost), we do NOT need the launcher scripts.-- In these cases, simply include `index.html` in the project root folder and everything should automatically work. No need for any of the pinokio launcher scripts. (Do-- You still need to include the metadata file so they show up properly on pinokio:- - `pinokio.json`: For metadata--## 3. Launching quick scripts without web UI--- In many cases, we may not even need a web UI, but instead just a simple way to run scripts.-- This may include TUI (Terminal User Interface) apps, a simple launcher-- In these cases, all we need is the launcher file `pinokio.js`, which may link to multiple scripts. In this case, there are no web apps (no serverless apsp, no servers), but instead just the default pinokio launcher UI that calls a bunch of scripts.-- Here are some examples:- - A pinokio script to toggle the desktop theme between dark and light- - Write some code (python or javascript or whatever)- - Write a `toggle.js` pinokio script that executes the code- - Write a `pinokio.js` launcher script to create a sidebar UI that displays the `toggle.js` so the user can simply click the "toggle" button to toggle back and forth between desktop themes- - A pinokio script to fetch some file- - Write some code (python or javascript or whatever)- - Write a `fetch.js` pinokio script that executes the code- - Write a `pinokio.js` launcher script to create a sidebar UI that displays the `fetch.js` so the user can simply click the "fetch" button to fetch some data.-- You still need to include the metadata file so they show up properly on pinokio:- - `pinokio.json`: For metadata--## API--This section lists all the script APIs available on Pinokio. To learn the details of how they are used, you can:-1. Check the examples in the ~/pinokio/prototype/system/examples folder-2. Read the `PINOKIO.md` at ~/pinokio/prototype/PINOKIO.md further documentation on the full syntax--### Script API--These APIs can be used to describe each step in a pinokio script:-- shell.run: run shell commands-- input: accept user input-- filepicker: accept file upload-- fs.write: write to file-- fs.read: read from file-- fs.copy: copy files-- fs.download: download files-- fs.link: create a symbolic link (or junction on windows) for folders-- fs.open: open the system file explorer at a given path-- fs.cat: print file contents-- jump: jump to a specific step-- local.set: set local variables for the currently running script-- json.set: update a json file-- json.rm: remove keys from a json file-- json.get: get values from a json file-- log: print to the web terminal-- net: make network requests-- notify: display a notification-- script.download: download a script from a git uri-- script.start: start a script-- script.stop: stop a script-- script.return: return values if the current script was called by a caller script, so the caller script can utilize the return value as `input`-- web.open: open a url in web browser-- hf.download: huggingfac-cli download API-### Template variables-The following variables are accessible inside template expressions (example `{{args.command}` in scripts, resulting in dynamic behaviors of scripts:-- input: An input is a variable that gets passed from one RPC call to the next-- args: args is the parameter object that gets passed into the script (via pinokio.js `params`). Unlike `input` which takes the value passed in from the immediately previous step, `args` is a global value that is the same through out the entire script execution.-- local: local variable object that can be set with `local.set` API-- self: refers to the script file itself (which is JSON or JavaScript). For example if `start.js` that's currently running has `daemon: true` set, `{{self.daemon}}` will evaluate to true.-- uri: The current script uri-- port: The next available port. Very useful when you need to launch an app at a specific port without port conflicts.-- cwd: The current script execution folder path-- platform: The current operating system. May be one of the following: `darwin`, `win32`, `linux`-- arch: The current system architecture. May be one of the following: x32, x64, arm, arm64, s390, s390x, mipsel, ia32, mips, ppc, ppc64-- gpus: array of available GPUs on the machine (example: `['apple']`, `['nvidia']`)-- gpu: the first available GPU (example: `nvidia`)-- current: The current variable points to the index of the currently executing instruction within the run array.-- next: The next variable points to the index of the next instruction to be executed. (null if the current instruction is the final instruction in the run array)-- envs: You can access the environment variables of the currently running process with envs object.-- which: Check whether a command exists and return its absolute path (example: `{{which('winget')}}`). This is the correct way to resolve command paths inside reproducible Pinokio scripts, including custom shell selection such as `shell: "{{which('bash')}}"`. If you are outside a Pinokio-managed shell and only need to inspect Pinokio's environment manually, use `pterm which <command>`, but do NOT copy that user-specific absolute path into launcher scripts.-- exists: Check whether a file or folder exists at the specified relative path (example: `"when": "{{!exists('app')}}"`). Can be used with the `when` attribute to determine a path's existence and trigger custom logic. Use relative paths and it will resolve automatically to the current execution folder.-- running: Check whether a script file is running (example: `"when": "{{!running('start.js')}}"`). Can be used with the `when` attribute to determine a path's existence and trigger custom logic. Use relative paths and it will resolve automatically to the current execution folder.-- os: Pinokio exposes the node.js os module through the os variable.-- path: Pinokio exposes the node.js path module through the os variable (example: `{{path.resolve(...)}}`--## System Capabilities-### Package Management (Use in Order of Preference)-The following package managers come pre-installed with Pinokio, so whenever you need to install a 3rd party binary, remember that these are available. Also, you can assume these are available and include the following package manager commands in Pinokio scripts:-1. **UV** - For Python packages (preferred over pip)-2. **NPM** - For Node.js packages-3. **Conda** - For cross-platform 3rd party binaries-4. **Brew** - Mac-only fallback when other options unavailable-5. **Git** - Full access to git is available.-6. **Bun** - For managing bun packages-**Important:** Include all install commands in the install script for reproducibility.-### HTTPS Proxy Support-- All HTTP servers automatically get HTTPS endpoints-- Convention: `http://localhost:<PORT>` → `https://<PORT>.localhost`-- Full proxy list available at: `http://localhost:2019/config/`-### Pterm Features:-- **Clipboard Access:** Read from or Write to system clipboard via pinokio Pterm CLI (`pterm clipboard` command.)-- **Notifications:** Send desktop alerts via pinokio pterm CLI (`pterm push` command.)-- **Script Testing:** Run launcher scripts via pinokio pterm CLI (`pterm start` command.)-- **File Selection:** Use built-in filepicker for user file/folder input (`pterm filepicker` command.)-- **Command Path Resolution:** Inspect the absolute path of any command as seen by Pinokio via `pterm which <command>`. Use this for debugging or external local tooling, especially when a helper process did not inherit Pinokio's `PATH`, for example `pterm which bash` on Windows. Do NOT hardcode the returned absolute path into launcher scripts; use `which()` or `kernel.which()` in the script itself instead.-- **Git Operations:** Clone repositories, push to GitHub-- **GitHub Integration:** Full GitHub CLI support (`gh` commands)--## Troubleshooting with Logs-Pinokio stores the logs for everything that happened in terminal at the following locations, so you can make use of them to determine what's going on:--### Log Structure-In case there is a `pinokio` folder in the project root folder, you should be able to find the logs folder here:--```-pinokio/-└── logs/ # Direct user interaction logs- ├── api/ # Launcher script logs (install.js, start.js, etc.)- ├── dev/ # AI coding tool logs (organized by tool)- └── shell/ # Direct user interaction logs-```--Otherwise, the `logs` folder should be found at project root:--```-logs/-├── api/ # Launcher script logs (install.js, start.js, etc.)-├── dev/ # AI coding tool logs (organized by tool)-└── shell/ # Direct user interaction logs-```--### Log File Naming-- Unix timestamps for each session-- Special "latest" file contains most recent session logs-- **Default:** Use "latest" files for current issues-- **Historical:** Use timestamped files for pattern analysis and the full history.--## Best practices-### 0. Always reference the logs when debugging-- When the user asks to fix something, ALWAYS check the logs folder first to check what went wrong. Check the "Troubleshooting with Logs" section.-### 1. Shell commands for launching programs-- Launch flags related- - Try as hard as possible to minimize launch flags and parameters when launching an app. For example, instead of `python app.py --port 8610`, try to do `python app.py` unless really necessary. The only exception is when the only way to launch the app is to specify the flags.-- Launch IP related- - Always try to find a way to launch servers at 127.0.0.1 or localhost, often by specifying launch flags or using environment variables. Some apps launch apps at 0.0.0.0 by default but we do not want this.-- Launch Port related- - In case the app itself automatically launches at the next available port by default (for example Gradio does this), do NOT specify port, since it's taken care of by the app itself. Always try to minimize the amount of code.- - If the install instruction says to launch at a specific port, don't use the hardcoded port they suggest since there's a risk of port conflicts. Instead, use Pinokio's `{{port}}` template expression to automatically get the next available port.- - For example, if the instruction says `python app.py --port 7860`, don't use that hardcoded port since there might be another app running at that port. Instead, automatically assign the next available port like this: `python app.py --port {{port}}`- - Note that the `{{port}}` expression always returns the next immediately available port for each step, so if you have multiple steps in a script and use `{{port}}` in multiple steps, the value will be different. So if you want to launch at the next available port and then later reuse that port, you will need to first use `{{port}}` to get the next available port, and save the value in local variable using `local.set`, and then use the `{{local.<variable_name>}}` expression later.-### 2. shell.run API-- When writing `shell.run` API requests, always use relative paths (no absolute paths) for the `path` field. For example, if you need to run a command from `app` folder, the `path` attribute should simply be `app`, instead of its full absolute path.-- If a launcher needs to use a command that Pinokio already provides, prefer resolving it with `{{which('command')}}` inside the script instead of assuming the command name will always be on `PATH`.-- Do NOT automatically avoid `bash`-based install commands on Windows. Pinokio's Windows environment includes `bash` through its bundled toolchain, so commands such as `curl -fsSL ... | bash` are acceptable when they run inside a Pinokio-managed shell and there is no simpler cross-platform alternative.-- If a Windows launcher needs to run the shell itself in bash instead of the default `cmd.exe`, set `shell: "{{which('bash')}}"` on the `shell.run` step.-- If a separate debugging process or external local tool did not inherit Pinokio's environment, you may use `pterm which <command>` to inspect what Pinokio would resolve. Do NOT turn that result into a hardcoded script path; for launcher scripts, always use `which()` or `kernel.which()` so the script stays reproducible across machines.-### 2. Package managers-- When installing python packages, try best to use `uv` instead of `pip` even if the install instruction says to use pip. Instead of `pip install -r requirements.txt`, you can simply use `uv pip install -r requirements.txt` for example. Even if the project's own README says use pip or poetry, first check if there's a way to use uv instead.-- When you need to install some global package, try to use `conda` as much as possible. Even on macs, `brew` should be only used if there are no `conda` options.-### 3. Minimal Always-- If you are starting with existing script files, before modifying, creating, or removing any script files, first look at `pinokio.js` to understand which script files are actually used in the launcher. The only script files used are the ones mentioned in the `pinokio.js` file. The `pinokio.js` file is the file that constructs the UI dynamically.-- Do not create a redundant script file that does something that already exists. Instead modify the existing script file for the feature. For example, do not create an `install.json` file for installation if `install.js` already exists. Instead, modify the `install.js` file.-- Pinokio accepts both JSON and JS script files, so when determining whether a script for a specific purpose already exists, check both JSON and JS files mentioned in the `pinokio.js` file. Do not create script files for rendundant purpose.-- When building launchers for existing projects cloned from a repository, try to stay away from modifying the project folder (the `~/pinokio/api/phosphene.git` folder), even if installations are failing. Instead, try to work around it by creating additional files in the launcher folder, and using those files IN ADDITION to the default project.- - The only exception when you may need to make changes to the project folder is when the user explicitly wants to modify the existing project. Otherwise if the purpose is to simply write a launcher, the app logic folder should never be touched.-- When running shell commands, take full advantage of the Pinokio `shell.run` API, which provides features like `env`, `venv`, `input`, `path`, `sudo`, `on`, etc. which can greatly reduce the amount of script code.- - Python apps: Always use virtual environments via `venv` attribute. This attribute automatically creates a venv or uses if it already exists.-### 4. Try to support Cross-platform as much as possible-- Use cross-platform shell commands only.-- This means, prefer to use commands that work on all platforms instead of the current platform.-- If there are no cross platform commands, use Pinokio's template expressions to conditionally use commands depending on `platform`, `arch`, etc.-- Also try to utilize Pinokio Pterm APIs for various cross-platform system features.-- If it is impossible to implement a cross platform solution (due to the nature of the project itself), set the `platform`, `arch`, and/or `gpu` attributes of the `pinokio.json` file to declare the limitation.-- Pinokio provides various APIs for cross-platform way of calling commonly used system functions, or lets you selectively run commands depending on `platform`, `arch`, etc.-### 5. Do not make assumptions about Pinokio API-- Do NOT make assumptions about which Pinokio APIs exist. Check the documentation.-- Do NOT make assumptions about the Pinokio API syntax. Follow the documentation.-### 6. Scripts must be able to replicate install and launch steps 100%-- The whole point of the scripts is for others to easily download and invoke them via Pinokio interface with one click. Therefore, do not assume the end user's system state, and make everything self-contained.-- When a 3rd party package needs to be installed, or a 3rd party repository needs to be downloaded, include them in the scripts.-### 7 Dynamic UI rendering-- The `pinokio.js` launcher script can change dynamically depending on the current state of the script execution. Which means, depending on what the file returns, it can determine what the sidebar looks like at any given moment of the script cycle.- - `info.exists(relative_path)`: The `info.exists` can be used to check whether a relative path (relative to the script root path) exists. The `pinokio.js` file can determine which menu items to return based on this value at any given moment.- - `info.running(relative_path)`: The `info.running` can be used to check whether a script at a relative path is currently running (relative to the script root path) exists. The `pinokio.js` file can determine which menu items to return based on this value at any given moment.- - `info.local(relative_path)`: The `info.local` can be used to return all the local variables tied to a script that's currently running. The `pinokio.js` file can determine which menu items to return based on this value at any given moment.- - `default`: set the `default` attribute on any menu item for whichever menu needs to be selected by default at a given step. Some example scenarios:- - during the install process, the `install.js` menu item needs to be set as the `default`, so it automatically executes the script- - when launching the `start.js` menu item needs to be set as the `default`, so it automatically executes the script- - after the app has launched, the `default` needs to be set on the web UI URL, so the user is sent to the actual app automatically.- - Check the examples in the ~/pinokio/prototype/system/examples folder to see how these are being used.-### 8. No need for stop scripts-- `pinokio.js` does NOT need a separate `stop` script. Every script that can be started can also be natively stopped through the Pinokio UI, therefore you do not need a separate stop script for start script-### 9. Writing launchers for existing projects-- When writing or modifying pinokio launcher scripts, figure out the install/launch steps by reading the project folder `app`.-- In most cases, the `README.md` file in the `~/pinokio/api/phosphene.git` folder contains the instructions needed to install and run the app, but if not, figure out by scanning the rest of the project files.-- Install scripts should work for each specific operating system, so ignore Docker related instructions. Instead use install/launch instructions for each platform.-### 10. Retrofitting an already-working setup-- Sometimes the user starts outside Pinokio, gets an app working through ad-hoc commands, and only later asks to turn that work into a Pinokio launcher.-- In this case, treat the current working setup and the successful session context as the highest priority source of truth. Do NOT restart from scratch if the app is already working.-- First capture the exact install and launch steps that already succeeded: cloned repositories, package manager commands, environment variables, model downloads, ports, working directories, helper scripts, and any fixes that were required.-- Then convert that knowledge into reproducible Pinokio scripts (`install.js`, `start.js`, `reset.js`, `update.js`, `pinokio.js`, `pinokio.json`) instead of telling the user to manually repeat the ad-hoc process.-- When the successful setup lives in a non-Pinokio folder, use that folder as evidence only. Resolve `PINOKIO_HOME` first, then produce the final launcher in the proper Pinokio location (`PINOKIO_HOME/api/<unique_name>` or `PINOKIO_HOME/plugin/<unique_name>`) unless the user explicitly asks for another layout.-- Replace machine-specific state with reproducible steps. Never hardcode absolute paths, user-specific cache locations, session-only ports, or one-off manual edits if they can be expressed in the launcher.-- Do not simply encode whatever happened to work on the current machine. Generalize the result into the broadest practical cross-platform, cross-machine launcher, and if limitations are unavoidable, declare them explicitly in `pinokio.json` instead of silently baking in local assumptions.-- If the app is already installed but the exact setup steps are partially missing, inspect the current working tree, generated files, dependency manifests, shell history when available, and logs to reconstruct the smallest reliable install and start flow.-- Verify from as clean a state as practical. A launcher is only done when another user could reproduce the working result without relying on undocumented steps from the original ad-hoc session.-### 11. Don't use Docker unless really necessary-- Some projects suggest docker as installation options. But even in these cases, try to find "development" options to launch the app without relying on Docker, as much as possible. We do not need Docker since we can automatically install and launch apps specifically for the user's platform, since we can write scripts that run cross platform.-### 12. pinokio.json-- Do not touch the `version` field since the version is the script schema version and the one pre-set in `pinokio.js` must be used.-- `icon`: It's best if we have a user friendly icon to represent the app, so try to get an image and link it from `pinokio.json`.- - If the git repository for the `~/pinokio/api/phosphene.git` folder points to GitHub (for example https://github.com/<USERNAME>/<REPO_NAME>`, ask the user if they want to download the icon from GitHub, and if approved, get the `avatar_url` by fetching `https://api.github.com/users/<USERNAME>`, and then download the image to the root folder as `icon.png`, and set `icon.png` as the `icon` field of the `pinokio.json`.-### 13. Gitignore-- When a launcher involves cloning 3rd party repositories, downloading files dynamically, or some files to be generated, these need to be included in the .gitignore file. This may include things like:- - Cloning git repositories- - Downloading files- - Dynamically creating files during installation or running, such as Sqlite Databases, or environment variables, or anything specific to the user.-- Make sure these file paths are included in the .gitignore file, and if not, include them in .gitignore.--## AI Libraries (Pytorch, Xformers, Triton, Sageattention, etc.)-If the launcher is for running AI models locally, the install script must declare the AI bundle so Pinokio can install the machine-level prerequisites before the script runs:--```-// install.js-module.exports = {- requires: {- bundle: "ai"- },- run: [- ...- ]-}-```--This is required even when the script also uses `torch.js`. The AI bundle is what triggers installation of common local AI prerequisites such as CUDA on NVIDIA systems and Hugging Face CLI.--If the launcher has a dedicated built-in script named `torch.js`, it can be used as follows:--```-// install.js-module.exports = {- requires: {- bundle: "ai"- },- run: [- // Edit this step with your custom install commands- {- method: "shell.run",- params: {- venv: "venv", // Edit this to customize the venv folder path- path: "app",- message: [- "uv pip install -r requirements.txt"- ],- }- },- // Delete this step if your project does not use torch- {- method: "script.start",- params: {- uri: "torch.js",- params: {- path: "app",- venv: "venv", // Edit this to customize the venv folder path- // xformers: true // uncomment this line if your project requires xformers- // triton: true // uncomment this line if your project requires triton- // sageattention: true // uncomment this line if your project requires sageattention- // flashattention: true // uncomment this line if your project requires flashattention- }- }- },- ]-}-```+- `docs/PANEL_REFERENCE.md` — `panel_settings.json`, LoRA system, `required_files.json`, helper protocol+- `docs/DEBUG_RECIPES.md` — debug recipes, patch authoring template+- `docs/DEPENDENCY_PINS.md` — full mlx / ltx-2-mlx pin rationale and measurements+- `docs/HISTORY.md` — v3.0 history, 2.0 capabilities, benchmarks-The `torch.js` script also includes ways to install pytorch dependent libraries such as xformers, triton, sagetattention. If any of these libraries need to be installed, use the torch.js to install in order to install them cross platform.---## Quick Reference-### Essential Documentation-- **Pinokio Programming:** See `PINOKIO.md` at ~/pinokio/prototype/PINOKIO.md → "Programming Pinokio" section-- **Dynamic Menus:** See `PINOKIO.md` at ~/pinokio/prototype/PINOKIO.md → "Dynamic menu rendering" section-- **CLI Commands:** See `PTERM.md` at ~/pinokio/prototype/PTERM.md-### Common Patterns-- **Python Virtual Env:** `shell.run` with `venv` attribute-- **Cross-platform Commands:** Always test on multiple platforms-- **Error Handling:** Check logs/api for launcher issues-- **GitHub Operations:** Use `gh` CLI for advanced GitHub features-## Development Principles-1. **Minimize Shell Usage:** Leverage API parameters instead of raw commands-2. **Maintain Separation:** Keep app logic and launchers separate-3. **Follow Conventions:** Match existing project patterns-4. **Test Thoroughly:** Use CLI to verify launcher functionality-5. **Document Changes:** Update relevant metadata and documentation+The generic Pinokio scaffolding guide that used to follow here is Pinokio's own (`~/pinokio/CLAUDE.md`, `~/pinokio/prototype/PINOKIO.md`); it is not duplicated in this repo.diff --git a/README.md b/README.mdindex a79742d..574a1d1 100644--- a/README.md+++ b/README.md@@ -19,7 +19,7 @@</p>-> **Current release: v4.19.3.** **Phosphene no longer touches your GitHub login:** a maintainer-only statistics job ran on every install and, if the GitHub command-line tool was signed in, borrowed its token once a day; it now runs only on the maintainer's Mac (#106). **Report a bug** asks what happened before it opens the issue, and the log it attaches keeps the error lines. **4.19.2:** **Ingredients puts your reference pictures in the video again** on LTX-2.3 (#101), and you can **switch the LTX generation (2.3 or 2.5) from the panel** (@blackest, #102; 2.5 stays the default). High · 720p renders High · 720p, Upscale ×2 refuses a result bigger than QHD before it starts (@blackest, #103), One Shot gets Stop early and a smarter Split (@blackest, #97-#99), room tone sits at -38 LUFS (@blackest, #100), and fewer renders fail: missing pictures, keyframes and LoRAs are caught when you press Generate, the GPU-watchdog message says what can actually help, and vocal separation rides out a flaky connection. Linux on Apple Silicon arrives as a community-maintained, best-effort target (@joshuaswarren, #94). 4.19.1: voices trained in Phosphene save correctly again, and a stopped training run says why. **4.19.0: Hailuo H3 grows up, and trained characters look like themselves again.** On Hailuo H3: **Keyframes** (an end frame, first + last, or stills at exact moments), **Extend** any clip, **Lip-sync** a face to your own voice or song, **Add sound** to a silent clip, smoother 10-15 s shots (each window carries the end of the last one, picture and sound), and **Fast HD**. Characters and voices trained in Phosphene since June were saved with their numbers in the wrong order and carried no likeness; new trainings save correctly and **Update repairs the ones you already have** (found by @tanis2000, #62). **Extend no longer wears your clip down** round after round: the part you already had is delivered untouched and only the new part is encoded (#48). 4.18.0: Play all, Use this audio for..., LoRA-aware Enhance. Press Update in Pinokio, then restart. Full notes on the [releases page](https://github.com/mrbizarro/Phosphene/releases).+> **Current release: v4.19.4.** **Renders work again where a library update broke them:** a new release of `tokenizers` (Oct 9) could reach your install during an Update, and then every video render stopped at its first step. Phosphene now holds its engine to a tested set of package versions, and Update puts the right one back. If the engine's packages ever stop fitting together, the panel says so before a render starts and offers Repair engine. A failed FLUX.2 image now says why. **4.19.3:** **Phosphene no longer touches your GitHub login:** a maintainer-only statistics job ran on every install and, if the GitHub command-line tool was signed in, borrowed its token once a day; it now runs only on the maintainer's Mac (#106). **Report a bug** asks what happened before it opens the issue, and the log it attaches keeps the error lines. **4.19.2:** **Ingredients puts your reference pictures in the video again** on LTX-2.3 (#101), and you can **switch the LTX generation (2.3 or 2.5) from the panel** (@blackest, #102; 2.5 stays the default). High · 720p renders High · 720p, Upscale ×2 refuses a result bigger than QHD before it starts (@blackest, #103), One Shot gets Stop early and a smarter Split (@blackest, #97-#99), room tone sits at -38 LUFS (@blackest, #100), and fewer renders fail: missing pictures, keyframes and LoRAs are caught when you press Generate, the GPU-watchdog message says what can actually help, and vocal separation rides out a flaky connection. Linux on Apple Silicon arrives as a community-maintained, best-effort target (@joshuaswarren, #94). 4.19.1: voices trained in Phosphene save correctly again, and a stopped training run says why. **4.19.0: Hailuo H3 grows up, and trained characters look like themselves again.** On Hailuo H3: **Keyframes** (an end frame, first + last, or stills at exact moments), **Extend** any clip, **Lip-sync** a face to your own voice or song, **Add sound** to a silent clip, smoother 10-15 s shots (each window carries the end of the last one, picture and sound), and **Fast HD**. Characters and voices trained in Phosphene since June were saved with their numbers in the wrong order and carried no likeness; new trainings save correctly and **Update repairs the ones you already have** (found by @tanis2000, #62). **Extend no longer wears your clip down** round after round: the part you already had is delivered untouched and only the new part is encoded (#48). 4.18.0: Play all, Use this audio for..., LoRA-aware Enhance. Press Update in Pinokio, then restart. Full notes on the [releases page](https://github.com/mrbizarro/Phosphene/releases).## Overviewdiff --git a/VERSION b/VERSIONindex 11533fc..cf4c5df 100644--- a/VERSION+++ b/VERSION@@ -1 +1 @@-4.19.3+4.19.4diff --git a/docs/ANALYTICS.md b/docs/ANALYTICS.mdindex d449666..743bf6e 100644--- a/docs/ANALYTICS.md+++ b/docs/ANALYTICS.md@@ -238,7 +238,7 @@ Same as `render_completed` (minus `first_render`), plus:| `error_class` | string | `"metal_watchdog"` | **A closed 19-value taxonomy** (`refused`, `oom_jetsam`, `metal_watchdog`, `metal_oom`, `native_crash`, `helper_start_timeout`, `helper_exit`, `model_missing`, `model_corrupt`, `download_failed`, `venv_broken`, `bad_params`, `input_missing`, `file_missing`, `disk_full`, `export_failed`, `timeout`, `cancelled_race`, `other`). Classification runs on the original error text locally; **only the class leaves the machine.** `refused` is in the taxonomy but never rides on a `render_failed` event — it is the value that routes the event to `render_refused` instead, below || `error_fingerprint` | string | `"a3f09c21e7b4"` | Only when `error_class` is `other`: 12 hex chars of the SHA-256 of the already-scrubbed first line. Lets "the same unknown error, 17 times, all on M1 Max" be counted without transmitting the text — the readable line stays in your own `state/usage-log.jsonl` || `error_signature` | string | `"RuntimeError: helper exited before first frame"` | **The only free-text field the panel sends**, see the scrubbing rules below. Kept for ONE transition release alongside `error_class`, then removed |-| `crash_line` | string | `"gpu_timeout"` | 4.19.2 — only when the LTX render helper died from a signal (SIGABRT, SIGSEGV, …): the **class** of the last native error line it printed, never the line. **Closed vocabulary**: `gpu_timeout`, `gpu_interactivity` (the two GPU-watchdog names), `gpu_hang`, `gpu_page_fault`, `gpu_oom`, `gpu_victim`, `gpu_other` (another Metal command-buffer error), `resource_limit`, `cxx_exception`, `assertion`, `none` (no such line reached the panel). Why: until 4.19.2 the generic SIGABRT sentence quoted the watchdog line as an example, so every unexplained abort was counted as `metal_watchdog` (24 of 4.19.1's 37); those now count as `native_crash`, and this says what they were |+| `crash_line` | string | `"gpu_timeout"` | 4.19.2 — only when the LTX render helper died from a signal (SIGABRT, SIGSEGV, …): the **class** of the last native error line it printed, never the line. **Closed vocabulary**: `gpu_timeout`, `gpu_interactivity` (the two GPU-watchdog names), `gpu_hang`, `gpu_page_fault`, `gpu_oom`, `gpu_victim`, `gpu_internal`, `gpu_submissions_ignored`, `gpu_invalid_resource`, `gpu_not_permitted`, `gpu_device_removed` (4.19.4 - the remaining IOGPU/Metal command-buffer error names, split out of `gpu_other`), `gpu_other` (any other Metal command-buffer error), `resource_limit`, `cxx_exception`, `assertion`, `none` (no such line reached the panel). Why: until 4.19.2 the generic SIGABRT sentence quoted the watchdog line as an example, so every unexplained abort was counted as `metal_watchdog` (24 of 4.19.1's 37); those now count as `native_crash`, and this says what they were || `crash_phase` | string | `"start"` | 4.19.2 — same condition as `crash_line`: how far the helper got, from its own step lines. **Closed vocabulary**: `encode`, `load`, `denoise`, `decode` (as `watchdog_phase`), `start` (before its first step line) || `train_error` | string | `"oom"` | 4.19.1 — only on a failed **training** job (`mode: train`): why it stopped. **Closed vocabulary**: `oom` (MLX/Metal could not allocate, or macOS killed the trainer with SIGKILL), `missing_file` (incl. the LTX-2.3 training weights not downloaded: the trainer now checks them first and stops within seconds), `caption_check` (the captions carry another trigger), `disk_full`, `import_error` (the venv is missing a package), `nan_loss` (the loss stopped being a number for 10 steps in a row; the trainer now stops there), `other`. The trainer classifies its own exception by TYPE first and then by MLX's fixed allocation-failure fragments (`lora_lab/failure.py`), sends the word in its `error` event, and the panel forwards it only if it is on this list. Never a path, caption, trigger or message: those stay in the Logs tab and `<dataset>/train.log`. Before 4.19.1 every one of these reached the fleet as `helper_exit` + "training exited with code 1"; that sentence and its `error_class` are unchanged, so the old series continues and `train_error` splits it |@@ -329,7 +329,7 @@ repaired is the most useful transition on this event. This is not a heartbeat an| `step` | string | `"engine_env"` | **Closed vocabulary**: `first_boot` (the panel came up), `engine_env` (its Python environment can run a render), `weights_check` (the base model is on disk), `first_queue` (a job reached the worker — someone pressed Render) || `outcome` | string | `"failed"` | **Closed vocabulary**: `started`, `ok`, `failed`, `skipped` || `error_class` | string | `"venv_broken"` | Only on `failed`, and only from the same closed taxonomy `render_failed` uses |-| `cause` | string | `"network"` | 4.17.5 — only on a failed `engine_env`: WHY, one word. **Closed vocabulary**: `network` (a package server could not be reached), `timeout` (downloads timed out), `disk` (disk full), `uv_error` (the package tool could not resolve or build), `python_missing` (the venv's Python does not run), `installing` (Pinokio's Install was still writing the venv when the panel looked - reported again when it finishes), `other`, `unknown` (no installer record: an install that stopped before the engine step, or one older than 4.17.5). Read from the installer's own record (`ltx-2-mlx/env/.phosphene_engine_result.json`, written by `scripts/pinokio/ltx_engine_env.sh` in these words via `install_cause.sh`) - never from its output text |+| `cause` | string | `"network"` | 4.17.5 — only on a failed `engine_env`: WHY, one word. **Closed vocabulary**: `network` (a package server could not be reached), `timeout` (downloads timed out), `disk` (disk full), `uv_error` (the package tool could not resolve or build), `python_missing` (the venv's Python does not run), `installing` (Pinokio's Install was still writing the venv when the panel looked - reported again when it finishes), `mismatch` (4.19.4 - the packages are all there but transformers refuses the version of one of its own dependencies, e.g. tokenizers 0.23.3 under transformers <5.13; read from the venv's files by the panel, Repair engine fixes it), `other`, `unknown` (no installer record: an install that stopped before the engine step, or one older than 4.17.5). Read from the installer's own record (`ltx-2-mlx/env/.phosphene_engine_result.json`, written by `scripts/pinokio/ltx_engine_env.sh` in these words via `install_cause.sh`) - never from its output text || `version` | string | `"4.16.0"` | The build that reported it || `ram_gb` | int | `16` | SYS-16: lets `first_queue` (this event) be sliced the same way `render_completed`'s `first_render` already is — the reviewer's finding was that activation is LOWEST on the machines that struggle most (36 GB 53%, 8 GB 57%, 16 GB 63%), and answering "first_queue vs first_render, per tier" needed this on both events, not a join against `app_boot` by install_id |diff --git a/docs/DEBUG_RECIPES.md b/docs/DEBUG_RECIPES.mdnew file mode 100644index 0000000..3e77e61--- /dev/null+++ b/docs/DEBUG_RECIPES.md@@ -0,0 +1,174 @@+# Phosphene debug recipes and patch authoring++Moved out of CLAUDE.md (former §19–§20).++## 19. Debug recipes++### "Helper died silently — where did it die?"++```bash+# Scan the panel log for the last step:* breadcrumb+curl -s http://127.0.0.1:8198/status | python3 -c \+ "import json,sys; [print(l) for l in json.load(sys.stdin)['log'] if 'step:' in l][-3:]"+```++If last step is `step:get_pipe` → death during pipeline init (model+load). Likely OOM or weight-corrupt. If last step is+`step:generate_and_save` → death during gen (denoise / VAE decode).+Likely OOM peak or Metal kernel issue.++For non-OOM crashes, check `~/Library/Logs/DiagnosticReports/python3.11_*.crash`+or `*.ips` from around the crash time.++### "Panel says port 8198 already in use"++```bash+lsof -nP -iTCP:8198 -sTCP:LISTEN # who has it+pkill -f mlx_ltx_panel.py # nuke all panels+```++Common cause: a previous manual `python mlx_ltx_panel.py` is still+running. Pinokio's start.js can't take over a port someone else owns.+**Don't spawn the panel manually unless you're going to kill it before+handing back.**++### "I edited the UI but the browser hasn't changed"++The frontend lives in files under `webapp/` (docs/ARCHITECTURE.md), and+what you must restart depends on which file:++- **CSS (`webapp/style/panel.css`) or JS (`webapp/js/*.js`)** — served+ from disk on every request with `Cache-Control: no-cache`. NO panel+ restart needed; just hard-refresh the browser (Cmd+Shift+R).+- **Markup (`webapp/index.html`)** — read ONCE at panel import (the+ served page is pinned to the booted process on purpose; see the+ build-stamp comment in the template). Restart the panel (Pinokio+ Stop → Start, or `pkill -f mlx_ltx_panel.py` then Start), then+ hard-refresh.+- **Python (`mlx_ltx_panel.py`, `panel/routes_*.py`)** — restart the+ panel.++### "I edited the helper or a patch but nothing changed"++```bash+# 1. Re-apply patches (idempotent, applies to site-packages)+cd ~/pinokio/api/phosphene.git+./ltx-2-mlx/env/bin/python3.11 patch_ltx_codec.py++# 2. Restart the helper subprocess (panel keeps running)+curl -X POST http://127.0.0.1:8198/helper/restart++# 3. Submit a test job+curl -X POST http://127.0.0.1:8198/run \+ -d "mode=t2v" -d "prompt=quick test" \+ -d "width=512" -d "height=288" -d "frames=49" \+ -d "steps=8" -d "quality=draft"++# 4. Wait for done+until [ "$(curl -s http://127.0.0.1:8198/status | python3 -c 'import json,sys;d=json.load(sys.stdin);print(0 if d.get(\"current\") else 1)')" = "1" ]; do sleep 5; done+```++### "How loud / clean is the audio in this clip?"++```bash+FFPROBE="/Volumes/Topaz Video AI 4.0.6/Topaz Video AI.app/Contents/MacOS/ffprobe"+FFMPEG="/Volumes/Topaz Video AI 4.0.6/Topaz Video AI.app/Contents/MacOS/ffmpeg"+"$FFMPEG" -i out.mp4 -af "volumedetect" -f null - 2>&1 | grep -E "max_volume|mean_volume"+```++Healthy on dialogue: `max_volume` between -2 and -15 dB. Below -25 dB+peak is the regression fingerprint — usually means a wrong mlx version.++### "Re-encode for X / web (yuv420p, faststart, 8 Mbps)"++```bash+"$FFMPEG" -y -i in.mp4 \+ -c:v h264_videotoolbox -profile:v high -pix_fmt yuv420p \+ -b:v 8M -maxrate 12M -bufsize 16M \+ -movflags +faststart \+ -c:a aac -b:a 192k \+ out_x.mp4+```++X (Twitter) rejects yuv444p with a misleading "aspect ratio" error.+Use this recipe for any social upload.++### "Stuck queue / can't cancel"++```bash+curl -X POST http://127.0.0.1:8198/stop # cancel current job+curl -X POST http://127.0.0.1:8198/queue/clear # empty the queue+curl -X POST http://127.0.0.1:8198/helper/restart # nuke the helper+```++### "Force re-download a corrupt model file"++```bash+# Delete the file in question, then click Install in Pinokio (resumes+# only the missing files; intact ones are skipped via `hf` hash check).+rm ~/pinokio/api/phosphene.git/mlx_models/ltx-2.3-mlx-q4/<bad-file>.safetensors+# Then in Pinokio: Phosphene → Install (or Resume Install)+```++### "Force a different hardware tier for testing"++```bash+LTX_TIER_OVERRIDE=base ./run_panel.sh # pretend this Mac is < 48 GB+```++`run_panel.sh` actively unsets this on every run unless explicitly set+on the command line — there's a hard-learned bug history about leaked+overrides bleeding across panel restarts.++### "What does `/status` actually return?"++```bash+curl -s http://127.0.0.1:8198/status | python3 -m json.tool | head -60+```++Top-level keys: `running`, `paused`, `current`, `queue`, `history`,+`log`, `tier`, `memory`, `helper`, `download`, `repos_ready`,+`repos_total`, `base_available`, `q8_available`, `q8_missing`,+`comfy_pids`, `outputs`, `server_now`, `avg_elapsed_sec`.++## 20. Patch authoring template (`patch_ltx_codec.py`)++When adding a new patch:++```python+# ---- Patch N: <one-line summary> --------------------------------------------+# Why: <symptom + root cause + why this fix>. Reference upstream+# file:line and any external context (commit SHA, GitHub issue, paper).+PATCH_<NAME>_OLD = '''<exact text expected to be in the upstream file>'''+PATCH_<NAME>_NEW = '''<replacement text — include a `# PATCHED (LTX23MLX): ...` comment>'''+```++Then in `main()`:++```python+target = _find("<relative/path/to/upstream.py>")+outcome = apply_patch(+ target, PATCH_<NAME>_OLD, PATCH_<NAME>_NEW,+ marker="<unique substring that proves NEW is on disk>",+ label="<NAME>",+ upgrade_marker="<optional: substring that distinguishes a newer NEW from an older NEW>",+)+# If this patch is optional (don't fail install on drift):+if outcome in (OUTCOME_DRIFT, OUTCOME_MISSING):+ print(" [<NAME>] note: ...", file=sys.stderr)+ outcome = OUTCOME_ALREADY+outcomes.append(("<NAME>", outcome))+```++Conventions:+- `marker` is a substring **inside** `PATCH_<NAME>_NEW` that's unlikely+ to appear in the unpatched file. Convention: include+ `PATCHED (LTX23MLX...)` somewhere in the new text.+- `upgrade_marker` lets you ship a v2 of a patch without forcing users+ to nuke their venv. Example: codec patch's `+faststart` was added+ later; `upgrade_marker="+faststart"` distinguishes v1 (no faststart)+ from v2 and rewrites the line in place.+- Patches that target an upstream code structure that may legitimately+ vanish (e.g. an internal helper that gets refactored away) should be+ marked **optional** in main() so install warns instead of fails.+diff --git a/docs/DEPENDENCY_PINS.md b/docs/DEPENDENCY_PINS.mdnew file mode 100644index 0000000..cf610e2--- /dev/null+++ b/docs/DEPENDENCY_PINS.md@@ -0,0 +1,8 @@+# Phosphene dependency pins: full rationale++Moved out of CLAUDE.md §4. The long-form rows for mlx and ltx-2-mlx, with all measurements.++| Pin | Why |+|---|---|+| `mlx==0.31.1` | mlx 0.31.2 introduced a numerical regression that attenuates LTX 2.3 vocoder output by ~22 dB. Verified: same model + same prompt + same seed → -42 dB peak on 0.31.2 vs -9 dB peak on 0.31.1. **2026-08-28 — 0.32.1 / 0.32.2 measured and held back, on MEMORY, not audio.** The audio blocker is 0.31.2-specific and gone by 0.32 (isolated vocoder delta **0.000001 dB**; five renders per arm: max_volume -1.7 vs -1.8 dB, -9.2 vs -9.3 LUFS, no time shift — claimed 22 dB, measured 0.1). Speed is real too: Q8 1024×576 121f **139.8 s → 133.6 s (-4.5%)**, all in DiT load + VAE decode. What holds it back: 0.31.1's peak footprint tracks the WORKLOAD, 0.32.x's tracks the MACHINE — it takes ~95% of the ceiling MLX derives from RAM (`0.95 * hw.memsize`, identical formula on both), so it scales down with the Mac but never stops filling it. `/usr/bin/time -l` peak, same prompt/seed/dims, MLX memory+cache limits set to each Mac's derived value: Q4 768×432 — 16 GB **17.41 → 20.35** (0.32.2: 19.35), 32 GB **25.66 → 33.18** (97% of physical), 64 GB **25.53 → 54.28**; Q8 1024×576 — 48 GB **39.49 → 49.95** (97% of physical). On the 64 GB box the Q4 render moved system pressure **58% → 84%** with +1.5 GB swap, the Q8 one hit **87%** — past the 82% at which `plan_memory_policy()` forces the streamed decode (~30 s on a 5 s clip, more than the 4.5% the move earns). **Ruled out:** Metal residency sets (new in 0.32) — `MLX_RESIDENCY_SET_MAX_PCT=0` reproduces the footprint to within 300 KB over three runs. The growth is allocator **cache**, so an explicit `mx.set_cache_limit()` is the prerequisite — **shipped, on this pin, ahead of any version move**: `mlx_warm_helper.py` now caps the cache at **one eighth of physical RAM** (floor 2 GiB, ceiling 8 GiB), applied at helper start and re-asserted before every render because the pipelines drop it to 0 on paths we do not take. On 0.31.1 that is Q4 768x432 121f **25.53 -> 16.50 GB for 71.45 -> 68.84 s** and Q8 1024x576 at the 48 GiB tier **39.49 -> 25.39 GB for 139.84 -> 138.71 s**, both sha256-identical to the uncapped render. **And the pin cannot move alone** — see `scripts/check_post_update.js`. **2026-08-28, second pass: the cap shipped and the move was REFUSED AGAIN.** With the policy applied to both versions, 0.32.1's peak as a share of physical RAM is 16 GiB **101% → 116%**, 32 GiB 75% → 68%, 48 GiB Q8 **77% → 82%**, 64 GiB **37% → 41%** — three of four tiers worse than 0.31.1 uses today, and the Comfortable 48 GiB tier lands ON the 82% line `plan_memory_policy()` treats as pressured. The cap cannot reach it because the excess is not cache: at an identical cap, 0.32.1's **active** memory is +12.0 GB on Q4 and +29.2 GB on Q8. Cache **0** does get it under (Q8@48 GiB 32.25 GB, Q4@16 GiB 17.04 GB) and erases the entire speed win at the same time. There is no cache setting where 0.32.1 beats 0.31.1+policy on both axes, so mflux stays at 0.18.0 too. |+| `ltx-2-mlx` PINNED to the FORK TAG **`v0.14.19+ltx25.7`** (`mrbizarro/ltx-2-mlx` = v0.14.19 `1192051` + the LTX-2.5 port + the schedule/sampler/live-preview work + the i2v anchor re-pin on BOTH loops + `+ltx25.7`: IC-LoRA `source_video=`, the seam Upscale ×2 renders through — the tag's own history is in `scripts/pinokio/ltx_checkout.sh`) | **The pin is a TAG and it lives in `scripts/pinokio/ltx_checkout.sh`**, which is the ONE checkout implementation both lanes call (install.js dispatches it; scripts/post_update.sh calls it). It was a bare SHA through v3.8.3 and was reachable only by luck — a force-push would have stranded every install with an un-fetchable pin and a dead Update button. `check_ltx_pin.js` is the gate. The packages report **`0.14.19+ltx25.7`**; `_LTX_EXPECTED_VERSION` in mlx_warm_helper.py must equal that string or every render logs VERSION SKEW — move the two together. This pin is what lets **LTX-2.5 render through the panel**, and on **dev/beta** 2.5 is the registry DEFAULT (2.3 stays installed, selectable via `LTX_MODEL_VERSION=ltx23`). **v3.8.x did NOT register `ltx25` at all** and shipped 2.3 as the only generation, because the 2.5 weight packs were not publicly downloadable when it was cut — a fresh install would have booted into a generation it could not fetch. They are published now, and **v4.0.0 closes that divergence**: 2.5 is the registered default everywhere. If you ever need to curate a release back to a single generation, it is one `MODEL_VERSIONS` dict plus its three `required_files.json` rows (watch the `kind: "base"` trap: any base row is mandatory for an install to read complete, in the panel *and* in `pinokio.js`). The **pin diverged for the same reason**: v3.8.x shipped `871694d` / `0.14.19+ltx25.1`, one commit behind, because `e6be9d6` (the 2.5 sampler + stage-2 schedule, below) had no 2.3 regression evidence behind it at cut time. It does now — a 2.3 sha256-identity pair across the change — so the next release should choose the pin deliberately rather than inherit either. The base tag v0.14.19 landed 2026-08-11 (a catch-up from v0.14.8, itself a 2026-06-01 catch-up from v0.14.0). **STAY PINNED** — this is NOT "main HEAD", and not upstream's tip either. The v0.14.8 bump had pulled dgrauet's native `_pre_denoise_flush` (the Metal-watchdog fix for the I2V "mosaic" on memory-pressured Macs, #17), budget-aware VAE decode tiling and first-class `frame_rate`, which cut us from 7 runtime patches to 1 (codec-only). The v0.14.19 bump keeps that shape and adds: checkpoint-read `av_ca_timestep_scale_multiplier` (0.14.11 — **audio/dialogue weighting changes on every render**, toward upstream parity, plus `LTXModelConfig.from_checkpoint_dir()`), `frame_rate` forwarded at the A2V/lipdub call sites and no more shortest-stream mux truncation (0.14.15), quantized transformers at any `group_size` (0.14.16), and GPU-watchdog explanation + DiT-freed-before-VAE-decode + a Gemma cache-limit fix (0.14.19). **The `+ltx25.2` bump (2026-08-12) is the first one that changes what a 2.5 render computes**, and only a 2.5 render: (a) the **euler-ancestral sampler is finally REACHED** — it had been implemented with 48 tests and zero callers, so every prior 2.5 render silently used the 2.3 Euler step, against upstream's own `ANCESTRAL_SAMPLER_SINCE_VERSION = (2, 5)` and all three official ComfyUI 2.5 templates; keyframe/flf2v deliberately stays on Euler because the flf2v template pins eta to 0. (b) **stage 2's first sigma is now the vendor's 0.85**, read from `video_ltx2_5_t2v.json` node 395, where we had been using 2.3's 0.909375 — a refine pass starting at the wrong noise level. Both are version-keyed off the checkpoint's own `model_version`, and 2.3 output is proven **sha256-identical** before and after. **No model re-download**: 0.14.13+ prefers a versioned `transformer-distilled-*.safetensors` and falls back to the unversioned name, and update.js trims the `-1.1` variants, so file resolution is identical to v0.14.8. Bumping the pin further is a deliberate, tested operation — read the release notes, bump `_LTX_EXPECTED_VERSION` in mlx_warm_helper.py, smoke-test the matrix on dev, then bump BOTH install.js and update.js in one commit. **The `+ltx25.4` bump (2026-08-14, v4.0.2) is the i2v anchor.** The conditioning item was always built correctly — `frame_idx=0`, `strength=1.0`, `mask_value=0`, a hard latent replace — and both loops forced those tokens back into the model's **x0 estimate** every step. Under Euler that was sufficient by arithmetic accident: velocity `(x - x0)/sigma` is exactly 0 at a pinned token, so the step returns it unchanged. The **euler-ancestral** step 2.5 selects has no such property: it rescales every token by `alpha_next/alpha_down` and adds fresh Gaussian noise, unmasked. Measured on the real 2.5 schedule the anchor is **halved and buried under noise 0.86x its own scale after step 1**, so every forward from step 2 on saw garbage where the image should be and the composition was decided without it; the terminal step stamped the image back in, which is why the delivered frame 0 always matched while the clip was a different shot. The fix re-composites the **sample** against `clean_latent`/`denoise_mask` after the ancestral step at all three sites, guarded by the existing uniform-mask flags — the other half of what ComfyUI's 2.5 i2v graph does. Proven, not argued: **t2v at a fixed seed is sha256-identical** before and after (`fbf09533583c423ab9ad3c0a437aee3484f15c0c5cceb2b1fc4ecc6d59071abb`), and frame-vs-input normalised cross-correlation at seed 424242 moves **0.0934 -> 0.7878** (frame 36) and **0.0902 -> 0.7187** (frame 72) while frame 0 holds at ~0.975. Every Euler lane — 2.3 i2v, keyframe/flf2v with its deliberate `eta=0`, a2v, extend, restore, ic_lora, lipdub — never reaches the branch. **The `+ltx25.5` bump (2026-08-15, v4.0.7) closes that on res_2s too**, which is the lane 2.5's HQ tiers run: the owner reported a reference image producing a high-quality clip of something else on High / High-720p. `res2s_denoise_loop` takes `repin_masked_sample` (default False = the old bytes) and `ti2vid_two_stages_hq` resolves it **per generation**, so 2.5 anchors i2v for real while 2.3 is byte-identical BY CONSTRUCTION — the reason this was deferred in +ltx25.4 is answered by construction rather than by measurement. `denoise_loop` takes the same flag defaulting True, so passing False deliberately restores the drift: that is **Inspire**, shipped as an explicit i2v mode (`loose_reference` through `generate_two_stage`/`generate_and_save` on both pipelines, forwarded only when true). `tests/test_repin_masked_sample.py` pins all four directions. The historic `dcd639e (0.1.0)` detour broke the Extend `cfg_scale` API; do not revisit. |diff --git a/docs/HISTORY.md b/docs/HISTORY.mdnew file mode 100644index 0000000..e85c6c5--- /dev/null+++ b/docs/HISTORY.md@@ -0,0 +1,98 @@+# Phosphene history: v3.0 line, 2.0 capabilities, benchmarks++Moved out of CLAUDE.md §0. Historical; `docs/STATE.md` is current.++### Historical — the v3.0 line++Public release was **v3.0.6**. The v3.0 line launched 2026-05-23 and has+shipped six patch releases: v3.0.0 (Characters/Voice/Image Studio/A2V) →+v3.0.1 (FFLF crash fix) → v3.0.2 (Boost/Turbo accel restored after a+2-month silent regression) → v3.0.3 (HiDream hidden, issue #15) → v3.0.4+(CivitAI SSL cert) → v3.0.5 (A2V kwarg signature shim, #5) → v3.0.6+(deep-review hardening: CivitAI token-leak fix, dead-HDR revival,+GPU-contention guard, boot version-gate). Published git tags: `v2.0.0`–+`v2.0.5` then `v3.0.0`–`v3.0.6` — there is **no `v2.0.6` tag** (that was+the dev codename that became v3.0.0). The `VERSION` file should read+`3.0.6`. Versioning: `3.0.x` for patches. Pre-2.0 commit messages /+comments still use the `Y1.NNN` counter (Y1.001 → Y1.039) — historical;+do not introduce new `Y` labels.++The authoritative current engineering snapshot is `docs/STATE.md`+(current capabilities, version history, known bugs). The `## 2.0`+capability list+below is retained as historical baseline — everything in it shipped; the+v3.0 additions (Characters, voice LoRA, Image Studio, A2V, Train tab,+capability tiers) are now baseline too.++### What ships in 2.0 (capabilities checklist)++- **Four modes**: T2V, I2V, FFLF (keyframe interpolation), Extend.+- **Joint audio + video** in a single LTX 2.3 forward pass — sound is+ generated WITH the video. Lip-sync, footsteps, ambient noise all+ align at the frame level. mlx 0.31.1 pin is what keeps the vocoder+ output at healthy levels (-9 to -15 dB peak on dialogue prompts).+- **Quality tiers**: `quick` / `balanced` / `standard` / `high`. The+ earlier `draft` key was renamed; do not reintroduce it. `high` =+ Q8 two-stage HQ pipeline + TeaCache, requires Q8 download.+- **Speed modes** for Standard renders: `exact` (full sampler) /+ `boost` (skip up to 2 stable middle steps via adaptive caching) /+ `turbo` (skip up to 3). 23–34 % wall-time savings on stable scenes.+ Disabled for High, Extend, and FFLF where step-skipping breaks+ quality contracts.+- **Sharp upscale** = PiperSR (CoreML) on the Apple Neural Engine.+ Real x2 detail recovery before the ffmpeg fit/encode tail; ~26 s+ overhead on a 5 s × 1024×576 native. The earlier "model" upscale+ path (LTX latent x2) was retired in Y1.026; it remains hidden+ behind `LTX_ENABLE_MODEL_UPSCALE=1` for lab archaeology only.+- **VAE temporal streaming** — long clips no longer freeze at the+ final decode. Patch in `patch_ltx_codec.py` defaults to+ `LTX_VAE_STREAMING=auto`: streams when latent frames > 121 (≈ 5 s),+ full-decodes shorter clips. Helper-side env-var override keeps+ installs that haven't re-applied the patch on the right path too.+- **Filtered hf downloads** (Y1.024+): Q4 ≈ 20 GB, Q8 ≈ 37 GB,+ Gemma ≈ 7.5 GB, optional spatial upscaler ≈ 1 GB. Older builds+ pulled the full upstream repos and bloated to Q4=56 GB / Q8=82 GB+ by including duplicate transformer variants and unused upscalers.+ `update.js` deletes the dupes on existing installs.+- **Hardware-tier auto-config** (`base` / `standard` / `high` / `pro`)+ with realistic per-tier time estimates surfaced on the Quality+ pills. Compact-tier users see honest "~12 min" instead of M-Studio+ numbers.+- **Now-card progress bar** (Y1.039) — phase-aware, denoise-step-aware.+ Computed server-side from history bucket + helper log signals.+ Replaces the old `elapsed / global_avg` ratio that mis-paced both+ Quick and High renders.+- **Gallery race-free** (Y1.039) — `list_outputs()` skips files that+ ffmpeg is still writing (in-flight skip + 2 s mtime cutoff), and+ the `/file` URL carries an `&v=<mtime>` cache-bust so the browser+ fetches the freshest bytes when a file is replaced.+- **CivitAI LoRA browser** built into the panel. `mlx_models/loras/`+ is scanned at boot; sidecar JSON metadata travels with each safetensors.+- **Phosphene 2.0 release badge** — violet `2.0` chip next to the+ wordmark in the panel header. Distinct from the amber `DEV` profile+ badge so dev/prod tabs are distinguishable at a glance.++### Empirical benchmarks (M4 Max 64 GB, "Comfortable" tier)++All numbers are real wall-clock from sidecar `elapsed_sec` on Y1.039 /+v2.0.0 runs today. Output mp4 carries audio in every case.++| Config | Frames | Wall |+|---|---|---|+| T2V Quick · exact · 640×480 | 121 (5 s) | ~ 2 m 14 s |+| T2V Standard · exact · 1280×704 | 121 (5 s) | ~ 7 m 40 s |+| T2V Standard · boost · 1280×704 | 121 (5 s) | ~ 6 m 20 s |+| T2V Standard · turbo · 1280×704 | 121 (5 s) | ~ 5 m 26 s |+| T2V High Q8 · 1280×704 | 121 (5 s) | ~ 11 m 51 s |+| T2V Balanced · turbo · 720p Sharp | 121 (5 s) | **~ 3 m 30 s** |+| T2V Balanced · turbo · 720p Sharp | 241 (10 s) | **~ 8 m 07 s** |+| I2V Standard · exact · 1280×704 | 121 (5 s) | ~ 7 m 51 s |+| I2V Balanced · turbo · 720p Sharp | 121 (5 s) | ~ 3 m 37 s |+| I2V Balanced · turbo · 720p Sharp | 241 (10 s) | ~ 8 m 26 s |+| FFLF · clamped to 768 px (Comfortable cap) | 121 (5 s) | ~ 5 m 29 s |+| Extend · 768 px (Comfortable cap), +3 s | source 121 → output 184 | ~ 15 m 50 s |++The marquee number for the launch thread is the+**Balanced + Turbo + 720p Sharp** recipe: 5-sec clip in 3 m 30 s, 10-sec+in 8 m 07 s. That's the recommended default for "fast HD with audio".+diff --git a/docs/PANEL_REFERENCE.md b/docs/PANEL_REFERENCE.mdnew file mode 100644index 0000000..fa3fd1b--- /dev/null+++ b/docs/PANEL_REFERENCE.md@@ -0,0 +1,340 @@+# Phosphene panel reference: settings, LoRAs, required_files, helper protocol++Moved out of CLAUDE.md (former §15a, §15b, §16, §17).++## 15a. `panel_settings.json` schema++User-controllable preferences. Persisted at `<repo>/state/panel_settings.json`+(Y1.004+); pre-Y1.004 lived at `<repo>/panel_settings.json` and is migrated+on first boot by `_migrate_state_dir()`. State directory is gitignored.++The whole `state/` dir is symlinked into Pinokio's fs.link drive so it+survives Reset → Reinstall (see "Persistent storage / fs.link" in install.js++ update.js). All persisted-state files (`panel_settings.json`,+`panel_queue.json`, `panel_hidden.json`) live there.++Read at panel startup; mutated via `POST /settings`. The helper subprocess+inherits codec env vars from this at spawn — when settings change, the+panel kills the helper so the next job picks up new values.++```jsonc+{+ "version": 2, // bumped from v1 when secrets added+ // Metadata so the UI knows which preset to highlight as active.+ // "custom" means pix_fmt + crf were set manually outside any preset.+ "output_preset": "standard" | "archival" | "web" | "custom",+ "output_pix_fmt": "yuv420p" | "yuv444p" | "yuv422p"+ | "yuv420p10le" | "yuv422p10le" | "yuv444p10le",+ "output_crf": "0".."30", // string (passed via env vars)++ // Secrets. Stored locally only, never sent over the network except+ // as Authorization headers / ?token= URL params to the upstream+ // services (civitai.com, huggingface.co). NEVER returned by GET+ // /settings — the public response surfaces booleans only.+ "civitai_api_key": "", // empty = not configured+ "hf_token": "" // empty = not configured+}+```++### `GET /settings` security contract++The full settings dict — including `civitai_api_key` and `hf_token` —+is read by the backend only. The HTTP API exposes a *masked* view via+`get_settings_public()`:++```jsonc+{+ "version": 2,+ "output_preset": "standard",+ "output_pix_fmt": "yuv420p",+ "output_crf": "18",+ "has_civitai_key": false, // bool, never the value+ "has_hf_token": false // bool, never the value+}+```++This applies on every response that includes settings — success path,+validation errors, helper-restart confirmations. A user with the panel+proxied through ngrok / tunneled to the LAN never leaks their saved+secrets through a status poll.++### Token resolution priority++`_active_civitai_key()` and `_active_hf_token()` resolve the active+token in this order:++1. The saved value in `panel_settings.json` (set via the Settings+ modal). This is the path normal users take.+2. The corresponding env var (`CIVITAI_API_KEY` / `HF_TOKEN`). Power+ users with shell-level config keep working unchanged.++Empty string in #1 falls through to #2. The settings UI's "Clear"+button writes an empty string to #1, so a user who configured a key+in the UI and then wants to revert to env-var-based config can do+so cleanly.++For HF specifically, `huggingface_hub.snapshot_download` *also* reads+`~/.cache/huggingface/token` (the file `hf auth login` writes). We+don't override that file — if neither settings nor `HF_TOKEN` env is+set, the library falls back to that cached file. This means power+users who already ran `hf auth login` get gated LoRAs working without+touching the panel's token settings.++Preset table is the single source of truth, defined in `OUTPUT_PRESETS`+in `mlx_ltx_panel.py`:++| key | pix_fmt | crf | Approx 5s @ 1280×704 | Use case |+|---|---|---|---|---|+| `standard` ⭐ default | yuv420p | 18 | ~7 MB | Visually lossless, plays everywhere (X / IG / Discord) |+| `archival` (UI label "Video production") | yuv444p | 0 | ~50 MB | Mathematically lossless, full 4:4:4 chroma. For color grading, compositing, VFX, anywhere downstream re-encode is expected. Internal key kept as `archival` for backwards compat with settings files saved before the rename. |+| `web` | yuv420p | 23 | ~3 MB | Smallest, mobile / embedding |++`+faststart` is always applied (codec patch) regardless of preset, so+gallery thumbnails always render the first frame instantly.++When adding a new preset: edit `OUTPUT_PRESETS` in `mlx_ltx_panel.py`+and the `order` array in the settings modal JS (`openSettingsModal`).+The blurb shown in the UI is read from the server at modal-open time,+so server is the source of truth — no JS strings to keep in sync.++## 15b. LoRA system++LTX 2.3 supports LoRA adapters via the upstream `apply_loras()` function+in `ltx_core_mlx.loader.fuse_loras`. The fusion is **weight-level**: at+pipeline load time, each LoRA's `(lora_A, lora_B)` matrix pair is+multiplied + added to the corresponding base-model weight, modified in+place, then quantized. This is *not* a runtime adapter — switching+LoRAs requires reloading the pipeline.++### Integration hook++The base `TextToVideoPipeline.load()` checks+`getattr(self, "_pending_loras", None)` and, if present, calls+`_fuse_pending_loras(transformer_weights, lora_paths)` before+quantizing the transformer. Set `pipe._pending_loras = [(path, strength), ...]`+between construction and the first job.++The wrapper in `mlx_warm_helper.py:_attach_loras` does this. It also+resolves HuggingFace repo IDs (`Lightricks/LTX-2.3-22b-IC-LoRA-HDR`)+to local files via `snapshot_download`, picking the largest+`.safetensors` in the repo (LoRA repos sometimes ship auxiliary files+like scene embeddings alongside the main weights).++### Pipeline cache invalidation++`get_pipe(kind, loras=...)` keys the cache on `(kind, frozen LoRA set)`.+Changing the LoRA set forces a pipeline rebuild — the cached pipeline's+weights have the previous LoRA set fused in and there's no clean way+to "unfuse." Cost is the standard ~30s pipeline reload.++The frozen LoRA set is order-insensitive (set hash, not list hash) —+fusion is commutative so `[A, B]` and `[B, A]` produce identical+weights and should hit the same cache entry.++### `mlx_models/loras/` directory++User-installed LoRAs live as `<name>.safetensors` files at the install+root's `mlx_models/loras/` directory. An optional sidecar JSON next to+each `.safetensors` carries display metadata:++```jsonc+{+ "name": "Crisp Enhance",+ "description": "Sharper detail and edge enhancement.",+ "trigger_words": [], // optional, prepended to prompt at submit+ "recommended_strength": 0.8, // 0.0..1.5 typical, displayed as default in slider+ "preview_url": "https://...", // optional, shown in the picker+ "base_model": "LTXV 2.3",+ "civitai_id": 2530917, // optional, for attribution+ "civitai_version_id": 2844417,+ "civitai_url": "https://civitai.com/models/2530917",+ "downloaded_at": "2026-05-01T..."+}+```++Sidecar absent → panel falls back to the filename as the display name+and zero metadata. Sidecar shape matches the JSON `_civitai_download`+writes, so a CivitAI install lands a usable picker entry without any+hand-editing.++### Curated LoRA registry++`CURATED_LORAS` in `mlx_ltx_panel.py` lists Lightricks' official LoRAs+that we know about. Currently:++| key | repo | UI surface | Note |+|---|---|---|---|+| `hdr` | `Lightricks/LTX-2.3-22b-IC-LoRA-HDR` | "HDR" toggle in form | Hidden from picker (`is_hdr_toggle: True`); exposed as a plain checkbox |+| `motion-track` | `Lightricks/LTX-2.3-22b-IC-LoRA-Motion-Track-Control` | Listed in picker | IC-LoRA, needs video conditioning (not yet wired in panel UI) |+| `union-control` | `Lightricks/LTX-2.3-22b-IC-LoRA-Union-Control` | Listed in picker | Same |++All three are **gated** on Hugging Face — users must accept the license+on the model page AND have a valid HF token (`hf auth login`) before+the helper's `snapshot_download` will work. The helper translates the+upstream `GatedRepoError` into a clear actionable error.++### Job spec extension++The `generate` and `extend` actions accept an optional `loras` param:++```jsonc+{+ "action": "generate",+ "id": "...",+ "params": {+ "mode": "t2v",+ "prompt": "...",+ "loras": [+ {"path": "/abs/path/to/style.safetensors", "strength": 0.8},+ {"path": "Lightricks/LTX-2.3-22b-IC-LoRA-HDR", "strength": 1.0}+ ],+ ...+ }+}+```++Path may be a local file or an HF repo id. Strength is clamped to+±2.0 by the panel before sending; values outside the typical 0.0..1.5+range are usually nonsense and risk numerical issues during fusion.++### HDR toggle semantics++The `hdr` boolean on the job (separate from `loras`) is a UI shortcut.+Worker-side, `run_job_inner` resolves it to+`{"path": "Lightricks/LTX-2.3-22b-IC-LoRA-HDR", "strength": 1.0}`+and appends to the LoRA list before calling the helper. Users see+"HDR" as a feature; the LoRA implementation is hidden.++### CivitAI bridge++CivitAI's REST API is the de-facto LoRA distribution hub for LTX 2.3.+Two endpoints proxy through the panel:++- `/civitai/search` filtered to `baseModels=LTXV 2.3` (the canonical+ string CivitAI uses for LTX-2.3 LoRAs as of 2026-05). Cursor-paginated.+- `/civitai/download` streams a `.safetensors` into `mlx_models/loras/`+ + writes a sidecar JSON.++Both endpoints accept an optional `CIVITAI_API_KEY` env var. As of 2025,+CivitAI requires a token for most LoRA downloads (search still works+without). The token goes in `?token=<key>` on the URL — many CDN hops+only honor that form, not the Authorization header.++### Adding a new curated LoRA++1. Edit `CURATED_LORAS` in `mlx_ltx_panel.py` with `id`, `name`,+ `description`, `repo_id`, `default_strength`, and either+ `is_hdr_toggle: True` (= surfaces as a header pill, hidden from+ picker) or `False` (= shows in picker as a usable entry).+2. If `is_hdr_toggle`, also add the HTML toggle pill (next to "No+ music"), the JS sync block, and the `make_job` resolution that maps+ the boolean to the curated repo id.++## 16. `required_files.json` schema++Single source of truth for "what counts as installed." Read by:+- `pinokio.js` → menu rendering (Install vs Resume Install vs Start)+- `mlx_ltx_panel.py` → `/status` and per-job validation+- (indirectly) `install.js` and `download_q8.js` — their `hf download`+ paths must match the `local_dir` declared here.++```jsonc+{+ "_comment": "...",+ "repos": [+ {+ "key": "q4" | "gemma" | "q8",+ "kind": "base" | "optional", // "base" = blocks Start, "optional" = unlock features+ "name": "human-readable label",+ "blurb": "what this is for",+ "repo_id": "<hf-org/repo>", // for `hf download`+ "local_dir": "mlx_models/<repo-name>", // relative to install root+ "size_gb": 25, // approximate, displayed in UI+ "files": [ // every required file inside local_dir+ "transformer-distilled.safetensors",+ "connector.safetensors",+ ...+ ]+ }+ ],+ "env": {+ "marker_paths": [ // OR-checked; first existing path wins+ "ltx-2-mlx/env/pyvenv.cfg", // canonical Pinokio install+ "ltx-2-mlx/.venv/pyvenv.cfg", // alternate manual layouts+ ...+ ]+ },+ "min_size_bytes": 1024 // file must be >= this to count as "complete"+}+```++When the upstream model layout changes, **edit this file first**. The+menu, panel, and install scripts auto-pick up the change.++## 17. Helper protocol (panel ↔ helper)++The helper subprocess (`mlx_warm_helper.py`) speaks newline-delimited+JSON over stdin/stdout. The panel's `WarmHelper` class wraps it.++### Actions panel sends++```jsonc+// Generation request (T2V, I2V, I2V-clean-audio)+{ "action": "generate",+ "id": "<job-id>",+ "params": { "mode": "t2v"|"i2v"|"i2v_clean_audio",+ "prompt": "...", "output_path": "...",+ "height": 704, "width": 1280, "frames": 121,+ "seed": 42, "steps": 8, "image": "<path>" } }++// Extend request+{ "action": "extend",+ "id": "<job-id>",+ "params": { "video_path": "...", "prompt": "...",+ "extend_frames": 5, "extend_direction": "after",+ "extend_steps": 12, "cfg_scale": 1.0,+ "output_path": "...", "seed": 42 } }++// Keyframe (FFLF)+{ "action": "keyframe", "id": "...", "params": {...} }++// Prompt rewrite (Gemma)+{ "action": "enhance", "prompt": "..." }+```++### Events helper emits++```jsonc+{ "event": "ready", "model": "<path>", "low_memory": true } // on startup+{ "event": "log", "line": "free-form panel log line" } // any informational message+{ "event": "done", "id": "...", "output": "<path>",+ "elapsed_sec": 33.6, "seed_used": 42 }+{ "event": "error", "id": "...", "error": "<message>",+ "trace": "<python traceback>" }+{ "event": "exit", "reason": "python_normal_exit"+ | "sigterm(15)"+ | "sigterm(2)"+ | "idle" } // graceful exit+{ "event": "enhanced", "original": "...", "enhanced": "..." } // /prompt/enhance result+```++**No exit event + stdout pipe closes = non-graceful death** (SIGKILL,+SIGSEGV, SIGABRT, SIGBUS). The panel inspects `proc.poll()` returncode+and translates the negative signal number to a name in the user-facing+error.++### Step breadcrumb log lines++The helper emits these inside `generate`/`extend` actions so the panel+can localize a silent death to a phase:++```+step:get_pipe kind=t2v+step:get_pipe done+step:generate_and_save mode=i2v 1280x704 121f steps=8+step:generate_and_save done+```++When a job dies silently, the panel log's last `step:*` line tells you+which phase (pipeline init vs actual generation).+diff --git a/image_engine.py b/image_engine.pyindex 59559d1..5549796 100644--- a/image_engine.py+++ b/image_engine.py@@ -59,6 +59,7 @@ from __future__ import annotationsimport jsonimport os+import reimport threadingimport timeimport urllib.error@@ -825,6 +826,28 @@ def _generate_mock(prompt: str, n: int, width: int, height: int,return results+_EXC_LINE_RX = re.compile(r"^[A-Za-z_][\w.]*(?:Error|Exception|Interrupt|Exit)\s*:\s*\S")+_NOISE_PREFIXES = ("Traceback", 'File "', "During handling", "The above exception",+ "^^^", "~~~", "[", "step")+++def _subprocess_cause_line(lines) -> str:+ """The line in a dead engine subprocess's tail that names the cause: the+ last `SomethingError: ...` line, else the last line that is not traceback+ scaffolding or a progress bar, else "". Same rule as the panel's+ failure_line() (mlx_ltx_panel.py), kept here because this module is+ imported by the panel, not the other way round."""+ clean = [str(t).strip() for t in (lines or ()) if str(t or "").strip()]+ for t in reversed(clean):+ if _EXC_LINE_RX.match(t):+ return t+ for t in reversed(clean):+ if (not t.startswith(_NOISE_PREFIXES) and not t[0].isdigit()+ and "%|" not in t and "it/s]" not in t and "s/it]" not in t):+ return t+ return ""++def _generate_mflux(prompt: str, n: int, width: int, height: int,output_dir: Path, base_seed: int | None,config: ImageEngineConfig,@@ -1449,6 +1472,13 @@ def _generate_mflux(prompt: str, n: int, width: int, height: int,passstderr_tail = "\n".join(last_lines)+ # 4.19.4: the line that NAMES the cause goes on the error's FIRST line.+ # The fleet keeps only that first line (scrubbed), and it used to read+ # "mflux-generate-flux2 failed (exit 1) on batch of 1 seeds. Tail of+ # stdout/stderr:" - two Macs, 21 FLUX.2 failures since 4.16, and not one+ # word of why. The tail still follows in full for the user and the Logs.+ cause = _subprocess_cause_line(last_lines)+ cause_note = f" — last line: {cause[:220]}" if cause else ""# SIGTERM/SIGKILL → user hit /stop. Surface as a typed cancellation# so the queue worker marks the job 'cancelled' rather than 'failed'.if rc in (-15, 143, -9, 137):@@ -1490,7 +1520,7 @@ def _generate_mflux(prompt: str, n: int, width: int, height: int,else "GPU/Metal error from MLX. Could be OOM or a kernel limit.")raise RuntimeError(- f"{bin_name} aborted on batch of {n} seeds (exit {rc}). {hint}\n\n"+ f"{bin_name} aborted on batch of {n} seeds (exit {rc}){cause_note}. {hint}\n\n"f"Try one of:\n"f" - Smaller engine (FLUX.2 [klein] 4B / Z-Image-Turbo) "f"if you picked a 9B/edit model.\n"@@ -1506,7 +1536,7 @@ def _generate_mflux(prompt: str, n: int, width: int, height: int,# traceback puts the exception on its last line, and the head-slice# this used to take cut it off right before the message (#73).raise RuntimeError(- f"{bin_name} failed (exit {rc}) on batch of {n} seeds. "+ f"{bin_name} failed (exit {rc}) on batch of {n} seeds{cause_note}. "f"Tail of stdout/stderr:\n{stderr_tail[-1200:]}")diff --git a/install_qwen.js b/install_qwen.jsindex 12e7e0f..3b2f32f 100644--- a/install_qwen.js+++ b/install_qwen.js@@ -71,14 +71,14 @@ module.exports = {// Step 2: force-reinstall the same version WITHOUT deps so// pip never silently bumps a transitive dep when we// re-run later.- message: "./ltx-2-mlx/env/bin/pip install 'mflux==0.18.0'"+ message: "./ltx-2-mlx/env/bin/pip install -c scripts/pinokio/engine_constraints.txt 'mflux==0.18.0'"}},{method: "shell.run",params: {// Pin-tightening pass — see two-step rationale above.- message: "./ltx-2-mlx/env/bin/pip install --force-reinstall --no-deps 'mflux==0.18.0'"+ message: "./ltx-2-mlx/env/bin/pip install -c scripts/pinokio/engine_constraints.txt --force-reinstall --no-deps 'mflux==0.18.0'"}},{@@ -99,7 +99,7 @@ module.exports = {// API moved (so a mflux bump never *breaks* FLUX.2 — worst case it// loses the speedup). Bumped to the mflux 0.18 line (Ideogram 4 +// Qwen-Edit share this package); re-confirm the FLUX.2 speedup holds.- message: "./ltx-2-mlx/env/bin/pip install 'mlx-teacache==0.4.1'"+ message: "./ltx-2-mlx/env/bin/pip install -c scripts/pinokio/engine_constraints.txt 'mlx-teacache==0.4.1'"}},{diff --git a/install_sharp.js b/install_sharp.jsindex 555b93a..03d83f9 100644--- a/install_sharp.js+++ b/install_sharp.js@@ -9,7 +9,7 @@ module.exports = {{method: "shell.run",params: {- message: "./ltx-2-mlx/env/bin/pip install 'pipersr==1.0.0'"+ message: "./ltx-2-mlx/env/bin/pip install -c scripts/pinokio/engine_constraints.txt 'pipersr==1.0.0'"}},{diff --git a/mlx_ltx_panel.py b/mlx_ltx_panel.pyindex 59f6b31..3a1afad 100644--- a/mlx_ltx_panel.py+++ b/mlx_ltx_panel.py@@ -212,6 +212,93 @@ def engine_env_fault() -> str:if pkgs and not any((d / "ltx_pipelines_mlx").exists() for d in pkgs):return ("the engine venv has a Python but no packages — ""ltx_pipelines_mlx never finished installing into it")+ for d in pkgs:+ mismatch = engine_dependency_mismatch(d)+ if mismatch:+ return f"{ENGINE_ENV_MISMATCH_WORDS} - {mismatch}"+ return ""+++# --- THE THIRD SHAPE: PACKAGES PRESENT, VERSIONS THAT REFUSE (4.19.4) -------+# transformers checks a handful of its dependencies' versions AT IMPORT+# (transformers/dependency_versions_check.py) and raises on a mismatch, and+# every render imports it (the Gemma prompt encoder, through mlx_lm). On+# 2026-10-09 tokenizers 0.23.3 shipped; an Update's eager+# `--upgrade 'litellm…'` moved it there, transformers <5.13 refused it, and+# every render on the install died half a minute in with "tokenizers>=0.22.0,+# <=0.23.0 is required for a normal functioning of this module, but found+# tokenizers==0.23.3" - filed as bad_params, with no way out in the sentence.+# Same question as the package-directory check above, answered from files:+# transformers' own table against the dist-info folders, no import, a few ms.+# A mismatch is a broken environment, so it gets the Repair engine sentence+# (scripts/pinokio/ltx_engine_env.sh resolves under engine_constraints.txt,+# which puts the set back).+ENGINE_ENV_MISMATCH_WORDS = "the engine venv's packages do not fit together"+#: The packages transformers checks at import (its pkgs_to_check_at_runtime,+#: minus python, which is the venv's own).+TRANSFORMERS_RUNTIME_DEPS = ("tqdm", "regex", "packaging", "filelock", "numpy",+ "tokenizers", "huggingface-hub", "safetensors",+ "accelerate", "pyyaml")+++def _dist_versions(site: Path) -> dict:+ """{normalised name: version} from site-packages' *.dist-info folders."""+ out: dict = {}+ try:+ names = [p.name for p in site.iterdir() if p.name.endswith(".dist-info")]+ except OSError:+ return out+ dupes: set = set()+ for n in names:+ stem = n[:-len(".dist-info")]+ name, _, ver = stem.rpartition("-")+ if name and ver:+ key = re.sub(r"[-_.]+", "-", name).lower()+ if key in out and out[key] != ver:+ dupes.add(key)+ out[key] = ver+ # Two dist-info folders for one package (a stale leftover beside the real+ # one): which one Python's importlib.metadata picks is not ours to guess,+ # so say nothing about that package rather than block a working venv+ # (Codex 4.19.4).+ for key in dupes:+ out.pop(key, None)+ return out+++def engine_dependency_mismatch(site: Path) -> str:+ """"" when transformers in `site` will import, else which package is out+ of the range transformers itself requires. Fails open: anything this+ cannot read (no transformers, an unparsable table, no `packaging`) is ""."""+ try:+ table = site / "transformers" / "dependency_versions_table.py"+ if not table.is_file():+ return ""+ import ast+ tree = ast.parse(table.read_text(encoding="utf-8"))+ deps = None+ for node in tree.body:+ if (isinstance(node, ast.Assign) and any(+ isinstance(t, ast.Name) and t.id == "deps" for t in node.targets)):+ deps = ast.literal_eval(node.value)+ if not isinstance(deps, dict):+ return ""+ from packaging.requirements import Requirement+ from packaging.version import Version+ installed = _dist_versions(site)+ tf = installed.get("transformers", "?")+ for pkg in TRANSFORMERS_RUNTIME_DEPS:+ spec = deps.get(pkg)+ have = installed.get(pkg)+ if not spec or not have:+ continue # transformers skips what is not installed too+ req = Requirement(spec)+ if not req.specifier.contains(Version(have), prereleases=True):+ return (f"transformers {tf} needs {spec} but {pkg} {have} is "+ f"installed, so every render would stop at its first "+ f"step")+ except Exception: # noqa: BLE001+ return ""return ""@@ -292,7 +379,7 @@ def _engine_install_running() -> bool:#: The installer's own words (scripts/pinokio/install_cause.sh) plus the two#: the panel can see for itself. docs/ANALYTICS.md, install_step.cause.ENGINE_ENV_CAUSES = ("network", "disk", "uv_error", "python_missing", "timeout",- "installing", "other", "unknown")+ "installing", "mismatch", "other", "unknown")ENGINE_ENV_RESULT_NAME = ".phosphene_engine_result.json"@@ -320,6 +407,11 @@ def engine_env_cause() -> str:return "installing"if not HELPER_PYTHON.is_file():return "python_missing"+ # 4.19.4: the packages are there but transformers refuses their+ # versions (engine_dependency_mismatch) - whatever the last install+ # recorded, that is why this venv cannot render now.+ if ENGINE_ENV_MISMATCH_WORDS in engine_env_fault():+ return "mismatch"rec = engine_env_record() or {}cause = str(rec.get("cause") or "")if rec.get("outcome") == "failed" and cause in ENGINE_ENV_CAUSES:@@ -10544,6 +10636,15 @@ _CRASH_LINE_CLASSES = (("gpu_oom", ("kiogpucommandbuffercallbackerroroutofmemory","insufficient memory")),("gpu_victim", ("innocentvictim", "innocent victim")),+ # 4.19.4: the rest of IOGPU's / Metal's command-buffer error names, so+ # `gpu_other` stops being one bucket. Fleet 4.19.3: an M2 Max (macOS+ # 15.3) died 3 times in prompt encoding with a command-buffer error that+ # was none of the six above - and passed on its next try each time.+ ("gpu_internal", ("internal error", "errorinternal")),+ ("gpu_submissions_ignored", ("submissionsignored", "submissions ignored")),+ ("gpu_invalid_resource", ("invalidresource", "invalid resource")),+ ("gpu_not_permitted", ("notpermitted", "not permitted")),+ ("gpu_device_removed", ("deviceremoved", "device removed")),("gpu_other", ("kiogpucommandbuffercallbackerror","command buffer execution failed", "[metal]")),("resource_limit", ("resource limit",)),@@ -10554,12 +10655,24 @@ _CRASH_LINE_CLASSES = (CRASH_LINES = tuple(c for c, _ in _CRASH_LINE_CLASSES) + ("none",)+#: 4.19.4 (Codex): the plain-language names below are GPU errors only on a+#: line that is about the GPU - "Operation not permitted" in a C++ exception+#: is a file or process permission, not Metal. These classes need a marker.+_CRASH_LINE_GPU_ONLY = ("gpu_internal", "gpu_submissions_ignored",+ "gpu_invalid_resource", "gpu_not_permitted",+ "gpu_device_removed")+_CRASH_LINE_GPU_MARKERS = ("command buffer", "kiogpu", "[metal]", "mtl", "gpu")++def crash_line_class(line: str) -> str:"""The closed class of a native error line, or "" for any other line."""low = str(line or "").lower()if not low:return ""+ gpu_line = any(m in low for m in _CRASH_LINE_GPU_MARKERS)for cls, needles in _CRASH_LINE_CLASSES:+ if cls in _CRASH_LINE_GPU_ONLY and not gpu_line:+ continueif any(n in low for n in needles):return clsreturn ""@@ -18837,6 +18950,11 @@ _ANALYTICS_ERROR_CLASSES = ("runner is behind this panel")),("venv_broken", ("venv", "dangling", "runner missing","no module named",+ # transformers' own import-time version check (4.19.4:+ # tokenizers 0.23.3 under transformers <5.13 - 7 renders+ # on one Mac filed as bad_params on the word "required").+ # A package set that refuses to import is a broken venv.+ "required for a normal functioning of this module",# The engine tree itself is absent. The fleet's shape is# `[Errno 2] No such file or directory: 'ltx-2-mlx<path>'`# (67 events, 2 installs) — the scrubber leaves the@@ -18874,9 +18992,36 @@ _ANALYTICS_ERROR_CLASSES = ()+_ANALYTICS_TB_FRAME_RX = re.compile(r'^\s*File "[^"]*", line \d+')+++def _analytics_drop_tb_frames(text: str) -> str:+ """The error text minus Python traceback frames (`File "…", line N, in f`+ and the source line printed under each).++ 4.19.4: an engine subprocess's error carries its tail, and every frame+ of a traceback out of the engine venv names `…/ltx-2-mlx/env/lib/…` -+ which the `venv_broken` row matches. So EVERY FLUX.2 failure with a+ traceback was filed as a broken venv (two Macs, 21 events since 4.16),+ whatever the exception said. Frames say where, never what: the class is+ decided by the rest."""+ out: list[str] = []+ skip_next = False+ for line in text.splitlines():+ if _ANALYTICS_TB_FRAME_RX.match(line):+ skip_next = True+ continue+ if skip_next and line.startswith((" ", "\t")):+ skip_next = False+ continue+ skip_next = False+ out.append(line)+ return "\n".join(out)++def _analytics_error_class(raw) -> str:"""Map an original error string onto the closed taxonomy."""- s = str(raw or "").strip().lower()+ s = _analytics_drop_tb_frames(str(raw or "")).strip().lower()if not s:return "other"for name, needles in _ANALYTICS_ERROR_CLASSES:diff --git a/scripts/check_post_update.js b/scripts/check_post_update.jsindex 3f29eca..46ba5bb 100644--- a/scripts/check_post_update.js+++ b/scripts/check_post_update.js@@ -272,6 +272,67 @@ for (const [label, re] of [["the IC-LoRA fetches", /IC-LoRA-Colorizer/], ["the Lelse console.log(` ok ${label} is best-effort`)}+// --- 4. EVERY INSTALL INTO THE ENGINE VENV CARRIES THE KNOWN-GOOD SET -------+// 4.19.4 fleet fix. tokenizers 0.23.3 shipped 2026-10-09; Update's+// `uv pip install --upgrade 'litellm>=1.83.14'` (uv's --upgrade is EAGER: it+// re-resolves everything under litellm, which accepts tokenizers <1.0) moved it+// there, and transformers <5.13 refuses to import with it - every render dies.+// A later resolve that included transformers happened to move it back, so the+// install was broken only while the Update was in between; one that stopped+// there (a dropped connection, Pinokio ending the run on an "error:" line)+// stayed broken. A constraints file on EVERY install into the venv closes the+// class: no step, however eager, can leave the set.+{+ const EC_REL = "scripts/pinokio/engine_constraints.txt"+ let ec = ""+ try { ec = fs.readFileSync(path.join(repoRoot, EC_REL), "utf8") } catch (e) {+ failures.push(`${EC_REL} is missing - nothing holds the engine venv to its known-good set.`)+ }+ const ecLines = ec.split("\n").map((l) => l.trim()).filter((l) => l && !l.startsWith("#"))+ const need = [+ ["the transformers cap", (l) => l === "transformers>=5.0.0,<5.13.0"],+ // transformers <5.13 itself requires tokenizers >=0.22.0,<=0.23.0+ ["a tokenizers range inside transformers <5.13's own", (l) => /^tokenizers>=0\.22\.0,<(=)?0\.23\.0$/.test(l)],+ ["the huggingface-hub 1.x range", (l) => l === "huggingface-hub>=1.5.0,<2.0"],+ [`mlx==${PIN_PAIR.mlx}`, (l) => l === `mlx==${PIN_PAIR.mlx}`],+ [`mlx-metal==${PIN_PAIR.mlx}`, (l) => l === `mlx-metal==${PIN_PAIR.mlx}`],+ ["mlx-lm==0.31.1", (l) => l === "mlx-lm==0.31.1"],+ ]+ for (const [label, ok] of need) {+ if (ec && !ecLines.some(ok)) failures.push(`${EC_REL} does not carry ${label}.`)+ }+ if (ec) console.log(` ok ${EC_REL}: ${ecLines.length} constraints`)++ // Every install line, in every file that installs into the engine venv.+ const ecRef = /-c\s+("\$EC"|\$EC\b|scripts\/pinokio\/engine_constraints\.txt)|\$\{EC_ARGS\[@\]/+ const sites = [+ ["scripts/post_update.sh", /\buv pip install\b/],+ ["scripts/pinokio/ltx_engine_env.sh", /\buv pip install\b/],+ ["scripts/pinokio/mflux_pack.sh", /\buv pip install\b/],+ ["scripts/pinokio/a2v_stems_deps.sh", /\bpip install\b/],+ ["install_qwen.js", /\bpip install\b/],+ ["install_sharp.js", /\bpip install\b/],+ ]+ for (const [rel, re] of sites) {+ let text = ""+ try { text = fs.readFileSync(path.join(repoRoot, rel), "utf8") } catch (e) {+ failures.push(`${rel} is missing.`); continue+ }+ const cmds = text.replace(/\\\n/g, " ").split("\n")+ .filter((l) => !/^\s*(#|\/\/|\*)/.test(l) && re.test(l))+ // Count per INSTALL, not per line: `\`-continued chains join several+ // installs into one line, and one -c must not vouch for its neighbours.+ const installRe = /\bpip install\b/g+ const refRe = new RegExp(ecRef.source, "g")+ const bare = cmds.filter((l) => (l.match(installRe) || []).length > (l.match(refRe) || []).length)+ if (!cmds.length) failures.push(`${rel}: no install line found - is this gate still looking at the right file?`)+ else if (bare.length) failures.push(`${rel}: ${bare.length} install line(s) into the engine venv without -c ${EC_REL}: ${bare[0].trim().slice(0, 140)}`)+ else console.log(` ok ${rel}: all ${cmds.reduce((n, l) => n + (l.match(/\bpip install\b/g) || []).length, 0)} install(s) carry the engine constraints`)+ const eager = cmds.filter((l) => /--upgrade\b|\s-U\s/.test(l) && /litellm|smolagents|huggingface-hub|transformers|mflux/.test(l))+ if (eager.length) failures.push(`${rel}: an EAGER --upgrade of a package with a deep dependency tree (${eager[0].trim().slice(0, 120)}) - that is the step that moved tokenizers to 0.23.3.`)+ }+}+console.log("")console.log(failures.length ? `RESULT: FAIL (${failures.length})` : "RESULT: PASS")for (const f of failures) console.log("FAIL " + f)diff --git a/scripts/pinokio/a2v_stems_deps.sh b/scripts/pinokio/a2v_stems_deps.shindex 4c4881c..fdace6b 100755--- a/scripts/pinokio/a2v_stems_deps.sh+++ b/scripts/pinokio/a2v_stems_deps.sh@@ -96,6 +96,11 @@ PY="$VENV/bin/python3.11"export TORCH_HOME="$SEP_HOME"unset PYTORCH_ENABLE_MPS_FALLBACK PYTORCH_MPS_FAST_MATHRUNNER="$APP_ROOT/scripts/a2v_separate.py"+# The engine venv's known-good set (4.19.4) rides along with the torch/numpy+# pins below, so demucs can never move tokenizers / transformers / the mlx trio.+EC="$APP_ROOT/scripts/pinokio/engine_constraints.txt"+EC_ARGS=()+[ -f "$EC" ] && EC_ARGS=(-c "$EC")PROBE='import demucs.pretrained, demucs.apply, torch'if "$PY" -c "$PROBE" >/dev/null 2>&1; then@@ -123,10 +128,10 @@ PYPINSn=1while :; doif command -v uv >/dev/null 2>&1; then- uv pip install --python "$PY" -c "$PINS" 'demucs==4.0.1' 2>&1 | defuse+ uv pip install --python "$PY" -c "$PINS" ${EC_ARGS[@]+"${EC_ARGS[@]}"} 'demucs==4.0.1' 2>&1 | defuserc=$?else- "$PY" -m pip install --retries 5 --timeout 60 -c "$PINS" 'demucs==4.0.1' 2>&1 | defuse+ "$PY" -m pip install --retries 5 --timeout 60 -c "$PINS" ${EC_ARGS[@]+"${EC_ARGS[@]}"} 'demucs==4.0.1' 2>&1 | defuserc=$?fi[ "$rc" -eq 0 ] && breakdiff --git a/scripts/pinokio/engine_constraints.txt b/scripts/pinokio/engine_constraints.txtnew file mode 100644index 0000000..1b4f35e--- /dev/null+++ b/scripts/pinokio/engine_constraints.txt@@ -0,0 +1,37 @@+# THE ENGINE VENV'S KNOWN-GOOD SET (ltx-2-mlx/env) - 4.19.4.+#+# Every `uv pip install` / `pip install` into the engine venv passes this file+# with -c: install.js (scripts/pinokio/ltx_engine_env.sh, mflux_pack.sh,+# a2v_stems_deps.sh), every Update (scripts/post_update.sh), the panel's own+# Repair / image-engine / vocal-separation installers, install_qwen.js and+# install_sharp.js. A constraint never installs anything by itself; it only+# forbids a resolve from leaving these ranges - whatever else that resolve+# was asked for. scripts/check_post_update.js fails the build if an install+# line into the engine venv does not carry it.+#+# WHY (4.19.4 fleet fix). tokenizers 0.23.3 shipped on 2026-10-09. transformers+# below 5.13 (our cap, see post_update.sh 2b) checks at import time that+# tokenizers is >=0.22.0,<=0.23.0 and refuses to load otherwise, and every+# render loads transformers (the Gemma prompt encoder goes through mlx_lm's+# tokenizer). Update's `uv pip install --upgrade 'litellm>=1.83.14'` is an+# EAGER upgrade of litellm and everything under it - litellm asks for+# tokenizers <1.0 - so it moved tokenizers to 0.23.3 and broke every render+# until a later step that resolves transformers happened to move it back. An+# Update that stopped in between left the install unable to render+# ("tokenizers>=0.22.0,<=0.23.0 is required ... but found tokenizers==0.23.3").+#+# Change a line here only together with the scripts that pin the same package+# (the mlx trio: install.js, post_update.sh, ltx_engine_env.sh, mflux_pack.sh -+# check_post_update.js holds them together) and a from-zero install + render.++# transformers <5.13 (5.13.0 breaks every generation - post_update.sh 2b).+transformers>=5.0.0,<5.13.0+# What transformers <5.13 itself requires (no 0.23.0 final exists, so this is+# 0.22.x - the version every install that renders today has).+tokenizers>=0.22.0,<0.23.0+# transformers <5.13 and mflux 0.18.0 both want huggingface-hub 1.x.+huggingface-hub>=1.5.0,<2.0+# The mlx pin (0.31.2 attenuates the vocoder by ~22 dB - post_update.sh step 2).+mlx==0.31.1+mlx-lm==0.31.1+mlx-metal==0.31.1diff --git a/scripts/pinokio/ltx_engine_env.sh b/scripts/pinokio/ltx_engine_env.shindex 1c6ad08..d96e5ff 100755--- a/scripts/pinokio/ltx_engine_env.sh+++ b/scripts/pinokio/ltx_engine_env.sh@@ -41,6 +41,11 @@ APP_ROOT="$(cd "$(dirname "$0")/../.." && pwd)"MLX="${1:-$APP_ROOT/ltx-2-mlx}"cd "$MLX" 2>/dev/null || { echo "FATAL error: no engine checkout at $MLX - run Install"; exit 1; }PY=env/bin/python+# The engine venv's known-good set (4.19.4): every install below passes it with+# -c, so no resolve can leave tokenizers / transformers / huggingface-hub / the+# mlx trio outside what renders. engine_constraints.txt says why each line is there.+EC="$APP_ROOT/scripts/pinokio/engine_constraints.txt"+[ -f "$EC" ] || { echo "FATAL error: scripts/pinokio/engine_constraints.txt is missing - re-run Update"; exit 1; }# OUTCOME RECORD (4.17.5). Every finished run writes env/.phosphene_engine_result# .json: {"outcome","cause","ts"} - closed words only (install_cause.sh), no@@ -101,7 +106,7 @@ LOG="$(mktemp -t phos_engine_env)" || LOG=/dev/nulldefuse() { tee -a "$LOG" | sed -u -e 's/[Ee][Rr][Rr][Oo][Rr]:/problem -/g' -e 's/[Ee]rrno /errno-/g'; }attempt() {- uv pip install --python env/bin/python 'mlx==0.31.1' 'mlx-lm==0.31.1' \+ uv pip install --python env/bin/python -c "$EC" 'mlx==0.31.1' 'mlx-lm==0.31.1' \'mlx-metal==0.31.1' 'transformers>=5.0.0,<5.13.0' 2>&1 | defuse || return 1# The packages' dependencies resolve WITH the pins, the same as# scripts/post_update.sh step 3 (4.19.0). Alone, this resolve took the newest@@ -110,14 +115,14 @@ attempt() {# walked it DOWN to 0.31.2 (mflux 0.18.0 wants <0.32) - every fresh install# since late August ran mlx 0.31.2 with an mlx-arsenal that declares it# cannot. Pinned here the solver picks mlx-arsenal 0.11.1 and mlx stays 0.31.1.- uv pip install --python env/bin/python --build-constraints ../pip-build-constraints.txt \+ uv pip install --python env/bin/python -c "$EC" --build-constraints ../pip-build-constraints.txt \'mlx==0.31.1' 'mlx-lm==0.31.1' 'mlx-metal==0.31.1' 'transformers>=5.0.0,<5.13.0' \./packages/ltx-core-mlx ./packages/ltx-pipelines-mlx ./packages/ltx-trainer 2>&1 | defuse || return 1- uv pip install --python env/bin/python --reinstall --no-deps \+ uv pip install --python env/bin/python -c "$EC" --reinstall --no-deps \--build-constraints ../pip-build-constraints.txt \./packages/ltx-core-mlx ./packages/ltx-pipelines-mlx ./packages/ltx-trainer 2>&1 | defuse || return 1- uv pip install --python env/bin/python --no-deps 'mlx-vlm==0.4.4' 2>&1 | defuse || return 1- uv pip install --python env/bin/python certifi pillow numpy 'huggingface-hub>=1.5.0,<2.0' \+ uv pip install --python env/bin/python -c "$EC" --no-deps 'mlx-vlm==0.4.4' 2>&1 | defuse || return 1+ uv pip install --python env/bin/python -c "$EC" certifi pillow numpy 'huggingface-hub>=1.5.0,<2.0' \'hf_transfer>=0.1.6' 'litellm>=1.83.14' 'smolagents>=1.24.0' 'pywebpush>=2.0' 2>&1 | defuse || return 1# The --reinstall above replaced the patched ltx_core_mlx: put the codec patch# back before anything renders (install.js runs it again after; idempotent).@@ -189,7 +194,7 @@ exit 1# transformers at all, so an existing 5.13.0 survived every Update and# the install stayed unable to generate anything. A promise about# another file now names the step that keeps it.-# (install.js ran: "uv pip install --python env/bin/python 'mlx==0.31.1' 'mlx-lm==0.31.1' 'mlx-metal==0.31.1' 'transformers>=5.0.0,<5.13.0'")+# (install.js ran: "uv pip install --python env/bin/python -c "$EC" 'mlx==0.31.1' 'mlx-lm==0.31.1' 'mlx-metal==0.31.1' 'transformers>=5.0.0,<5.13.0'")# Y3 — Train Character ships in 3.0. Without ltx-trainer-mlx in# the venv, the trainer subprocess fails at `import yaml` because# pyyaml is a transitive dep of ltx-trainer (declared in its@@ -206,7 +211,7 @@ exit 1# pip-build-constraints.txt; update.js runs the same uv command# (it used to spell it `PIP_CONSTRAINT=`, which modern pip ignores# by design — one lane now, one failure mode).-# (install.js ran: "uv pip install --python env/bin/python --build-constraints ../pip-build-constraints.txt ./packages/ltx-core-mlx ./packages/ltx-pipelines-mlx ./packag)+# (install.js ran: "uv pip install --python env/bin/python -c "$EC" --build-constraints ../pip-build-constraints.txt ./packages/ltx-core-mlx ./packages/ltx-pipelines-mlx ./packag)# v4.0 — THE SECOND PASS IS THE POINT, and it closes a trap that has# shipped since the workspace landed. `ltx-2-mlx` is a uv WORKSPACE:# the line above (with deps, without --reinstall) links its members@@ -227,7 +232,7 @@ exit 1# it is the exact command update.js has run for many releases, so# the end state is one every install already converges to on its# first Update. One lane, one runtime shape.-# (install.js ran: "uv pip install --python env/bin/python --reinstall --no-deps --build-constraints ../pip-build-constraints.txt ./packages/ltx-core-mlx ./packages/ltx-)+# (install.js ran: "uv pip install --python env/bin/python -c "$EC" --reinstall --no-deps --build-constraints ../pip-build-constraints.txt ./packages/ltx-core-mlx ./packages/ltx-)# Auto-caption (Gemma 3 12B via mlx-vlm) needs the mlx-vlm# package. Pinned to 0.4.4 — caption_with_gemma.py's import# surface (load, generate, prompt_utils.apply_chat_template)@@ -235,7 +240,7 @@ exit 1# mlx-vlm's heavy default deps (PIL>=10, av, etc. that fight# mflux/transformers pins). The runtime imports it lazily so# a partial install doesn't break the rest of the panel.-# (install.js ran: "uv pip install --python env/bin/python --no-deps 'mlx-vlm==0.4.4'")+# (install.js ran: "uv pip install --python env/bin/python -c "$EC" --no-deps 'mlx-vlm==0.4.4'")# hf_transfer is HuggingFace's Rust-based downloader — 5-10× faster# than the default Python downloader for big repos like Q8 (~25 GB).# The panel sets HF_HUB_ENABLE_HF_TRANSFER=1 in download envs; if the@@ -266,7 +271,7 @@ exit 1# only ever a transitive dep — if a future dep change drops it, the# SSL_CERT_FILE path vanishes and ALL panel stdlib HTTPS breaks.# Naming it here keeps the cert bundle guaranteed-present.-# (install.js ran: "uv pip install --python env/bin/python certifi pillow numpy 'huggingface-hub>=1.5.0,<2.0' 'hf_transfer>=0.1.6' 'litellm>=1.83.14' 'smolagents>=1.24.0)+# (install.js ran: "uv pip install --python env/bin/python -c "$EC" certifi pillow numpy 'huggingface-hub>=1.5.0,<2.0' 'hf_transfer>=0.1.6' 'litellm>=1.83.14' 'smolagents>=1.24.0)# v2.0.3: post-install confirmation that the local packages# actually landed in site-packages. The Y1.034+ patch script's# i2v target tolerates a missing ltx_pipelines_mlx — withoutdiff --git a/scripts/pinokio/mflux_pack.sh b/scripts/pinokio/mflux_pack.shindex 00c6227..e07d463 100644--- a/scripts/pinokio/mflux_pack.sh+++ b/scripts/pinokio/mflux_pack.sh@@ -25,8 +25,8 @@# FBCache patch is applied.echo 'Installing the mflux image-engine pack (Ideogram 4 + Qwen-Edit)…' && \-( uv pip install --python ./ltx-2-mlx/env/bin/python 'mflux==0.18.0' && \- uv pip install --python ./ltx-2-mlx/env/bin/python --reinstall --no-deps 'mflux==0.18.0' && \- uv pip install --python ./ltx-2-mlx/env/bin/python 'mlx-teacache==0.4.1' && \+( uv pip install --python ./ltx-2-mlx/env/bin/python -c scripts/pinokio/engine_constraints.txt 'mflux==0.18.0' && \+ uv pip install --python ./ltx-2-mlx/env/bin/python -c scripts/pinokio/engine_constraints.txt --reinstall --no-deps 'mflux==0.18.0' && \+ uv pip install --python ./ltx-2-mlx/env/bin/python -c scripts/pinokio/engine_constraints.txt 'mlx-teacache==0.4.1' && \./ltx-2-mlx/env/bin/python3.11 patch_mflux_fbcache.py ) \|| echo 'WARN: mflux image-engine install hit an error — video still works; use the Reinstall image engines action to retry image generation.'diff --git a/scripts/post_update.sh b/scripts/post_update.shindex 92e1432..406f309 100644--- a/scripts/post_update.sh+++ b/scripts/post_update.sh@@ -86,6 +86,12 @@ require() {PY="$ROOT/ltx-2-mlx/env/bin/python3.11"VENV_PY="$ROOT/ltx-2-mlx/env/bin/python"HF="$ROOT/ltx-2-mlx/env/bin/hf"+# THE ENGINE VENV'S KNOWN-GOOD SET (4.19.4). EVERY uv pip install into the+# engine venv below passes it with -c, so no step - however eager - can leave+# the venv outside it, and an Update that stops half-way cannot strand an+# install on a set nobody tested. The file says why each line is there.+export EC="$ROOT/scripts/pinokio/engine_constraints.txt" # exported: the bash -c steps read it+[ -f "$EC" ] || { echo "FATAL error: $EC is missing - the repo pull did not land. Re-run Update."; exit 1; }export HF_HUB_ENABLE_HF_TRANSFER=1echo "=== Phosphene post-update — app root: $ROOT ==="@@ -132,7 +138,7 @@ require "the vendored engine pin move" -- bash "$ROOT/scripts/pinokio/ltx_checko# 2026-08-28 measurements behind holding at 0.31.1 rather than moving to# 0.32.x, are in scripts/check_post_update.js and install.js. Read them before# touching this line — and change both pins in one commit or not at all.-require "the mlx 0.31.1 pin" -- uv pip install --python "$VENV_PY" --reinstall --no-deps 'mlx==0.31.1' 'mlx-lm==0.31.1' 'mlx-metal==0.31.1'+require "the mlx 0.31.1 pin" -- uv pip install --python "$VENV_PY" -c "$EC" --reinstall --no-deps 'mlx==0.31.1' 'mlx-lm==0.31.1' 'mlx-metal==0.31.1'# ---- 2b. THE TRANSFORMERS CAP — the one install.js has been promising -------# install.js has said, since the 2026-07-10 ship-blocker, that "uv downgrades an@@ -153,7 +159,7 @@ require "the mlx 0.31.1 pin" -- uv pip install --python "$VENV_PY" --reinstall -# on the SAME uv invocation as the mlx trio (exactly as install.js:268 does it)# so the solver cannot re-widen the cap while satisfying mlx-lm.require "the transformers <5.13.0 cap (5.13.0 breaks every generation)" -- \- uv pip install --python "$VENV_PY" 'mlx==0.31.1' 'mlx-lm==0.31.1' 'mlx-metal==0.31.1' 'transformers>=5.0.0,<5.13.0'+ uv pip install --python "$VENV_PY" -c "$EC" 'mlx==0.31.1' 'mlx-lm==0.31.1' 'mlx-metal==0.31.1' 'transformers>=5.0.0,<5.13.0'# ---- 3. Re-install the three vendored packages ------------------------------# This is what actually moves an existing user's RUNTIME: a bare git checkout@@ -182,8 +188,8 @@ require "the transformers <5.13.0 cap (5.13.0 breaks every generation)" -- \# this is a no-op. It links the workspace members editable — the --reinstall# --no-deps pass right after replaces those links with real copies, exactly# as install.js does.-require "installing the vendored packages' dependencies (mlx-arsenal and the rest)" -- bash -c 'cd "$1/ltx-2-mlx" && shift && uv pip install --python env/bin/python --build-constraints ../pip-build-constraints.txt "$@" ./packages/ltx-core-mlx ./packages/ltx-pipelines-mlx ./packages/ltx-trainer' _ "$ROOT" 'mlx==0.31.1' 'mlx-lm==0.31.1' 'mlx-metal==0.31.1' 'transformers>=5.0.0,<5.13.0'-require "re-installing the three vendored packages" -- bash -c 'cd "$1/ltx-2-mlx" && uv pip install --python env/bin/python --reinstall --no-deps --build-constraints ../pip-build-constraints.txt ./packages/ltx-core-mlx ./packages/ltx-pipelines-mlx ./packages/ltx-trainer' _ "$ROOT"+require "installing the vendored packages' dependencies (mlx-arsenal and the rest)" -- bash -c 'cd "$1/ltx-2-mlx" && shift && uv pip install --python env/bin/python -c "$EC" --build-constraints ../pip-build-constraints.txt "$@" ./packages/ltx-core-mlx ./packages/ltx-pipelines-mlx ./packages/ltx-trainer' _ "$ROOT" 'mlx==0.31.1' 'mlx-lm==0.31.1' 'mlx-metal==0.31.1' 'transformers>=5.0.0,<5.13.0'+require "re-installing the three vendored packages" -- bash -c 'cd "$1/ltx-2-mlx" && uv pip install --python env/bin/python -c "$EC" --reinstall --no-deps --build-constraints ../pip-build-constraints.txt ./packages/ltx-core-mlx ./packages/ltx-pipelines-mlx ./packages/ltx-trainer' _ "$ROOT"# ---- 4. The codec patch — IMMEDIATELY after the reinstall -------------------# It MUST be here: step 3 overwrites site-packages, so a patch applied before@@ -199,10 +205,10 @@ require "the codec patch (without it every render encodes 4:2:0 - blocky faces)"# ---- 5. Trainer transitive deps ---------------------------------------------# ltx-trainer went in with --no-deps above, so pyyaml/pydantic/tqdm/rich were# never resolved; the trainer subprocess dies at `import yaml` without them.-( cd "$ROOT/ltx-2-mlx" && uv pip install --python env/bin/python 'pyyaml>=6.0' 'pydantic>=2.0' 'tqdm>=4.65' 'rich>=13.0' )+( cd "$ROOT/ltx-2-mlx" && uv pip install --python env/bin/python -c "$EC" 'pyyaml>=6.0' 'pydantic>=2.0' 'tqdm>=4.65' 'rich>=13.0' )# pywebpush signs the closed-tab completion alerts (Settings → Completion# alerts). Optional: the panel offers the button only when it imports.-( cd "$ROOT/ltx-2-mlx" && uv pip install --python env/bin/python 'pywebpush>=2.0' )+( cd "$ROOT/ltx-2-mlx" && uv pip install --python env/bin/python -c "$EC" 'pywebpush>=2.0' )# ---- 6. Optional runtime packages -------------------------------------------# mlx-vlm --no-deps on purpose (its default deps fight our mflux/transformers/@@ -215,11 +221,20 @@ require "the codec patch (without it every render encodes 4:2:0 - blocky faces)"# huggingface-hub<1.0.0, which pip refuses to resolve against our >=1.5.0 floor# (ResolutionImpossible — the "blue screen error flashing for a second every# update"), while uv installs both and leaves it warned-but-functional.-( cd "$ROOT/ltx-2-mlx" && uv pip install --python env/bin/python --no-deps 'mlx-vlm==0.4.4' )-uv pip install --python "$VENV_PY" --upgrade 'hf_transfer>=0.1.6'-uv pip install --python "$VENV_PY" --upgrade certifi-uv pip install --python "$VENV_PY" --upgrade 'litellm>=1.83.14'-uv pip install --python "$VENV_PY" --upgrade 'huggingface-hub>=1.5.0,<2.0' 'smolagents>=1.24.0'+( cd "$ROOT/ltx-2-mlx" && uv pip install --python env/bin/python -c "$EC" --no-deps 'mlx-vlm==0.4.4' )+uv pip install --python "$VENV_PY" -c "$EC" --upgrade 'hf_transfer>=0.1.6'+uv pip install --python "$VENV_PY" -c "$EC" --upgrade certifi+# NOT --upgrade (4.19.4). uv's --upgrade is EAGER: it re-resolves every package+# under litellm to its newest release, and litellm accepts tokenizers <1.0 - so+# on 2026-10-09 this line moved tokenizers to 0.23.3, which transformers <5.13+# refuses to import with, and every render failed until step 7 happened to+# resolve transformers and move it back. An Update that stopped in between+# (Pinokio stops a run on an "error:" line, a dropped connection, a closed+# window) left the install unable to render. The floors below still install or+# raise litellm / smolagents when they are missing or too old; -c "$EC" holds+# the rest of the venv where it is.+uv pip install --python "$VENV_PY" -c "$EC" 'litellm>=1.83.14'+uv pip install --python "$VENV_PY" -c "$EC" 'huggingface-hub>=1.5.0,<2.0' 'smolagents>=1.24.0'# ---- 7. The mflux image-engine pack (Ideogram 4 + Qwen-Edit) ----------------# STANDARD since 2026-06-13, for every user — this is what unblocked Ideogram 4@@ -228,9 +243,9 @@ uv pip install --python "$VENV_PY" --upgrade 'huggingface-hub>=1.5.0,<2.0' 'smol# resolves and then the version locks. BEST-EFFORT: video is unaffected if it# fails, and the panel offers a one-click reinstall.echo 'Installing/refreshing the mflux image-engine pack (Ideogram 4 + Qwen-Edit)…'-( uv pip install --python "$VENV_PY" 'mflux==0.18.0' \- && uv pip install --python "$VENV_PY" --reinstall --no-deps 'mflux==0.18.0' \- && uv pip install --python "$VENV_PY" 'mlx-teacache==0.4.1' ) \+( uv pip install --python "$VENV_PY" -c "$EC" 'mflux==0.18.0' \+ && uv pip install --python "$VENV_PY" -c "$EC" --reinstall --no-deps 'mflux==0.18.0' \+ && uv pip install --python "$VENV_PY" -c "$EC" 'mlx-teacache==0.4.1' ) \|| echo 'WARN: mflux image-engine install hit an error — video is unaffected; re-run Update, or use the Reinstall image engines action, to retry.'# The FBCache patch has to follow the step that installs what it patches.@@ -396,20 +411,28 @@ echo 'Trim done.'# could never install a missing `mlx_arsenal`, so it failed the same way every# time (INST-03). mlx_arsenal is imported explicitly because the package roots# import without it — the failure used to surface only at Generate.+# 4.19.4: and transformers, through the module every render loads it from+# (the Gemma prompt encoder reaches it via mlx_lm.tokenizer_utils). transformers+# checks its own dependency versions AT IMPORT and refuses to load on a+# mismatch - tokenizers 0.23.3 under transformers <5.13 was exactly that, and+# every render on the install failed with "tokenizers>=0.22.0,<=0.23.0 is+# required ... but found tokenizers==0.23.3". The repair below resolves+# transformers under -c "$EC", which moves tokenizers back into range, so an+# install that already has the bad set is fixed by this Update.echo 'Verifying the render engine actually imports…'-if ! "$PY" -c "import ltx_core_mlx; import ltx_pipelines_mlx; import mlx; import mlx_arsenal" 2>/dev/null; then+if ! "$PY" -c "import ltx_core_mlx; import ltx_pipelines_mlx; import mlx; import mlx_arsenal; import transformers; import mlx_lm.tokenizer_utils" 2>/dev/null; thenecho 'Render engine did not import — repairing the vendored packages once…'- ( cd "$ROOT/ltx-2-mlx" && uv pip install --python env/bin/python \+ ( cd "$ROOT/ltx-2-mlx" && uv pip install --python env/bin/python -c "$EC" \--build-constraints ../pip-build-constraints.txt \'mlx==0.31.1' 'mlx-lm==0.31.1' 'mlx-metal==0.31.1' 'transformers>=5.0.0,<5.13.0' \./packages/ltx-core-mlx ./packages/ltx-pipelines-mlx ./packages/ltx-trainer \- && uv pip install --python env/bin/python --reinstall \+ && uv pip install --python env/bin/python -c "$EC" --reinstall \--no-deps --build-constraints ../pip-build-constraints.txt \./packages/ltx-core-mlx ./packages/ltx-pipelines-mlx ./packages/ltx-trainer \&& "$PY" "$ROOT/patch_ltx_codec.py" ) \|| truefi-require "the render engine import gate" -- "$PY" -c "import ltx_core_mlx, ltx_pipelines_mlx, mlx, mlx_arsenal"+require "the render engine import gate" -- "$PY" -c "import ltx_core_mlx, ltx_pipelines_mlx, mlx, mlx_arsenal, transformers, mlx_lm.tokenizer_utils"# Music is independent of LTX. Update only an installed checkout; never pull# an 11 GB pack as a side effect of an ordinary panel update.diff --git a/test_crash_line_4192.py b/test_crash_line_4192.pyindex c24686c..e733153 100644--- a/test_crash_line_4192.py+++ b/test_crash_line_4192.py@@ -78,7 +78,10 @@ class TheLineClass(unittest.TestCase):"Error (00000003:kIOGPUCommandBufferCallbackErrorHang)"), "gpu_hang")self.assertEqual(c("Discarded (victim of GPU error/recovery) (00000005:""kIOGPUCommandBufferCallbackErrorInnocentVictim)"), "gpu_victim")+ # 4.19.4: Internal Error has its own class now (test_engine_deps_4194).self.assertEqual(c("[METAL] Command buffer execution failed: Internal Error"),+ "gpu_internal")+ self.assertEqual(c("[METAL] Command buffer execution failed: something new"),"gpu_other")self.assertEqual(c("[metal::malloc] Resource limit (499000) exceeded."),"resource_limit")diff --git a/test_engine_deps_4194.py b/test_engine_deps_4194.pynew file mode 100644index 0000000..e64ab97--- /dev/null+++ b/test_engine_deps_4194.py@@ -0,0 +1,207 @@+"""4.19.4: the engine venv stays on a known-good package set, an install that+already left it is caught before a render and repaired by Update, and the+failures the fleet could not explain now carry their cause.++Fleet since 4.19.3 (2026-10-14): one Mac, 7 i2v renders in a row, every one+"tokenizers>=0.22.0,<=0.23.0 is required for a normal functioning of this+module, but found tokenizers==0.23.3" - filed as bad_params. tokenizers 0.23.3+shipped on 2026-10-09; Update's `uv pip install --upgrade 'litellm>=1.83.14'`+(uv's --upgrade is eager) moved it there, transformers <5.13 refuses it at+import, and every render loads transformers. Re-running Install fixed that Mac.+"""+from __future__ import annotations++import os+import re+import subprocess+import sys+import unittest+from pathlib import Path+from tempfile import TemporaryDirectory++ROOT = Path(__file__).resolve().parent+sys.path.insert(0, str(ROOT))+os.environ.setdefault("PHOSPHENE_ANALYTICS_DISABLED", "1")++import mlx_ltx_panel as P # noqa: E402++EC = ROOT / "scripts" / "pinokio" / "engine_constraints.txt"+HK_ERROR = ("tokenizers>=0.22.0,<=0.23.0 is required for a normal functioning "+ "of this module, but found tokenizers==0.23.3.")+TABLE = '''deps = {+ "numpy": "numpy>=1.17",+ "tokenizers": "tokenizers>=0.22.0,<=0.23.0",+ "huggingface-hub": "huggingface-hub>=1.5.0,<2.0",+ "safetensors": "safetensors>=0.4.3",+ "tqdm": "tqdm>=4.27",+}+'''+++def _constraints() -> list[str]:+ return [l.strip() for l in EC.read_text().splitlines()+ if l.strip() and not l.strip().startswith("#")]+++class KnownGoodSet(unittest.TestCase):+ def test_constraints_file_holds_the_transformers_stack(self):+ lines = _constraints()+ self.assertIn("transformers>=5.0.0,<5.13.0", lines)+ tok = [l for l in lines if l.startswith("tokenizers")]+ self.assertEqual(len(tok), 1, lines)+ # transformers <5.13 requires tokenizers <=0.23.0 - 0.23.3 must be out.+ from packaging.requirements import Requirement+ spec = Requirement(tok[0]).specifier+ self.assertFalse(spec.contains("0.23.3"))+ self.assertTrue(spec.contains("0.22.2"))+ self.assertIn("huggingface-hub>=1.5.0,<2.0", lines)+ for pin in ("mlx==0.31.1", "mlx-lm==0.31.1", "mlx-metal==0.31.1"):+ self.assertIn(pin, lines)++ def _installs(self, rel: str, pattern: str) -> list[str]:+ text = (ROOT / rel).read_text().replace("\\\n", " ")+ out = []+ for line in text.splitlines():+ if re.match(r"^\s*(#|//|\*)", line):+ continue+ out += [line] * len(re.findall(pattern, line))+ return out++ def test_every_install_into_the_engine_venv_carries_the_constraints(self):+ ref = re.compile(r'-c\s+("\$EC"|scripts/pinokio/engine_constraints\.txt)'+ r'|\$\{EC_ARGS\[@\]')+ for rel in ("scripts/post_update.sh", "scripts/pinokio/ltx_engine_env.sh",+ "scripts/pinokio/mflux_pack.sh",+ "scripts/pinokio/a2v_stems_deps.sh",+ "install_qwen.js", "install_sharp.js"):+ text = (ROOT / rel).read_text().replace("\\\n", " ")+ n_install = n_ref = 0+ for line in text.splitlines():+ if re.match(r"^\s*(#|//|\*)", line):+ continue+ k = len(re.findall(r"\bpip install\b", line))+ n_install += k+ n_ref += min(k, len(ref.findall(line)))+ with self.subTest(rel=rel):+ self.assertGreater(n_install, 0)+ self.assertEqual(n_install, n_ref,+ f"{rel}: {n_install} installs, {n_ref} carry -c")++ def test_no_eager_upgrade_of_a_deep_package(self):+ text = (ROOT / "scripts" / "post_update.sh").read_text()+ for line in text.splitlines():+ if line.lstrip().startswith("#"):+ continue+ if "--upgrade" in line:+ self.assertNotRegex(line, r"litellm|smolagents|huggingface-hub|transformers")++ def test_update_import_gate_imports_transformers(self):+ text = (ROOT / "scripts" / "post_update.sh").read_text()+ gate = [l for l in text.splitlines()+ if l.startswith('require "the render engine import gate"')]+ self.assertEqual(len(gate), 1)+ self.assertIn("transformers", gate[0])+ self.assertIn("mlx_lm.tokenizer_utils", gate[0])++ def test_the_js_gate_passes_and_catches_a_bare_install(self):+ r = subprocess.run(["node", str(ROOT / "scripts" / "check_post_update.js")],+ capture_output=True, text=True, errors="replace")+ self.assertEqual(r.returncode, 0, r.stdout[-2000:])+ with TemporaryDirectory() as tmp:+ # A copy of the repo's scripts with ONE install stripped of -c.+ t = Path(tmp)+ for rel in ("scripts/check_post_update.js", "scripts/post_update.sh",+ "scripts/pinokio/ltx_engine_env.sh",+ "scripts/pinokio/mflux_pack.sh",+ "scripts/pinokio/a2v_stems_deps.sh",+ "scripts/pinokio/engine_constraints.txt",+ "install.js", "install_qwen.js", "install_sharp.js"):+ (t / rel).parent.mkdir(parents=True, exist_ok=True)+ (t / rel).write_text((ROOT / rel).read_text())+ mp = t / "scripts" / "pinokio" / "mflux_pack.sh"+ mp.write_text(mp.read_text().replace(+ "-c scripts/pinokio/engine_constraints.txt 'mlx-teacache", "'mlx-teacache", 1))+ r = subprocess.run(["node", str(t / "scripts" / "check_post_update.js")],+ capture_output=True, text=True, errors="replace")+ self.assertNotEqual(r.returncode, 0)+ self.assertIn("mflux_pack.sh", r.stdout)+++class _Venv:+ def __init__(self, tokenizers="0.22.2", table=TABLE):+ self.tokenizers, self.table = tokenizers, table++ def __enter__(self):+ self.tmp = TemporaryDirectory()+ env = Path(self.tmp.name) / "ltx-2-mlx" / "env"+ (env / "bin").mkdir(parents=True)+ (env / "pyvenv.cfg").write_text("home = /usr/bin\n")+ (env / "bin" / "python3.11").write_text("#!/bin/sh\n")+ self.site = site = env / "lib" / "python3.11" / "site-packages"+ (site / "ltx_pipelines_mlx").mkdir(parents=True)+ (site / "transformers").mkdir()+ if self.table is not None:+ (site / "transformers" / "dependency_versions_table.py").write_text(self.table)+ for d in ("transformers-5.7.0", f"tokenizers-{self.tokenizers}",+ "huggingface_hub-1.14.0", "numpy-2.4.6", "safetensors-0.8.0",+ "tqdm-4.70.0", "PyYAML-6.0.2"):+ (site / f"{d}.dist-info").mkdir()+ self.prev = P.HELPER_PYTHON+ P.HELPER_PYTHON = env / "bin" / "python3.11"+ return self++ def __exit__(self, *a):+ P.HELPER_PYTHON = self.prev+ self.tmp.cleanup()+++class CaughtBeforeARender(unittest.TestCase):+ def test_good_set_is_not_a_fault(self):+ with _Venv("0.22.2") as v:+ self.assertEqual(P.engine_dependency_mismatch(v.site), "")+ self.assertEqual(P.engine_env_fault(), "")++ def test_tokenizers_0_23_3_is_a_fault_with_the_repair(self):+ with _Venv("0.23.3") as v:+ m = P.engine_dependency_mismatch(v.site)+ self.assertIn("tokenizers 0.23.3", m)+ self.assertIn("transformers 5.7.0", m)+ fault = P.engine_env_fault()+ self.assertIn("do not fit together", fault)+ self.assertEqual(P.engine_env_cause(), "mismatch")+ # The worker's sentence: a broken venv, with the way out.+ msg = f"engine venv is not usable: {fault}. {P.ENGINE_ENV_REPAIR}"+ self.assertEqual(P._analytics_error_class(msg), "venv_broken")+ self.assertIn("Repair engine", msg)++ def test_a_stale_duplicate_dist_info_fails_open(self):+ # Codex 4.19.4: 0.22.2 AND a leftover 0.23.3 folder - which one+ # importlib picks is not ours to guess; never block on it.+ with _Venv("0.22.2") as v:+ (v.site / "tokenizers-0.23.3.dist-info").mkdir()+ self.assertEqual(P.engine_dependency_mismatch(v.site), "")++ def test_unreadable_table_fails_open(self):+ with _Venv("0.23.3", table="deps = not a dict(") as v:+ self.assertEqual(P.engine_dependency_mismatch(v.site), "")+ with _Venv("0.23.3", table=None) as v:+ self.assertEqual(P.engine_dependency_mismatch(v.site), "")++ def test_helper_refuses_to_spawn_on_a_mismatch(self):+ with _Venv("0.23.3"):+ h = P.WarmHelper()+ with self.assertRaises(RuntimeError) as cm:+ h._ensure()+ self.assertIn("do not fit together", str(cm.exception))+ self.assertIsNone(h.proc)++ def test_the_fleet_error_is_a_broken_venv_not_bad_params(self):+ self.assertEqual(P._analytics_error_class(HK_ERROR), "venv_broken")++ def test_mismatch_is_a_documented_cause(self):+ self.assertIn("mismatch", P.ENGINE_ENV_CAUSES)+ self.assertIn("`mismatch`", (ROOT / "docs" / "ANALYTICS.md").read_text())+++if __name__ == "__main__":+ unittest.main()diff --git a/test_engine_env_repair.py b/test_engine_env_repair.pyindex e23c0e9..3317b4e 100644--- a/test_engine_env_repair.py+++ b/test_engine_env_repair.py@@ -76,6 +76,8 @@ class _App:pin.mkdir(parents=True)shutil.copy(SCRIPT, pin / SCRIPT.name)shutil.copy(CHECK, pin / CHECK.name)+ # 4.19.4: every install in the step passes the engine constraints.+ shutil.copy(SCRIPT.parent / "engine_constraints.txt", pin / "engine_constraints.txt")self.mlx = self.tmp / "ltx-2-mlx"(self.mlx / "env" / "bin").mkdir(parents=True)self.mark = self.tmp / "installed.mark"diff --git a/test_failure_cause_4194.py b/test_failure_cause_4194.pynew file mode 100644index 0000000..1c8fd62--- /dev/null+++ b/test_failure_cause_4194.py@@ -0,0 +1,87 @@+"""4.19.4: the failures the fleet could not explain carry their cause.++Fleet since 4.16: two Macs, 21 FLUX.2 image failures recorded as+"mflux-generate-flux2 failed (exit 1) on batch of 1 seeds. Tail of+stdout/stderr:" - the fleet keeps only that first line - and every one filed as+venv_broken, because the traceback frames under it name ".../ltx-2-mlx/env/lib/".+And since 4.19.2 a helper that dies from a signal reports the class of its last+native line; an M2 Max's three prompt-encoding crashes on 4.19.3 all came back+`gpu_other`, the one bucket that names nothing.+"""+from __future__ import annotations++import os+import sys+import unittest+from pathlib import Path++ROOT = Path(__file__).resolve().parent+sys.path.insert(0, str(ROOT))+os.environ.setdefault("PHOSPHENE_ANALYTICS_DISABLED", "1")++import mlx_ltx_panel as P # noqa: E402+import image_engine as IE # noqa: E402+++class FailuresSayWhy(unittest.TestCase):+ TAIL = [+ "Traceback (most recent call last):",+ ' File "/Users/x/pinokio/api/phosphene.git/ltx-2-mlx/env/lib/python3.11/'+ 'site-packages/mflux/models/flux2/cli.py", line 88, in main',+ " image = model.generate_image(seed=seed)",+ "ValueError: height must be divisible by 16",+ ]++ def test_image_failure_first_line_names_the_cause(self):+ self.assertEqual(IE._subprocess_cause_line(self.TAIL),+ "ValueError: height must be divisible by 16")++ def test_traceback_frames_do_not_make_a_broken_venv(self):+ err = ("mflux-generate-flux2 failed (exit 1) on batch of 1 seeds"+ " — last line: ValueError: height must be divisible by 16. "+ "Tail of stdout/stderr:\n" + "\n".join(self.TAIL))+ self.assertNotEqual(P._analytics_error_class(err), "venv_broken")+ self.assertEqual(P._analytics_error_class(err), "helper_exit")+ # ...while a real broken venv still is one.+ self.assertEqual(P._analytics_error_class(+ "mflux-generate-flux2 failed (exit 1) — last line: "+ "ModuleNotFoundError: No module named 'mflux'"), "venv_broken")++ def test_signature_keeps_the_cause(self):+ err = ("mflux-generate-flux2 failed (exit 1) on batch of 1 seeds"+ " — last line: ValueError: height must be divisible by 16. "+ "Tail of stdout/stderr:\n...")+ self.assertIn("ValueError", P._analytics_scrub_text(err))++ def test_metal_command_buffer_errors_are_named(self):+ cases = {+ "[METAL] Command buffer execution failed: Internal Error "+ "(0000000e:Internal Error)": "gpu_internal",+ "Command buffer execution failed: (00000009:kIOGPUCommandBufferCallback"+ "ErrorSubmissionsIgnored)": "gpu_submissions_ignored",+ "(kIOGPUCommandBufferCallbackErrorInvalidResource)": "gpu_invalid_resource",+ "kIOGPUCommandBufferCallbackErrorBackgroundExecutionNotPermitted":+ "gpu_not_permitted",+ "Caused GPU Timeout Error (00000002:kIOGPUCommandBufferCallbackErrorTimeout)":+ "gpu_timeout",+ "[METAL] something else entirely": "gpu_other",+ }+ for line, cls in cases.items():+ with self.subTest(line=line):+ self.assertEqual(P.crash_line_class(line), cls)+ self.assertIn(cls, P.CRASH_LINES)+ # Codex 4.19.4: a permission error that is not about the GPU stays+ # a C++ exception.+ self.assertEqual(P.crash_line_class(+ "libc++abi: terminating due to uncaught exception of type "+ "std::runtime_error: open: Operation not permitted"), "cxx_exception")+ self.assertEqual(P.crash_line_class(+ "libc++abi: terminating due to uncaught exception of type "+ "std::runtime_error: internal error in the decoder"), "cxx_exception")+ doc = (ROOT / "docs" / "ANALYTICS.md").read_text()+ for cls in P.CRASH_LINES:+ self.assertIn(f"`{cls}`", doc)+++if __name__ == "__main__":+ unittest.main()