fix(run): resolve the bundled default checkpoint at runtime (BE-2994)

[mattmillerai]

ELI-5

comfy run --prompt "a fox" (no --workflow) runs a tiny built-in text2img
workflow. That workflow had one specific checkpoint filename baked in. If the
machine (or Comfy Cloud, or a fresh install) didn't have that exact file, the
run failed — often with a cryptic server-side error. This PR makes the CLI look
at what checkpoints the target actually has and use one, so a zero-config run
produces an image wherever any checkpoint exists — and gives a clear,
actionable error when there are truly none.

What changed

1. Fixed the stale pin. cql/data/default_text2img.json node "4"
ckpt_name is now v1-5-pruned-emaonly-fp16.safetensors (the file the
   gallery default.json and the text-to-image tutorial use), replacing the
   stale v1-5-pruned-emaonly.ckpt.

2. Runtime checkpoint resolution. New pure, offline-testable helper
   resolve_default_checkpoint(workflow, object_info) in
   cql/default_workflow.py:

   • pinned checkpoint present in the target's enum → no change;
   • pinned absent but the target has ≥1 checkpoint → substitute the first
     available and emit a note;
   • target positively enumerates zero checkpoints → flag it (hard error, below);
   • enum absent / object_info unfetchable ({}) → fail open (unchanged
     behavior — submit and let the server answer).

   Wired into both run paths (local execute + execute_cloud) after
   object_info is fetched and before _preflight_validate. It only acts on
   the bundled default graph (workflow_name == "default_text2img") and is
   skipped entirely when the user pinned the checkpoint via --set checkpoint=…
   / --set 4.ckpt_name=… (honored verbatim; a checkpoint_user_set flag is
   threaded through the preloaded tuple).

3. Actionable no-checkpoint error. When the target positively has zero
   checkpoints, a new registered no_checkpoint_available error (exit 1) with a
   download hint (local) / gallery-template guidance (cloud) replaces the cryptic
   server reject. Fail-open behavior is preserved when object_info can't be
   fetched at all.

Substitution is surfaced as a checkpoint_substituted NDJSON event (--json)
and a one-line pretty notice otherwise.

Acceptance criteria

• default_text2img.json uses v1-5-pruned-emaonly-fp16.safetensors; fixtures/tests updated.
• Missing-default-but-has-others → succeeds using the first available + emits a note; --set checkpoint=<name> always honored verbatim.
• Default present → unchanged, no note.
• Zero checkpoints (empty enum) → no_checkpoint_available + exit 1; object_info {} → fail-open submit (unchanged).
• Both --where local and --where cloud.
• New unit tests for resolve_default_checkpoint (present / substituted / empty-enum / user-pinned) + wiring tests; ruff/pytest green.

Testing

uv run --extra dev pytest tests/comfy_cli/cql tests/comfy_cli/command/test_run_prompt.py tests/comfy_cli/command/test_run.py tests/comfy_cli/command/test_run_json.py tests/comfy_cli/command/test_run_cli.py tests/comfy_cli/output → 488 passed. ruff format --check clean on all touched files.

Judgment calls / notes

• Return shape. The ticket suggested resolve_default_checkpoint(...) -> (workflow, note|None), but a bare note can't distinguish "pinned present (fine)" from "enum positively empty (error)" — both would be None. I returned a small CheckpointResolution dataclass (note / substituted_to / no_checkpoint) so the caller can drive step 3 precisely and only hard-error when it positively knows the enum is empty.
• --print-prompt is unchanged. The dry-run returns before the server round-trip, so it prints the bundled pin, not the runtime-resolved checkpoint (consistent with --print-prompt's existing "no server hit" contract). The prompt_preview event (emitted before resolution) likewise shows the pre-substitution graph; the explicit checkpoint_substituted event documents the swap in the stream.
• Event schema. checkpoint_substituted is not added to schemas/run_event.json's type enum — that enum is already non-exhaustive (prompt_preview/converted aren't in it either; additionalProperties: true), so I matched the established pattern rather than partially expanding it.
• Not a capability-denial regression (falsification). The new no_checkpoint_available deny path is capability-enabling on net: runtime resolution makes --prompt succeed wherever any checkpoint exists (the opposite of a dead-end). The error fires only in the provably-empty-enum case — a state where the workflow genuinely cannot run (no checkpoint to load) — and its hint redirects to the real fix (install a model / gallery template / --set). Fail-open is preserved for every ambiguous case.

Out of scope

Restructuring the bundled default to the gallery's newer Z-Image-Turbo graph (multi-file diffusion) is a larger, separate change and a product call on the blessed default model. Runtime resolution deliberately sidesteps that choice.

[coderabbitai]

📝 Walkthrough

Walkthrough

Changes

The bundled text-to-image workflow now uses an FP16 safetensors checkpoint and resolves it against runtime checkpoint metadata. Local and cloud execution preserve explicit overrides, substitute unavailable defaults when possible, and report missing local checkpoints with a registered error.

Sequence Diagram(s)

sequenceDiagram
  participant RunCommand
  participant Execute
  participant ObjectInfo
  participant CheckpointResolver
  participant Renderer
  RunCommand->>Execute: pass workflow and checkpoint_user_set
  Execute->>ObjectInfo: load target metadata
  Execute->>CheckpointResolver: resolve default checkpoint
  CheckpointResolver-->>Execute: updated workflow and resolution result
  Execute->>Renderer: emit preview or substitution event
  Execute->>Execute: preflight and submit

Loading

Possibly related PRs

• Comfy-Org/comfy-cli#511: Both changes adjust cloud object_info loading and preflight preparation in execute_cloud.

Suggested reviewers: bigcat88

🚥 Pre-merge checks | ✅ 2

✅ Passed checks (2 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch matt/be-2994-runtime-default-checkpoint

✨ Simplify code

• Create PR with simplified code
• Commit simplified code in branch matt/be-2994-runtime-default-checkpoint

---

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

🔍 Cursor Review — Consolidated panel

Triggered by @mattmillerai.

Found 7 finding(s).

Severity	Count
🟡 Medium	3
🟢 Low	4

Panel: 6/8 reviewers contributed findings.

Reviewers that did not contribute: kimi-k2.5:adversarial (empty), kimi-k2.5:edge-case (empty)

[mattmillerai]

Reviews resolver pass — all 7 review threads are now resolved, and no code changes were needed.

Review threads: 5 were already fixed in 93cfdfb. The 2 remaining were deferred/declined with reasoning; rather than leave them as loose unresolved threads, both are now recorded as tracked follow-ups (renderer events in single-envelope JSON; architecture-aware checkpoint substitution) and resolved. Neither is tagged for autonomous pickup — each needs a design decision first.

Merge state: MERGEABLE, no conflict with main.

The failing test check is NOT from this PR — it is a repo-wide CI failure.

test-windows.yml ("Windows Specific Commands") has failed 20 of 20 recent runs across every branch, including many PRs sharing no code with this one (be-3271, be-3272, be-3265, be-3268, be-3266, be-3270, be-2999, be-3000, …). Last green run on main was 2026-03-11 (1405d30). A gh run rerun --failed reproduced it identically (job 87814223657), so it is deterministic, not a flake.

Root cause: the workflow pip install -e . into venv, then runs comfy install --fast-deps from that same venv. uv tries to replace pydantic-core, but the live comfy process has already imported pydantic (via mixpanel), so Windows holds the loaded DLL open:

error: failed to remove file `...\venv\Lib\site-packages\pydantic_core/_pydantic_core.cp312-win_amd64.pyd`: Access is denied. (os error 5)
→ ImportError: cannot import name '__version__' from 'pydantic_core' (unknown location)

This PR touches only cmdline.py, command/run/{__init__,preflight}.py, cql/default_workflow.py, cql/data/default_text2img.json, error_codes.py + tests — nothing in the install/dependency path. Filed as a separate high-severity follow-up; fixing CI infra inside this behavioural PR would mask a repo-wide problem.

Verified locally: 63/63 PR tests pass (test_run_prompt.py, test_default_workflow.py), ruff check clean. Full suite: 2588 passed / 9 failed — the 9 (test_config_parser.py, test_node_init.py) are pre-existing, fail identically with main's copies of those files, are untouched by this PR, and pass in CI on all platforms (local git-env artifact).

All other checks green: ruff, build, CodeQL, GPU runners, and Tests on macos/ubuntu/windows 3.10.

[mattmillerai]

🤖 The reviews loop filed Linear follow-up ticket(s) for review thread(s) deferred as out of scope for this PR:

• https://linear.app/comfyorg/issue/BE-3281|BE-3281 — Fix repo-wide Windows CI failure: uv cannot replace pydantic_core .pyd locked by the running comfy process
• https://linear.app/comfyorg/issue/BE-3282|BE-3282 — Surface renderer events (e.g. checkpoint_substituted) in single-envelope JSON output
• https://linear.app/comfyorg/issue/BE-3283|BE-3283 — Prefer an architecture-compatible checkpoint instead of enum[0] when the bundled default is missing

[bigcat88]

This PR currently conflicts with main — GitHub reports mergeable: CONFLICTING, so it needs a rebase before I can review it and I'm skipping it in the current review sweep.

Please rebase (or merge main in) and I'll pick it up on the next pass. main moved a fair bit in the last day, including #614 (ANSI sanitisation across the pretty-print call sites) and #628 (the duplicate server_died error-code fix that had main red), so a refresh may also clear unrelated CI noise on this branch.

[mattmillerai]

Rebased on `main` — the merge conflict blocking review (in `comfy_cli/cmdline.py` and `tests/comfy_cli/command/test_run_prompt.py`) is resolved. Both conflicts were between this branch's runtime checkpoint-resolution work and `main`'s simpler static "needs a checkpoint" warning notice (`TestDefaultCheckpointNotice`); kept this branch's runtime resolution (which supersedes the static warning) and dropped main's now-superseded notice/tests accordingly.

Verified on the merged tree: full suite (3431 passed / 37 skipped), `ruff check`/`ruff format --diff` clean against the CI-pinned ruff 0.15.15.

The failing Windows test check is the pre-existing repo-wide CI issue already tracked as BE-3281 (uv can't replace a locked .pyd on Windows) — unrelated to this PR's changes, not re-fixed here per the prior resolver pass's reasoning (fixing CI infra inside this behavioral PR would mask the repo-wide problem). All 7 review threads were already resolved in a prior pass.

@bigcat88 conflict is cleared — ready for another look whenever convenient.

[coderabbitai]

Actionable comments posted: 5

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@comfy_cli/cmdline.py`:
- Around line 949-960: Refresh the --prompt option help text near the prompt
argument definition to reference v1-5-pruned-emaonly-fp16.safetensors instead of
the obsolete checkpoint name, and accurately describe that the CLI may
substitute an installed checkpoint at runtime. Leave the build_default_workflow
and checkpoint override behavior unchanged.

In `@comfy_cli/command/run/__init__.py`:
- Around line 741-749: Reuse the cloud object_info loaded by the UI conversion
branch instead of calling _load_from_target twice. Initialize a shared
object_info dictionary before the is_ui branch, assign the existing cloud
snapshot to it when available, and have the later checkpoint-resolution block
use that value while preserving the empty-dictionary fallback on load failure.

In `@comfy_cli/cql/default_workflow.py`:
- Around line 359-364: Update the basename matching in the checkpoint resolution
logic around the pinned string and enum entries to handle both `/` and `\`
separators. Normalize or split both values using platform-independent separator
handling before comparing basenames, while preserving the existing checkpoint
assignment and early return behavior; add coverage for a backslash-separated
enum entry if tests are available.

In `@tests/comfy_cli/command/test_run_prompt.py`:
- Around line 27-28: Move the shared _object_info_with_checkpoints helper from
tests/comfy_cli/command/test_run_prompt.py and
tests/comfy_cli/cql/test_default_workflow.py into the appropriate shared
conftest.py, then update both test modules to use the centralized helper and
remove their local duplicate definitions.

In `@tests/comfy_cli/cql/test_default_workflow.py`:
- Line 265: Replace the unused out binding in the resolve_default_checkpoint
test with an underscore assignment, while preserving the existing res value and
test behavior.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: a98f9f22-4138-4a69-8c7b-4617eaff458c

📥 Commits

Reviewing files that changed from the base of the PR and between 46e6cf7 and c1c11c9.

📒 Files selected for processing (8)

• comfy_cli/cmdline.py
• comfy_cli/command/run/__init__.py
• comfy_cli/command/run/preflight.py
• comfy_cli/cql/data/default_text2img.json
• comfy_cli/cql/default_workflow.py
• comfy_cli/error_codes.py
• tests/comfy_cli/command/test_run_prompt.py
• tests/comfy_cli/cql/test_default_workflow.py

[mattmillerai]

Reviews resolver pass — CodeRabbit's 5 threads are all resolved; 4 fixed in ee688b8, 1 declined with reasoning.

Fixed

• --prompt help text was stale on both counts (comfy_cli/cmdline.py) — still named v1-5-pruned-emaonly.ckpt and still claimed the checkpoint "is NOT downloaded for you", with no mention of the runtime substitution this PR adds.
• Cloud path fetched /object_info twice (comfy_cli/command/run/__init__.py) — once to lower UI→API, then again for checkpoint resolution + preflight. _load_from_target is a live, uncached HTTPS fetch, so this was a genuine second round-trip, not just tidiness. Now loaded once and shared. Sentinel is None rather than falsiness, so a fetched-but-empty snapshot does not trigger a redundant refetch.
• Basename match split on / only (comfy_cli/cql/default_workflow.py) — folder_paths builds relative names with the server's separator, so a Windows host enumerating SD1.5\v1-5-pruned-emaonly-fp16.safetensors missed the intended checkpoint and substituted enum[0] with a warning. Normalized via a module-level _basename helper, with a regression test.
• Dropped an unused out binding in a resolver test (Pylint W0612).

Declined: hoisting the two-line _object_info_with_checkpoints stub into a shared conftest. The two copies live in different test packages whose only shared ancestor is tests/comfy_cli/conftest.py, so it would widen a fixture's blast radius to every test under tests/comfy_cli/ to serve two modules, and move the asserted shape away from the tests that read it. Reasoning is on the thread.

Verification: full suite 3432 passed / 37 skipped; ruff format clean on all touched files. (Local ruff check flags UP038 in default_workflow.py, but that is pre-existing on untouched code and absent under the newer CI-pinned ruff — ruff_check is green.)

Status: all 15 CI checks pass, including Run Tests on Multiple Platforms (windows-latest) — the repo-wide Windows failure tracked as BE-3281 is no longer firing on this branch. MERGEABLE against main, no conflict. Not stacked. Awaiting human review — I do not merge.

[mattmillerai]

Reviews resolver pass — main had moved forward again since the last pass (adding allow_spend to execute/execute_cloud), reintroducing a merge conflict with this branch's runtime-checkpoint preloaded 4-tuple param. Merged main and kept both additions side by side (preloaded: tuple[dict, str, bool, bool] | None + allow_spend: bool = False) in both function signatures; cmdline.py's call sites already threaded both correctly post auto-merge.

No unresolved review threads found (all 7 CodeRabbit threads from the prior pass were already resolved). Verified on the merged tree: full suite (3669 passed / 37 skipped), ruff format --check clean on touched files. Local ruff check flags 17 pre-existing UP038 issues, all confirmed present on untouched origin/main code — not introduced here.

MERGEABLE against main, not stacked. Awaiting human review — I do not merge.

[coderabbitai]

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (3)

comfy_cli/command/run/__init__.py (2)

261-268: 🚀 Performance & Scalability | 🟡 Minor | ⚡ Quick win

Reuse the UI conversion snapshot.

For UI workflows, line 215 already fetched object_info; lines 266-268 replace it with {} and fetch again. Reuse the successful conversion snapshot so one run does not make two /object_info requests or validate against a different schema snapshot.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@comfy_cli/command/run/__init__.py` around lines 261 - 268, Update the
object_info initialization in the non-print-prompt flow to reuse the successful
UI conversion snapshot fetched around line 215, rather than resetting it to an
empty dict and calling _fetch_object_info again. Preserve the existing
print_prompt behavior of skipping the fetch and leaving the graph unchanged.

---

821-852: 🎯 Functional Correctness | 🟠 Major | ⚡ Quick win

Keep cloud --print-prompt server-independent.

This loads cloud object_info and resolves/substitutes the checkpoint before checking print_prompt. Thus comfy run --where cloud --prompt ... --print-prompt can contact cloud and print a mutated graph, contrary to the documented dry-run behavior and PR objective. Move the print branch before the snapshot/resolution path; UI-format conversion may retain its necessary schema fetch.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@comfy_cli/command/run/__init__.py` around lines 821 - 852, Move the cloud
`print_prompt` branch before the `cloud_object_info` loading and
`_resolve_default_checkpoint_or_exit` calls so `--print-prompt` remains
server-independent and prints the unmutated parsed workflow. Preserve any
necessary UI-format schema fetch, while ensuring snapshot loading and checkpoint
resolution only run for requests that will be submitted.

comfy_cli/cmdline.py (1)

1192-1200: 📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win

Wrap the partner-node warning line.

Line 1199 is 140 characters, exceeding the configured 120-character limit.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@comfy_cli/cmdline.py` around lines 1192 - 1200, Wrap the long partner-node
warning expression in the partner_nodes block, preserving the existing Rich
escaping and warning text while keeping each source line within the
120-character limit.

Sources: Learnings, Linters/SAST tools

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Outside diff comments:
In `@comfy_cli/cmdline.py`:
- Around line 1192-1200: Wrap the long partner-node warning expression in the
partner_nodes block, preserving the existing Rich escaping and warning text
while keeping each source line within the 120-character limit.

In `@comfy_cli/command/run/__init__.py`:
- Around line 261-268: Update the object_info initialization in the
non-print-prompt flow to reuse the successful UI conversion snapshot fetched
around line 215, rather than resetting it to an empty dict and calling
_fetch_object_info again. Preserve the existing print_prompt behavior of
skipping the fetch and leaving the graph unchanged.
- Around line 821-852: Move the cloud `print_prompt` branch before the
`cloud_object_info` loading and `_resolve_default_checkpoint_or_exit` calls so
`--print-prompt` remains server-independent and prints the unmutated parsed
workflow. Preserve any necessary UI-format schema fetch, while ensuring snapshot
loading and checkpoint resolution only run for requests that will be submitted.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 235f1dcd-b1d9-43d8-a2d8-a6eb7291dd59

📥 Commits

Reviewing files that changed from the base of the PR and between c1c11c9 and d15080e.

📒 Files selected for processing (6)

• comfy_cli/cmdline.py
• comfy_cli/command/run/__init__.py
• comfy_cli/command/run/preflight.py
• comfy_cli/cql/default_workflow.py
• comfy_cli/error_codes.py
• tests/comfy_cli/cql/test_default_workflow.py