From c5e00c130b07ab4fb49c7d99cfddbe78c383f950 Mon Sep 17 00:00:00 2001
From: Vito Sansevero <vito.sansevero@gmail.com>
Date: Fri, 16 Oct 2026 08:08:00 -0700
Subject: [PATCH 1/5] feat(xyz_helpers): add Checkpoint Folder Iterator and
 Model Compare Sheet

- Checkpoint Folder Iterator loads one checkpoint per queued run from a
  folder (relative to models/checkpoints or absolute), so a whole folder
  can be swept with only one model in memory at a time
- Model Compare Sheet saves each run's image as a tile under
  output/model_compare/<run_name>/ and rebuilds a labeled contact sheet
  from disk every run, so the grid survives between independent prompts
- Starting a sweep at index 0 archives stale tiles to a timestamped folder
- Running past the last checkpoint raises a clear error instead of
  wrapping, so an over-queued batch never restarts and archives a
  finished sweep
- Checkpoints load from the scanned absolute path, so folders outside the
  configured roots work as the tooltip promises
- Extract the LoRA Folder Batch folder-scanning, natural-sort and regex
  filter helpers into kikotools/base/model_folders.py so both tools share
  one implementation
---
 README.md                                     |  22 +++
 kikotools/__init__.py                         |   6 +
 kikotools/base/model_folders.py               | 106 ++++++++++++++
 .../checkpoint_folder_iterator/__init__.py    |   5 +
 .../tools/checkpoint_folder_iterator/logic.py |  52 +++++++
 .../tools/checkpoint_folder_iterator/node.py  |  80 +++++++++++
 .../tools/model_compare_sheet/__init__.py     |   5 +
 kikotools/tools/model_compare_sheet/logic.py  | 119 ++++++++++++++++
 kikotools/tools/model_compare_sheet/node.py   | 110 ++++++++++++++
 .../xyz_helpers/lora_folder_batch/logic.py    | 134 ++----------------
 tests/unit/base/__init__.py                   |   0
 tests/unit/base/test_model_folders.py         |  57 ++++++++
 .../checkpoint_folder_iterator/__init__.py    |   0
 .../checkpoint_folder_iterator/test_logic.py  |  99 +++++++++++++
 .../checkpoint_folder_iterator/test_node.py   |  71 ++++++++++
 .../tools/model_compare_sheet/__init__.py     |   0
 .../tools/model_compare_sheet/test_logic.py   |  79 +++++++++++
 .../tools/model_compare_sheet/test_node.py    | 125 ++++++++++++++++
 18 files changed, 948 insertions(+), 122 deletions(-)
 create mode 100644 kikotools/base/model_folders.py
 create mode 100644 kikotools/tools/checkpoint_folder_iterator/__init__.py
 create mode 100644 kikotools/tools/checkpoint_folder_iterator/logic.py
 create mode 100644 kikotools/tools/checkpoint_folder_iterator/node.py
 create mode 100644 kikotools/tools/model_compare_sheet/__init__.py
 create mode 100644 kikotools/tools/model_compare_sheet/logic.py
 create mode 100644 kikotools/tools/model_compare_sheet/node.py
 create mode 100644 tests/unit/base/__init__.py
 create mode 100644 tests/unit/base/test_model_folders.py
 create mode 100644 tests/unit/tools/checkpoint_folder_iterator/__init__.py
 create mode 100644 tests/unit/tools/checkpoint_folder_iterator/test_logic.py
 create mode 100644 tests/unit/tools/checkpoint_folder_iterator/test_node.py
 create mode 100644 tests/unit/tools/model_compare_sheet/__init__.py
 create mode 100644 tests/unit/tools/model_compare_sheet/test_logic.py
 create mode 100644 tests/unit/tools/model_compare_sheet/test_node.py

diff --git a/README.md b/README.md
index afeb975..a1da383 100644
--- a/README.md
+++ b/README.md
@@ -50,6 +50,8 @@ Advanced parameter management tools adapted from [comfyui-essentials-nodes](http
 |------|-------------|----------|
 | [🎛️ Flux Sampler Params](#️-flux-sampler-params) | FLUX-optimized parameter generator with batch support | 🧰 xyz-helpers |
 | [📁 LoRA Folder Batch](#-lora-folder-batch) | Batch process multiple LoRAs from folders | 🧰 xyz-helpers |
+| [🔁 Checkpoint Folder Iterator](#-checkpoint-folder-iterator) | Load one checkpoint per queued run from a folder | 🧰 xyz-helpers |
+| [🧩 Model Compare Sheet](#-model-compare-sheet) | Save each run's image and rebuild a labeled contact sheet | 🧰 xyz-helpers |
 | [📊 Plot Parameters](#-plot-parameters) | Visualize parameter effects with graphs | 🧰 xyz-helpers |
 | [🎯 Sampler Select Helper](#-sampler-select-helper) | Intelligent sampler selection with recommendations | 🧰 xyz-helpers |
 | [📅 Scheduler Select Helper](#-scheduler-select-helper) | Optimal scheduler selection for samplers | 🧰 xyz-helpers |
@@ -301,6 +303,26 @@ Automated batch processing for multiple LoRA models from folders.
 
 ![LoRA Folder Batch Example](examples/workflows/xyz_helpers_lora_testing.png)
 
+#### 🔁 Checkpoint Folder Iterator
+Run the same prompt through every checkpoint in a folder, one model per queued run.
+
+- **folder**: relative to `models/checkpoints`, or an absolute path anywhere on disk; regex include/exclude filters
+- **index** with `control_after_generate`: set 0 + *increment*, then queue a batch count equal to the checkpoint count
+- Queuing past the last checkpoint fails that run with a clear message instead of wrapping around, so the finished sweep is never restarted or archived by accident
+- Outputs MODEL/CLIP/VAE for the indexed file plus `ckpt_name`, `label`, `index`, `count`
+- Only one checkpoint is loaded at a time, so large folders do not exhaust RAM
+
+#### 🧩 Model Compare Sheet
+Output node that pairs with Checkpoint Folder Iterator.
+
+- Saves each run's image(s) to `output/model_compare/<run_name>/<NN>_<label>.png`
+- Rebuilds `grid.png` from every tile saved so far, each labeled with its filename
+- `columns`, `tile_width`, `font_size` control the layout; the grid is also returned as IMAGE
+- The node preview (and anything else that reads it) gets `grid_preview.png`, at most 1024 px wide; `grid.png` keeps full resolution
+- After the last queued run the preview shows the complete sheet
+- Wire Project File Path into `run_name` for `project/date/sweep` folders
+- A run at index 0 moves tiles already in the folder to `<run_name>_<timestamp>`, so an interrupted sweep never leaks into the new grid
+
 #### 📊 Plot Parameters
 Visual analysis tool for understanding parameter relationships and effects.
 
diff --git a/kikotools/__init__.py b/kikotools/__init__.py
index dc20c6f..f93cc80 100644
--- a/kikotools/__init__.py
+++ b/kikotools/__init__.py
@@ -10,6 +10,7 @@ from .tools.batch_list_converter import (
     LatentListToLatentBatchNode,
 )
 from .tools.batch_prompts import BatchPromptsNode
+from .tools.checkpoint_folder_iterator import CheckpointFolderIteratorNode
 from .tools.display_any import DisplayAnyNode
 from .tools.display_text import DisplayTextNode
 from .tools.embedding_autocomplete import KikoEmbeddingAutocomplete
@@ -23,6 +24,7 @@ from .tools.kiko_workflow_timer import KikoWorkflowTimerNode
 from .tools.kiko_save_image import KikoSaveImageNode
 from .tools.local_image_loader import LocalImageLoaderNode
 from .tools.project_file_path import ProjectFilePathNode
+from .tools.model_compare_sheet import ModelCompareSheetNode
 from .tools.model_downloader import ModelDownloaderNode
 from .tools.resolution_calculator import ResolutionCalculatorNode
 from .tools.sampler_combo import SamplerComboCompactNode, SamplerComboNode
@@ -69,6 +71,8 @@ NODE_CLASS_MAPPINGS = {
     "FluxSamplerParams": FluxSamplerParamsNode,
     "PlotParameters+": PlotParametersNode,
     "LoRAFolderBatch": LoRAFolderBatchNode,
+    "CheckpointFolderIterator": CheckpointFolderIteratorNode,
+    "ModelCompareSheet": ModelCompareSheetNode,
     "WidthHeightToVec2": WidthHeightToVec2Node,
     "KikoWorkflowTimer": KikoWorkflowTimerNode,
     "KikoProjectFilePath": ProjectFilePathNode,
@@ -105,6 +109,8 @@ NODE_DISPLAY_NAME_MAPPINGS = {
     "FluxSamplerParams": "Flux Sampler Parameters",
     "PlotParameters+": "Plot Parameters",
     "LoRAFolderBatch": "LoRA Folder Batch",
+    "CheckpointFolderIterator": "Checkpoint Folder Iterator",
+    "ModelCompareSheet": "Model Compare Sheet",
     "WidthHeightToVec2": "Width Height to VEC2",
     "KikoWorkflowTimer": "Workflow Timer",
     "KikoProjectFilePath": "Project File Path",
diff --git a/kikotools/base/model_folders.py b/kikotools/base/model_folders.py
new file mode 100644
index 0000000..8b5ce03
--- /dev/null
+++ b/kikotools/base/model_folders.py
@@ -0,0 +1,106 @@
+"""Scan ComfyUI model folders (loras, checkpoints, ...) for .safetensors files."""
+
+import logging
+import os
+import re
+from typing import Dict, List, Optional, Tuple
+
+logger = logging.getLogger(__name__)
+
+
+def get_model_roots(folder_key: str) -> List[str]:
+    """Return every configured root directory for a folder_paths key."""
+    try:
+        import folder_paths
+
+        entry = folder_paths.folder_names_and_paths.get(folder_key)
+        return list(entry[0]) if entry else []
+    except (ImportError, AttributeError, IndexError, TypeError):
+        return []
+
+
+def is_within(path: str, root: str) -> bool:
+    """True if realpath `path` equals or is inside realpath `root`."""
+    try:
+        real_path, real_root = os.path.realpath(path), os.path.realpath(root)
+        return os.path.commonpath([real_path, real_root]) == real_root
+    except ValueError:  # different drives or mixed absolute/relative
+        return False
+
+
+def resolve_scan_targets(
+    folder_path: str, folder_key: str
+) -> List[Tuple[str, Optional[str]]]:
+    """
+    Resolve a folder setting to (directory, base_root) pairs to scan.
+
+    base_root is the model root the directory lives in, or None when the
+    directory is an absolute path outside every known root.
+    """
+    roots = get_model_roots(folder_key)
+
+    if os.path.isabs(folder_path):
+        base = next((r for r in roots if is_within(folder_path, r)), None)
+        return [(folder_path, base)]
+
+    targets = []
+    for root in roots:
+        candidate = os.path.join(root, folder_path)
+        if not is_within(candidate, root):
+            logger.warning(f"Folder escapes the {folder_key} directory: {folder_path}")
+            continue
+        targets.append((candidate, root))
+    return targets
+
+
+def scan_model_entries(folder_path: str, folder_key: str) -> List[Tuple[str, str]]:
+    """Return naturally sorted (relative_name, absolute_path) for every .safetensors."""
+    entries: Dict[str, str] = {}
+    for directory, base in resolve_scan_targets(folder_path, folder_key):
+        if not os.path.isdir(directory):
+            continue
+        for root, _, files in os.walk(directory):
+            for file in files:
+                if not file.endswith(".safetensors"):
+                    continue
+                full = os.path.join(root, file)
+                try:
+                    rel = os.path.relpath(full, base or directory)
+                except ValueError:
+                    rel = os.path.relpath(full, directory)
+                entries.setdefault(rel.replace("\\", "/"), full)
+    return [(name, entries[name]) for name in natural_sort(list(entries))]
+
+
+def natural_sort(items: List[str]) -> List[str]:
+    """Sort strings so embedded numbers compare numerically (v2 < v10)."""
+
+    def natural_key(text):
+        parts = []
+        for part in re.split(r"(\d+)", text):
+            if not part:
+                continue
+            parts.append((0, int(part)) if part.isdigit() else (1, part.lower()))
+        return parts
+
+    return sorted(items, key=natural_key)
+
+
+def filter_by_pattern(
+    names: List[str], include_pattern: str = "", exclude_pattern: str = ""
+) -> List[str]:
+    """Keep names matching include_pattern (if set) and not exclude_pattern (if set)."""
+    filtered = list(names)
+    if include_pattern:
+        try:
+            include_re = re.compile(include_pattern)
+            filtered = [f for f in filtered if include_re.search(f)]
+        except re.error as e:
+            logger.error(f"Invalid include pattern: {e}")
+    if exclude_pattern:
+        try:
+            exclude_re = re.compile(exclude_pattern)
+            filtered = [f for f in filtered if not exclude_re.search(f)]
+        except re.error as e:
+            logger.error(f"Invalid exclude pattern: {e}")
+    return filtered
diff --git a/kikotools/tools/checkpoint_folder_iterator/__init__.py b/kikotools/tools/checkpoint_folder_iterator/__init__.py
new file mode 100644
index 0000000..37999d1
--- /dev/null
+++ b/kikotools/tools/checkpoint_folder_iterator/__init__.py
@@ -0,0 +1,5 @@
+"""Checkpoint Folder Iterator module."""
+
+from .node import CheckpointFolderIteratorNode
+
+__all__ = ["CheckpointFolderIteratorNode"]
diff --git a/kikotools/tools/checkpoint_folder_iterator/logic.py b/kikotools/tools/checkpoint_folder_iterator/logic.py
new file mode 100644
index 0000000..11a9bab
--- /dev/null
+++ b/kikotools/tools/checkpoint_folder_iterator/logic.py
@@ -0,0 +1,52 @@
+"""Logic for the Checkpoint Folder Iterator node."""
+
+import os
+from typing import List, Sequence, Tuple, TypeVar
+
+from ...base.model_folders import filter_by_pattern, scan_model_entries
+
+T = TypeVar("T")
+
+
+def list_checkpoint_entries(
+    folder_path: str, include_pattern: str = "", exclude_pattern: str = ""
+) -> List[Tuple[str, str]]:
+    """(name, absolute_path) pairs for every checkpoint, filtered, in natural order.
+
+    The absolute path is what gets loaded, so folders outside the configured
+    checkpoints roots work too; the name is relative to the root (or to the
+    folder itself when it lives outside every root) and is used for labels.
+    """
+    entries = scan_model_entries(folder_path, "checkpoints")
+    names = [name for name, _ in entries]
+    kept = set(filter_by_pattern(names, include_pattern, exclude_pattern))
+    return [(name, path) for name, path in entries if name in kept]
+
+
+def list_checkpoints(
+    folder_path: str, include_pattern: str = "", exclude_pattern: str = ""
+) -> List[str]:
+    """Checkpoint names (relative to the checkpoints roots) in natural order."""
+    entries = list_checkpoint_entries(folder_path, include_pattern, exclude_pattern)
+    return [name for name, _ in entries]
+
+
+def pick_checkpoint(items: Sequence[T], index: int) -> T:
+    """Return items[index], or raise when the sweep has run past the end.
+
+    Wrapping would silently restart the sweep (and, downstream, archive the
+    grid that just finished), so an over-queued run fails loudly instead.
+    """
+    if not items:
+        raise ValueError("No checkpoints found")
+    if not 0 <= index < len(items):
+        raise ValueError(
+            f"Index {index} is past the end: only {len(items)} checkpoints matched. "
+            "The sweep is complete; reset index to 0 to start a new one."
+        )
+    return items[index]
+
+
+def label_for(ckpt_name: str) -> str:
+    """Label drawn under a tile for this checkpoint. Default: the file stem."""
+    return os.path.splitext(os.path.basename(ckpt_name))[0]
diff --git a/kikotools/tools/checkpoint_folder_iterator/node.py b/kikotools/tools/checkpoint_folder_iterator/node.py
new file mode 100644
index 0000000..de99bfa
--- /dev/null
+++ b/kikotools/tools/checkpoint_folder_iterator/node.py
@@ -0,0 +1,80 @@
+"""Checkpoint Folder Iterator node for ComfyUI."""
+
+from typing import Tuple
+
+from ...base.base_node import ComfyAssetsBaseNode
+from .logic import label_for, list_checkpoint_entries, pick_checkpoint
+
+
+class CheckpointFolderIteratorNode(ComfyAssetsBaseNode):
+    """
+    Load one checkpoint from a folder per queued run.
+
+    Set index to 0 with "increment" and queue as many runs as there are
+    checkpoints: each run loads the next file, so only one model is in
+    memory at a time. A run past the last checkpoint fails with a clear
+    error rather than wrapping around, so over-queuing never restarts the
+    sweep. Pairs with Model Compare Sheet to build a labeled grid.
+    """
+
+    @classmethod
+    def INPUT_TYPES(cls):
+        return {
+            "required": {
+                "folder": (
+                    "STRING",
+                    {
+                        "default": ".",
+                        "multiline": False,
+                        "tooltip": "Folder relative to models/checkpoints (or absolute)",
+                    },
+                ),
+                "index": (
+                    "INT",
+                    {
+                        "default": 0,
+                        "min": 0,
+                        "max": 9999,
+                        "control_after_generate": True,
+                        "tooltip": "Which checkpoint to load; errors past the end",
+                    },
+                ),
+            },
+            "optional": {
+                "include_pattern": (
+                    "STRING",
+                    {"default": "", "tooltip": "Regex to include (empty = all)"},
+                ),
+                "exclude_pattern": (
+                    "STRING",
+                    {"default": "", "tooltip": "Regex to exclude (empty = none)"},
+                ),
+            },
+        }
+
+    RETURN_TYPES = ("MODEL", "CLIP", "VAE", "STRING", "STRING", "INT", "INT")
+    RETURN_NAMES = ("model", "clip", "vae", "ckpt_name", "label", "index", "count")
+    FUNCTION = "load"
+    CATEGORY = "🫶 ComfyAssets/🧰 xyz-helpers"
+
+    def load(
+        self,
+        folder: str,
+        index: int,
+        include_pattern: str = "",
+        exclude_pattern: str = "",
+    ) -> Tuple[object, object, object, str, str, int, int]:
+        import folder_paths
+        import comfy.sd
+
+        entries = list_checkpoint_entries(folder, include_pattern, exclude_pattern)
+        ckpt_name, ckpt_path = pick_checkpoint(entries, index)
+        self.log_info(f"Loading {index + 1}/{len(entries)}: {ckpt_name}")
+
+        model, clip, vae = comfy.sd.load_checkpoint_guess_config(
+            ckpt_path,
+            output_vae=True,
+            output_clip=True,
+            embedding_directory=folder_paths.get_folder_paths("embeddings"),
+        )[:3]
+        return model, clip, vae, ckpt_name, label_for(ckpt_name), index, len(entries)
diff --git a/kikotools/tools/model_compare_sheet/__init__.py b/kikotools/tools/model_compare_sheet/__init__.py
new file mode 100644
index 0000000..4fbd163
--- /dev/null
+++ b/kikotools/tools/model_compare_sheet/__init__.py
@@ -0,0 +1,5 @@
+"""Model Compare Sheet module."""
+
+from .node import ModelCompareSheetNode
+
+__all__ = ["ModelCompareSheetNode"]
diff --git a/kikotools/tools/model_compare_sheet/logic.py b/kikotools/tools/model_compare_sheet/logic.py
new file mode 100644
index 0000000..8bbd570
--- /dev/null
+++ b/kikotools/tools/model_compare_sheet/logic.py
@@ -0,0 +1,119 @@
+"""Logic for the Model Compare Sheet node: tile files on disk into a labeled grid."""
+
+import math
+import os
+import re
+from datetime import datetime
+from typing import List, Optional
+
+from PIL import Image, ImageDraw, ImageFont
+
+from ...base.model_folders import is_within, natural_sort
+
+GRID_FILENAME = "grid.png"
+PREVIEW_FILENAME = "grid_preview.png"
+PREVIEW_WIDTH = 1024
+BACKGROUND = (28, 28, 28)
+LABEL_COLOR = (235, 235, 235)
+
+
+def resolve_run_dir(output_dir: str, run_name: str) -> str:
+    """Directory for one compare run, always inside output/model_compare."""
+    if not run_name or os.path.isabs(run_name) or ".." in run_name.split("/"):
+        raise ValueError(f"Invalid run_name: {run_name!r}")
+    run_dir = os.path.join(output_dir, "model_compare", run_name)
+    if not is_within(run_dir, output_dir):
+        raise ValueError(f"Invalid run_name: {run_name!r}")
+    return run_dir
+
+
+def tile_filename(index: int, label: str, batch_index: int, batch_size: int) -> str:
+    """'03_label.png', or '03_label_2.png' for the second image of a batch."""
+    safe = re.sub(r"[^A-Za-z0-9._-]+", "_", label)
+    suffix = f"_{batch_index + 1}" if batch_size > 1 else ""
+    return f"{index:02d}_{safe}{suffix}.png"
+
+
+def label_from_filename(filename: str) -> str:
+    stem = os.path.splitext(os.path.basename(filename))[0]
+    return re.sub(r"^\d+_", "", stem)
+
+
+def list_tiles(run_dir: str) -> List[str]:
+    """PNG tiles in a run directory in natural order, excluding the grid itself."""
+    names = [
+        f
+        for f in os.listdir(run_dir)
+        if f.lower().endswith(".png") and f not in (GRID_FILENAME, PREVIEW_FILENAME)
+    ]
+    return [os.path.join(run_dir, f) for f in natural_sort(names)]
+
+
+def archive_previous_sweep(run_dir: str) -> Optional[str]:
+    """Rename a run folder that already holds tiles to '<run_dir>_<timestamp>'.
+
+    Called when a sweep starts over (index 0) so stale tiles from an
+    interrupted sweep never end up in the new grid. Returns the archive path,
+    or None when there was nothing to archive.
+    """
+    if not os.path.isdir(run_dir) or not list_tiles(run_dir):
+        return None
+    stamp = datetime.fromtimestamp(os.path.getmtime(run_dir)).strftime("%Y%m%d-%H%M%S")
+    archive = f"{run_dir}_{stamp}"
+    n = 1
+    while os.path.exists(archive):
+        n += 1
+        archive = f"{run_dir}_{stamp}_{n}"
+    os.rename(run_dir, archive)
+    return archive
+
+
+def _font(font_size: int) -> ImageFont.ImageFont:
+    try:
+        return ImageFont.truetype("DejaVuSans.ttf", font_size)
+    except OSError:
+        return ImageFont.load_default(size=font_size)
+
+
+def _fit_label(draw: ImageDraw.ImageDraw, text: str, font, max_width: int) -> str:
+    while text and draw.textlength(text, font=font) > max_width:
+        text = text[:-2] + "…" if len(text) > 1 else ""
+    return text
+
+
+def build_contact_sheet(
+    paths: List[str], columns: int, tile_width: int, font_size: int
+) -> Image.Image:
+    """Tile the images at `paths` into a grid with each file's label underneath."""
+    tiles = []
+    for path in paths:
+        with Image.open(path) as im:
+            im = im.convert("RGB")
+            tile_height = max(1, round(im.height * tile_width / im.width))
+            tiles.append((im.resize((tile_width, tile_height), Image.LANCZOS), path))
+
+    band = font_size * 2
+    cell_height = max(t.height for t, _ in tiles) + band
+    cols = min(len(tiles), columns)
+    rows = math.ceil(len(tiles) / cols)
+    sheet = Image.new("RGB", (cols * tile_width, rows * cell_height), BACKGROUND)
+    draw = ImageDraw.Draw(sheet)
+    font = _font(font_size)
+
+    for i, (tile, path) in enumerate(tiles):
+        x = (i % cols) * tile_width
+        y = (i // cols) * cell_height
+        sheet.paste(tile, (x, y))
+        label = _fit_label(draw, label_from_filename(path), font, tile_width - 8)
+        text_x = x + (tile_width - draw.textlength(label, font=font)) / 2
+        text_y = y + tile.height + (band - font_size) / 2
+        draw.text((text_x, text_y), label, fill=LABEL_COLOR, font=font)
+    return sheet
+
+
+def preview_of(sheet: Image.Image) -> Image.Image:
+    """A copy of the sheet no wider than PREVIEW_WIDTH, for the node preview and galleries."""
+    if sheet.width <= PREVIEW_WIDTH:
+        return sheet
+    height = max(1, round(sheet.height * PREVIEW_WIDTH / sheet.width))
+    return sheet.resize((PREVIEW_WIDTH, height), Image.LANCZOS)
diff --git a/kikotools/tools/model_compare_sheet/node.py b/kikotools/tools/model_compare_sheet/node.py
new file mode 100644
index 0000000..8bfa1e8
--- /dev/null
+++ b/kikotools/tools/model_compare_sheet/node.py
@@ -0,0 +1,110 @@
+"""Model Compare Sheet node for ComfyUI."""
+
+import json
+import os
+from typing import Dict, Optional
+
+import numpy as np
+import torch
+from PIL import Image
+from PIL.PngImagePlugin import PngInfo
+
+from ...base.base_node import ComfyAssetsBaseNode
+from .logic import (
+    GRID_FILENAME,
+    PREVIEW_FILENAME,
+    archive_previous_sweep,
+    build_contact_sheet,
+    list_tiles,
+    preview_of,
+    resolve_run_dir,
+    tile_filename,
+)
+
+
+class ModelCompareSheetNode(ComfyAssetsBaseNode):
+    """
+    Save each run's image into output/model_compare/<run_name>/ and rebuild a
+    labeled contact sheet from every tile saved so far. Pair with Checkpoint
+    Folder Iterator: after the last queued run the grid holds every model.
+    """
+
+    @classmethod
+    def INPUT_TYPES(cls):
+        return {
+            "required": {
+                "images": ("IMAGE",),
+                "label": ("STRING", {"forceInput": True}),
+                "index": ("INT", {"forceInput": True}),
+                "run_name": (
+                    "STRING",
+                    {
+                        "default": "illustrious",
+                        "tooltip": "Subfolder of output/model_compare for this run",
+                    },
+                ),
+                "columns": ("INT", {"default": 5, "min": 1, "max": 32}),
+                "tile_width": ("INT", {"default": 512, "min": 64, "max": 4096}),
+                "font_size": ("INT", {"default": 28, "min": 8, "max": 256}),
+            },
+            "hidden": {"prompt": "PROMPT", "extra_pnginfo": "EXTRA_PNGINFO"},
+        }
+
+    RETURN_TYPES = ("IMAGE",)
+    RETURN_NAMES = ("grid",)
+    FUNCTION = "collect"
+    OUTPUT_NODE = True
+    CATEGORY = "🫶 ComfyAssets/🧰 xyz-helpers"
+
+    def collect(
+        self,
+        images: torch.Tensor,
+        label: str,
+        index: int,
+        run_name: str,
+        columns: int,
+        tile_width: int,
+        font_size: int,
+        prompt: Optional[Dict] = None,
+        extra_pnginfo: Optional[Dict] = None,
+    ):
+        import folder_paths
+
+        output_dir = folder_paths.get_output_directory()
+        run_dir = resolve_run_dir(output_dir, run_name)
+        if index == 0:
+            archived = archive_previous_sweep(run_dir)
+            if archived:
+                self.log_info(f"New sweep: previous tiles moved to {archived}")
+        os.makedirs(run_dir, exist_ok=True)
+
+        metadata = PngInfo()
+        if prompt is not None:
+            metadata.add_text("prompt", json.dumps(prompt))
+        for key, value in (extra_pnginfo or {}).items():
+            metadata.add_text(key, json.dumps(value))
+
+        for i, image in enumerate(images):
+            array = (image.cpu().numpy().clip(0, 1) * 255).round().astype(np.uint8)
+            name = tile_filename(index, label, i, images.shape[0])
+            Image.fromarray(array).save(os.path.join(run_dir, name), pnginfo=metadata)
+
+        sheet = build_contact_sheet(list_tiles(run_dir), columns, tile_width, font_size)
+        sheet.save(os.path.join(run_dir, GRID_FILENAME))
+        preview_of(sheet).save(os.path.join(run_dir, PREVIEW_FILENAME))
+        self.log_info(f"Contact sheet: {run_dir}/{GRID_FILENAME}")
+
+        grid = torch.from_numpy(np.asarray(sheet).astype(np.float32) / 255.0)[None]
+        subfolder = os.path.relpath(run_dir, output_dir)
+        return {
+            "ui": {
+                "images": [
+                    {
+                        "filename": PREVIEW_FILENAME,
+                        "subfolder": subfolder,
+                        "type": "output",
+                    }
+                ]
+            },
+            "result": (grid,),
+        }
diff --git a/kikotools/tools/xyz_helpers/lora_folder_batch/logic.py b/kikotools/tools/xyz_helpers/lora_folder_batch/logic.py
index 8b802c2..8987164 100644
--- a/kikotools/tools/xyz_helpers/lora_folder_batch/logic.py
+++ b/kikotools/tools/xyz_helpers/lora_folder_batch/logic.py
@@ -3,9 +3,16 @@
 import math
 import os
 import re
-from typing import List, Dict, Any, Optional, Tuple
+from typing import List, Dict, Any, Tuple
 import logging
 
+from ....base.model_folders import (
+    filter_by_pattern,
+    natural_sort,
+    resolve_scan_targets,
+    scan_model_entries,
+)
+
 logger = logging.getLogger(__name__)
 
 MAX_STRENGTH_VALUES = 1000
@@ -40,66 +47,9 @@ def get_lora_folders() -> List[str]:
         return [".", "flux", "sdxl", "sd15"]
 
 
-def _get_lora_roots() -> List[str]:
-    """Return every configured loras root directory (empty if unavailable)."""
-    try:
-        import folder_paths
-
-        entry = folder_paths.folder_names_and_paths.get("loras")
-        return list(entry[0]) if entry else []
-    except (ImportError, AttributeError, IndexError, TypeError):
-        return []
-
-
-def _is_within(path: str, root: str) -> bool:
-    """True if realpath `path` equals or is inside realpath `root`."""
-    try:
-        real_path, real_root = os.path.realpath(path), os.path.realpath(root)
-        return os.path.commonpath([real_path, real_root]) == real_root
-    except ValueError:  # different drives or mixed absolute/relative
-        return False
-
-
-def _resolve_scan_targets(folder_path: str) -> List[Tuple[str, Optional[str]]]:
-    """
-    Resolve a folder setting to (directory, base_root) pairs to scan.
-
-    base_root is the loras root the directory lives in, or None when the
-    directory is an absolute path outside every known root.
-    """
-    roots = _get_lora_roots()
-
-    if os.path.isabs(folder_path):
-        base = next((r for r in roots if _is_within(folder_path, r)), None)
-        return [(folder_path, base)]
-
-    targets = []
-    for root in roots:
-        candidate = os.path.join(root, folder_path)
-        if not _is_within(candidate, root):
-            logger.warning(f"Folder escapes the loras directory: {folder_path}")
-            continue
-        targets.append((candidate, root))
-    return targets
-
-
 def _scan_entries(folder_path: str) -> List[Tuple[str, str]]:
     """Return (relative_name, absolute_path) for every .safetensors found."""
-    entries: Dict[str, str] = {}
-    for directory, base in _resolve_scan_targets(folder_path):
-        if not os.path.isdir(directory):
-            continue
-        for root, _, files in os.walk(directory):
-            for file in files:
-                if not file.endswith(".safetensors"):
-                    continue
-                full = os.path.join(root, file)
-                try:
-                    rel = os.path.relpath(full, base or directory)
-                except ValueError:
-                    rel = os.path.relpath(full, directory)
-                entries.setdefault(rel.replace("\\", "/"), full)
-    return [(name, entries[name]) for name in natural_sort(list(entries))]
+    return scan_model_entries(folder_path, "loras")
 
 
 def scan_folder_for_loras(folder_path: str) -> List[str]:
@@ -164,71 +114,11 @@ def sort_lora_files(lora_files: List[str], sort_order: str) -> List[str]:
         return lora_files
 
 
-def natural_sort(items: List[str]) -> List[str]:
-    """
-    Sort strings naturally, handling numbers properly.
-
-    Args:
-        items: List of strings to sort
-
-    Returns:
-        Naturally sorted list
-    """
-
-    def natural_key(text):
-        def atoi(text):
-            return int(text) if text.isdigit() else text
-
-        # Split on digits and filter out empty strings
-        parts = [atoi(c) for c in re.split(r"(\d+)", text) if c]
-
-        # Convert to tuple of (type_order, value) to ensure consistent comparison
-        # Integers get type_order 0, strings get type_order 1
-        typed_parts = []
-        for part in parts:
-            if isinstance(part, int):
-                typed_parts.append((0, part))
-            else:
-                typed_parts.append((1, part))
-
-        return typed_parts
-
-    return sorted(items, key=natural_key)
-
-
 def filter_loras_by_pattern(
     lora_files: List[str], include_pattern: str = "", exclude_pattern: str = ""
 ) -> List[str]:
-    """
-    Filter LoRA files by include/exclude patterns.
-
-    Args:
-        lora_files: List of LoRA filenames
-        include_pattern: Regex pattern to include (empty = include all)
-        exclude_pattern: Regex pattern to exclude (empty = exclude none)
-
-    Returns:
-        Filtered list of LoRA files
-    """
-    filtered = lora_files.copy()
-
-    # Apply include pattern
-    if include_pattern:
-        try:
-            include_re = re.compile(include_pattern)
-            filtered = [f for f in filtered if include_re.search(f)]
-        except re.error as e:
-            logger.error(f"Invalid include pattern: {e}")
-
-    # Apply exclude pattern
-    if exclude_pattern:
-        try:
-            exclude_re = re.compile(exclude_pattern)
-            filtered = [f for f in filtered if not exclude_re.search(f)]
-        except re.error as e:
-            logger.error(f"Invalid exclude pattern: {e}")
-
-    return filtered
+    """Filter LoRA names by include/exclude regex (empty pattern = no filter)."""
+    return filter_by_pattern(lora_files, include_pattern, exclude_pattern)
 
 
 def _parse_finite(token: str, what: str, original: str) -> float:
@@ -438,7 +328,7 @@ def validate_folder_path(folder_path: str) -> bool:
 
         return any(
             os.path.isdir(directory)
-            for directory, _ in _resolve_scan_targets(folder_path)
+            for directory, _ in resolve_scan_targets(folder_path, "loras")
         )
     except Exception:
         return False
diff --git a/tests/unit/base/__init__.py b/tests/unit/base/__init__.py
new file mode 100644
index 0000000..e69de29
diff --git a/tests/unit/base/test_model_folders.py b/tests/unit/base/test_model_folders.py
new file mode 100644
index 0000000..29512bc
--- /dev/null
+++ b/tests/unit/base/test_model_folders.py
@@ -0,0 +1,57 @@
+"""Tests for the shared model-folder scanner."""
+
+import os
+import sys
+from unittest.mock import MagicMock, patch
+
+from kikotools.base.model_folders import scan_model_entries, natural_sort
+
+
+def _touch(path):
+    os.makedirs(os.path.dirname(path), exist_ok=True)
+    with open(path, "w") as f:
+        f.write("x")
+
+
+def _fake_folder_paths(key, *roots):
+    fp = MagicMock()
+    fp.folder_names_and_paths = {key: [list(roots)]}
+    return patch.dict(sys.modules, {"folder_paths": fp})
+
+
+class TestScanModelEntries:
+    def test_scans_the_requested_folder_key(self, tmp_path):
+        ckpt = tmp_path / "checkpoints"
+        _touch(str(ckpt / "Illustrious" / "b_v2.safetensors"))
+        _touch(str(ckpt / "Illustrious" / "a_v10.safetensors"))
+        _touch(str(ckpt / "Illustrious" / "notes.md"))
+        with _fake_folder_paths("checkpoints", str(ckpt)):
+            entries = scan_model_entries("Illustrious", "checkpoints")
+        assert [name for name, _ in entries] == [
+            "Illustrious/a_v10.safetensors",
+            "Illustrious/b_v2.safetensors",
+        ]
+        assert entries[0][1] == str(ckpt / "Illustrious" / "a_v10.safetensors")
+
+    def test_relative_folder_escaping_the_root_is_ignored(self, tmp_path):
+        ckpt = tmp_path / "checkpoints"
+        _touch(str(tmp_path / "outside" / "x.safetensors"))
+        with _fake_folder_paths("checkpoints", str(ckpt)):
+            assert scan_model_entries("../outside", "checkpoints") == []
+
+    def test_unknown_key_returns_empty(self, tmp_path):
+        with _fake_folder_paths("loras", str(tmp_path)):
+            assert scan_model_entries(".", "checkpoints") == []
+
+
+def test_natural_sort_orders_numbers_numerically():
+    assert natural_sort(["v10", "v2", "v1"]) == ["v1", "v2", "v10"]
+
+
+def test_natural_sort_ignores_case():
+    assert natural_sort(["IllustrijGEN3", "aij_v10", "Illustrijv21", "animij_v6"]) == [
+        "aij_v10",
+        "animij_v6",
+        "IllustrijGEN3",
+        "Illustrijv21",
+    ]
diff --git a/tests/unit/tools/checkpoint_folder_iterator/__init__.py b/tests/unit/tools/checkpoint_folder_iterator/__init__.py
new file mode 100644
index 0000000..e69de29
diff --git a/tests/unit/tools/checkpoint_folder_iterator/test_logic.py b/tests/unit/tools/checkpoint_folder_iterator/test_logic.py
new file mode 100644
index 0000000..717f55d
--- /dev/null
+++ b/tests/unit/tools/checkpoint_folder_iterator/test_logic.py
@@ -0,0 +1,99 @@
+"""Tests for Checkpoint Folder Iterator logic."""
+
+import os
+import sys
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+from kikotools.tools.checkpoint_folder_iterator.logic import (
+    label_for,
+    list_checkpoint_entries,
+    list_checkpoints,
+    pick_checkpoint,
+)
+
+
+def _touch(path):
+    os.makedirs(os.path.dirname(path), exist_ok=True)
+    with open(path, "w") as f:
+        f.write("x")
+
+
+def _fake_checkpoints(root):
+    fp = MagicMock()
+    fp.folder_names_and_paths = {"checkpoints": [[str(root)]]}
+    return patch.dict(sys.modules, {"folder_paths": fp})
+
+
+class TestListCheckpoints:
+    def test_lists_safetensors_in_natural_order(self, tmp_path):
+        for name in ("illustrij_v20", "illustrij_v3", "ilustmix_v9"):
+            _touch(str(tmp_path / "Illustrious" / f"{name}.safetensors"))
+        _touch(str(tmp_path / "Illustrious" / "illustrij_v20.jpeg"))
+        with _fake_checkpoints(tmp_path):
+            names = list_checkpoints("Illustrious")
+        assert names == [
+            "Illustrious/illustrij_v3.safetensors",
+            "Illustrious/illustrij_v20.safetensors",
+            "Illustrious/ilustmix_v9.safetensors",
+        ]
+
+    def test_include_and_exclude_patterns(self, tmp_path):
+        for name in ("a_v1", "a_v2", "b_v1"):
+            _touch(str(tmp_path / "X" / f"{name}.safetensors"))
+        with _fake_checkpoints(tmp_path):
+            names = list_checkpoints("X", include_pattern="^X/a_", exclude_pattern="v2")
+        assert names == ["X/a_v1.safetensors"]
+
+
+class TestListCheckpointEntries:
+    def test_pairs_each_name_with_its_absolute_path(self, tmp_path):
+        _touch(str(tmp_path / "X" / "a_v1.safetensors"))
+        with _fake_checkpoints(tmp_path):
+            entries = list_checkpoint_entries("X")
+        assert entries == [
+            ("X/a_v1.safetensors", str(tmp_path / "X" / "a_v1.safetensors"))
+        ]
+
+    def test_patterns_apply_to_entries_too(self, tmp_path):
+        for name in ("a_v1", "a_v2", "b_v1"):
+            _touch(str(tmp_path / "X" / f"{name}.safetensors"))
+        with _fake_checkpoints(tmp_path):
+            entries = list_checkpoint_entries("X", "^X/a_", "v2")
+        assert [name for name, _ in entries] == ["X/a_v1.safetensors"]
+
+    def test_absolute_folder_outside_roots_keeps_real_paths(self, tmp_path):
+        root = tmp_path / "models" / "checkpoints"
+        elsewhere = tmp_path / "external_drive" / "ckpts"
+        _touch(str(elsewhere / "ext_v1.safetensors"))
+        with _fake_checkpoints(root):
+            entries = list_checkpoint_entries(str(elsewhere))
+        assert entries == [
+            ("ext_v1.safetensors", str(elsewhere / "ext_v1.safetensors"))
+        ]
+
+
+class TestPickCheckpoint:
+    def test_returns_the_indexed_item(self):
+        names = ["a", "b", "c"]
+        assert pick_checkpoint(names, 0) == "a"
+        assert pick_checkpoint(names, 2) == "c"
+
+    def test_index_past_the_end_raises_instead_of_wrapping(self):
+        with pytest.raises(ValueError, match="past the end.*3 checkpoints"):
+            pick_checkpoint(["a", "b", "c"], 3)
+
+    def test_negative_index_raises(self):
+        with pytest.raises(ValueError, match="past the end"):
+            pick_checkpoint(["a"], -1)
+
+    def test_empty_list_raises(self):
+        with pytest.raises(ValueError, match="No checkpoints"):
+            pick_checkpoint([], 0)
+
+
+class TestLabelFor:
+    def test_default_label_is_the_file_stem(self):
+        assert label_for("Illustrious/illustrij_v20.safetensors") == "illustrij_v20"
+        assert label_for("Illustrious/reijlita/x_v1.safetensors") == "x_v1"
diff --git a/tests/unit/tools/checkpoint_folder_iterator/test_node.py b/tests/unit/tools/checkpoint_folder_iterator/test_node.py
new file mode 100644
index 0000000..7d9ff4f
--- /dev/null
+++ b/tests/unit/tools/checkpoint_folder_iterator/test_node.py
@@ -0,0 +1,71 @@
+"""Tests for the Checkpoint Folder Iterator node."""
+
+import sys
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+from kikotools.tools.checkpoint_folder_iterator import CheckpointFolderIteratorNode
+
+NODE = "kikotools.tools.checkpoint_folder_iterator.node"
+ENTRIES = [
+    ("X/a_v1.safetensors", "/models/checkpoints/X/a_v1.safetensors"),
+    ("X/b_v2.safetensors", "/models/checkpoints/X/b_v2.safetensors"),
+]
+
+
+def _fake_comfy_modules():
+    fp = MagicMock()
+    fp.get_folder_paths = MagicMock(return_value=["/models/embeddings"])
+    comfy = MagicMock()
+    comfy.sd.load_checkpoint_guess_config = MagicMock(
+        return_value=("MODEL", "CLIP", "VAE", "extra")
+    )
+    return (
+        patch.dict(
+            sys.modules, {"folder_paths": fp, "comfy": comfy, "comfy.sd": comfy.sd}
+        ),
+        fp,
+        comfy,
+    )
+
+
+class TestCheckpointFolderIteratorNode:
+    def test_input_index_increments_after_generate(self):
+        index = CheckpointFolderIteratorNode.INPUT_TYPES()["required"]["index"]
+        assert index[0] == "INT"
+        assert index[1]["control_after_generate"] is True
+
+    def test_loads_the_indexed_checkpoint_from_its_scanned_path(self):
+        ctx, fp, comfy = _fake_comfy_modules()
+        with ctx, patch(f"{NODE}.list_checkpoint_entries", return_value=ENTRIES):
+            out = CheckpointFolderIteratorNode().load("X", 1, "", "")
+        comfy.sd.load_checkpoint_guess_config.assert_called_once()
+        assert comfy.sd.load_checkpoint_guess_config.call_args.args == (
+            "/models/checkpoints/X/b_v2.safetensors",
+        )
+        fp.get_full_path_or_raise.assert_not_called()
+        assert out == ("MODEL", "CLIP", "VAE", "X/b_v2.safetensors", "b_v2", 1, 2)
+
+    def test_absolute_folder_outside_models_dir_loads_by_real_path(self):
+        ctx, _, comfy = _fake_comfy_modules()
+        external = [("ext_v1.safetensors", "/mnt/drive/ckpts/ext_v1.safetensors")]
+        with ctx, patch(f"{NODE}.list_checkpoint_entries", return_value=external):
+            out = CheckpointFolderIteratorNode().load("/mnt/drive/ckpts", 0, "", "")
+        assert comfy.sd.load_checkpoint_guess_config.call_args.args == (
+            "/mnt/drive/ckpts/ext_v1.safetensors",
+        )
+        assert out[3:] == ("ext_v1.safetensors", "ext_v1", 0, 1)
+
+    def test_index_past_the_end_raises_instead_of_restarting(self):
+        ctx, _, comfy = _fake_comfy_modules()
+        with ctx, patch(f"{NODE}.list_checkpoint_entries", return_value=ENTRIES):
+            with pytest.raises(ValueError, match="past the end"):
+                CheckpointFolderIteratorNode().load("X", 2, "", "")
+        comfy.sd.load_checkpoint_guess_config.assert_not_called()
+
+    def test_empty_folder_raises_clear_error(self):
+        ctx, _, _ = _fake_comfy_modules()
+        with ctx, patch(f"{NODE}.list_checkpoint_entries", return_value=[]):
+            with pytest.raises(ValueError, match="No checkpoints"):
+                CheckpointFolderIteratorNode().load("Empty", 0, "", "")
diff --git a/tests/unit/tools/model_compare_sheet/__init__.py b/tests/unit/tools/model_compare_sheet/__init__.py
new file mode 100644
index 0000000..e69de29
diff --git a/tests/unit/tools/model_compare_sheet/test_logic.py b/tests/unit/tools/model_compare_sheet/test_logic.py
new file mode 100644
index 0000000..b96c6f3
--- /dev/null
+++ b/tests/unit/tools/model_compare_sheet/test_logic.py
@@ -0,0 +1,79 @@
+"""Tests for Model Compare Sheet logic."""
+
+import os
+
+import pytest
+from PIL import Image
+
+from kikotools.tools.model_compare_sheet.logic import (
+    build_contact_sheet,
+    label_from_filename,
+    list_tiles,
+    resolve_run_dir,
+    tile_filename,
+)
+
+
+class TestResolveRunDir:
+    def test_run_dir_lives_under_model_compare(self, tmp_path):
+        assert resolve_run_dir(str(tmp_path), "illustrious") == os.path.join(
+            str(tmp_path), "model_compare", "illustrious"
+        )
+
+    @pytest.mark.parametrize("bad", ["", "../escape", "/abs/path", "a/../../b"])
+    def test_rejects_names_that_leave_the_output_dir(self, tmp_path, bad):
+        with pytest.raises(ValueError, match="run_name"):
+            resolve_run_dir(str(tmp_path), bad)
+
+
+class TestTileFilename:
+    def test_single_image_run(self):
+        assert tile_filename(3, "illustrij_v20", 0, 1) == "03_illustrij_v20.png"
+
+    def test_batch_gets_a_suffix(self):
+        assert tile_filename(3, "illustrij_v20", 1, 2) == "03_illustrij_v20_2.png"
+
+    def test_label_characters_are_sanitized(self):
+        assert tile_filename(0, "a/b:c d", 0, 1) == "00_a_b_c_d.png"
+
+
+def test_label_from_filename_strips_index_and_extension():
+    assert label_from_filename("03_illustrij_v20.png") == "illustrij_v20"
+    assert label_from_filename("03_illustrij_v20_2.png") == "illustrij_v20_2"
+    assert label_from_filename("grid.png") == "grid"
+
+
+def test_list_tiles_skips_grid_and_sorts_naturally(tmp_path):
+    for name in ("10_b.png", "2_a.png", "grid.png", "grid_preview.png", "notes.txt"):
+        (tmp_path / name).write_bytes(b"")
+    assert list_tiles(str(tmp_path)) == [
+        str(tmp_path / "2_a.png"),
+        str(tmp_path / "10_b.png"),
+    ]
+
+
+class TestBuildContactSheet:
+    def _tiles(self, tmp_path, n, size=(100, 200)):
+        paths = []
+        for i in range(n):
+            p = tmp_path / f"{i:02d}_m{i}.png"
+            Image.new("RGB", size, (i * 40, 0, 0)).save(p)
+            paths.append(str(p))
+        return paths
+
+    def test_grid_dimensions_follow_columns_and_tile_width(self, tmp_path):
+        paths = self._tiles(tmp_path, 3)
+        sheet = build_contact_sheet(paths, columns=2, tile_width=50, font_size=10)
+        # 3 tiles in 2 columns = 2 rows; tiles scale to 50x100; label band 2*font
+        assert sheet.size == (100, 2 * (100 + 20))
+
+    def test_fewer_tiles_than_columns_shrinks_width(self, tmp_path):
+        paths = self._tiles(tmp_path, 1)
+        sheet = build_contact_sheet(paths, columns=5, tile_width=50, font_size=10)
+        assert sheet.size == (50, 100 + 20)
+
+    def test_label_band_is_drawn(self, tmp_path):
+        paths = self._tiles(tmp_path, 1)
+        sheet = build_contact_sheet(paths, columns=1, tile_width=50, font_size=10)
+        band = sheet.crop((0, 100, 50, 120))
+        assert len(band.getcolors(maxcolors=4096) or []) > 1
diff --git a/tests/unit/tools/model_compare_sheet/test_node.py b/tests/unit/tools/model_compare_sheet/test_node.py
new file mode 100644
index 0000000..89c4833
--- /dev/null
+++ b/tests/unit/tools/model_compare_sheet/test_node.py
@@ -0,0 +1,125 @@
+"""Tests for the Model Compare Sheet node."""
+
+import os
+import sys
+from unittest.mock import MagicMock, patch
+
+import torch
+from PIL import Image
+
+from kikotools.tools.model_compare_sheet import ModelCompareSheetNode
+
+
+def _fake_output_dir(path):
+    fp = MagicMock()
+    fp.get_output_directory = MagicMock(return_value=str(path))
+    return patch.dict(sys.modules, {"folder_paths": fp})
+
+
+def _image(batch=1, h=64, w=32):
+    return torch.rand(batch, h, w, 3)
+
+
+class TestModelCompareSheetNode:
+    def test_is_an_output_node(self):
+        assert ModelCompareSheetNode.OUTPUT_NODE is True
+
+    def test_saves_tile_and_grid_and_returns_grid(self, tmp_path):
+        with _fake_output_dir(tmp_path):
+            out = ModelCompareSheetNode().collect(
+                _image(), "illustrij_v20", 3, "run1", 4, 32, 8
+            )
+        run_dir = tmp_path / "model_compare" / "run1"
+        assert (run_dir / "03_illustrij_v20.png").exists()
+        assert (run_dir / "grid.png").exists()
+        grid = out["result"][0]
+        assert grid.shape == (1, 64 + 16, 32, 3)
+        assert out["ui"]["images"][0]["filename"] == "grid_preview.png"
+        assert out["ui"]["images"][0]["subfolder"] == os.path.join(
+            "model_compare", "run1"
+        )
+
+    def test_grid_grows_across_runs(self, tmp_path):
+        with _fake_output_dir(tmp_path):
+            node = ModelCompareSheetNode()
+            node.collect(_image(), "a", 0, "run1", 4, 32, 8)
+            out = node.collect(_image(), "b", 1, "run1", 4, 32, 8)
+        assert out["result"][0].shape == (1, 64 + 16, 64, 3)
+
+    def test_batch_saves_every_image(self, tmp_path):
+        with _fake_output_dir(tmp_path):
+            ModelCompareSheetNode().collect(_image(batch=2), "a", 0, "run1", 4, 32, 8)
+        run_dir = tmp_path / "model_compare" / "run1"
+        assert (run_dir / "00_a_1.png").exists()
+        assert (run_dir / "00_a_2.png").exists()
+        assert Image.open(run_dir / "grid.png").size == (64, 64 + 16)
+
+    def test_rerun_of_same_index_overwrites_instead_of_duplicating(self, tmp_path):
+        with _fake_output_dir(tmp_path):
+            node = ModelCompareSheetNode()
+            node.collect(_image(), "a", 0, "run1", 4, 32, 8)
+            out = node.collect(_image(), "a", 0, "run1", 4, 32, 8)
+        assert out["result"][0].shape[2] == 32
+
+
+class TestArchiveOnNewSweep:
+    def test_index_zero_archives_the_previous_sweep(self, tmp_path):
+        with _fake_output_dir(tmp_path):
+            node = ModelCompareSheetNode()
+            node.collect(_image(), "a", 0, "run1", 4, 32, 8)
+            node.collect(_image(), "b", 1, "run1", 4, 32, 8)
+            out = node.collect(_image(), "c", 0, "run1", 4, 32, 8)
+        run_dir = tmp_path / "model_compare" / "run1"
+        assert sorted(p.name for p in run_dir.iterdir()) == [
+            "00_c.png",
+            "grid.png",
+            "grid_preview.png",
+        ]
+        assert out["result"][0].shape[2] == 32
+        archived = [p for p in run_dir.parent.iterdir() if p.name.startswith("run1_")]
+        assert len(archived) == 1
+        assert sorted(p.name for p in archived[0].iterdir()) == [
+            "00_a.png",
+            "01_b.png",
+            "grid.png",
+            "grid_preview.png",
+        ]
+
+    def test_nonzero_index_keeps_existing_tiles(self, tmp_path):
+        with _fake_output_dir(tmp_path):
+            node = ModelCompareSheetNode()
+            node.collect(_image(), "a", 0, "run1", 4, 32, 8)
+            node.collect(_image(), "b", 3, "run1", 4, 32, 8)
+        run_dir = tmp_path / "model_compare" / "run1"
+        assert sorted(p.name for p in run_dir.iterdir()) == [
+            "00_a.png",
+            "03_b.png",
+            "grid.png",
+            "grid_preview.png",
+        ]
+
+    def test_index_zero_on_empty_folder_archives_nothing(self, tmp_path):
+        with _fake_output_dir(tmp_path):
+            ModelCompareSheetNode().collect(_image(), "a", 0, "run1", 4, 32, 8)
+        assert [p.name for p in (tmp_path / "model_compare").iterdir()] == ["run1"]
+
+
+class TestPreview:
+    def test_ui_preview_is_downscaled_but_grid_and_output_stay_full_size(
+        self, tmp_path
+    ):
+        with _fake_output_dir(tmp_path):
+            out = ModelCompareSheetNode().collect(
+                _image(h=64, w=32), "a", 0, "run1", 1, 1200, 8
+            )
+        run_dir = tmp_path / "model_compare" / "run1"
+        assert Image.open(run_dir / "grid.png").size[0] == 1200
+        assert Image.open(run_dir / "grid_preview.png").size[0] == 1024
+        assert out["result"][0].shape[2] == 1200
+        assert out["ui"]["images"][0]["filename"] == "grid_preview.png"
+
+    def test_small_grid_preview_is_not_upscaled(self, tmp_path):
+        with _fake_output_dir(tmp_path):
+            ModelCompareSheetNode().collect(_image(), "a", 0, "run1", 1, 32, 8)
+        run_dir = tmp_path / "model_compare" / "run1"
+        assert Image.open(run_dir / "grid_preview.png").size[0] == 32

From 335cc5396159ad3b276889f9d6b49cc0bd774ebb Mon Sep 17 00:00:00 2001
From: Vito Sansevero <vito.sansevero@gmail.com>
Date: Fri, 16 Oct 2026 08:11:17 -0700
Subject: [PATCH 2/5] fix(model_compare_sheet): reject run_name segments on
 both separators

- Split run_name on "/" and "\" and reject empty, "." and ".." parts, so
  a Windows-style "..\foo" can no longer resolve outside model_compare
  and let the index-0 archive step rename an unrelated output folder
- Reject drive-letter names and require the resolved directory to sit
  strictly below output/model_compare after symlinks are followed
- Nested run names such as project/date/sweep still work
---
 kikotools/tools/model_compare_sheet/logic.py  | 19 +++++++++++---
 .../tools/model_compare_sheet/test_logic.py   | 25 +++++++++++++++++--
 2 files changed, 38 insertions(+), 6 deletions(-)

diff --git a/kikotools/tools/model_compare_sheet/logic.py b/kikotools/tools/model_compare_sheet/logic.py
index 8bbd570..cad81b1 100644
--- a/kikotools/tools/model_compare_sheet/logic.py
+++ b/kikotools/tools/model_compare_sheet/logic.py
@@ -18,11 +18,22 @@ LABEL_COLOR = (235, 235, 235)
 
 
 def resolve_run_dir(output_dir: str, run_name: str) -> str:
-    """Directory for one compare run, always inside output/model_compare."""
-    if not run_name or os.path.isabs(run_name) or ".." in run_name.split("/"):
+    """Directory for one compare run, always strictly inside output/model_compare.
+
+    run_name may be nested ("project/date/sweep"). Every segment must be a plain
+    name: no empty, "." or ".." parts, on either separator, and the resolved
+    path must stay below model_compare even after symlinks are followed.
+    """
+    parts = re.split(r"[\\/]", run_name)
+    if not run_name or os.path.isabs(run_name) or ":" in run_name:
         raise ValueError(f"Invalid run_name: {run_name!r}")
-    run_dir = os.path.join(output_dir, "model_compare", run_name)
-    if not is_within(run_dir, output_dir):
+    if any(part in ("", ".", "..") for part in parts):
+        raise ValueError(f"Invalid run_name: {run_name!r}")
+    base = os.path.join(output_dir, "model_compare")
+    run_dir = os.path.join(base, *parts)
+    if not is_within(run_dir, base) or os.path.realpath(run_dir) == os.path.realpath(
+        base
+    ):
         raise ValueError(f"Invalid run_name: {run_name!r}")
     return run_dir
 
diff --git a/tests/unit/tools/model_compare_sheet/test_logic.py b/tests/unit/tools/model_compare_sheet/test_logic.py
index b96c6f3..c0dfef0 100644
--- a/tests/unit/tools/model_compare_sheet/test_logic.py
+++ b/tests/unit/tools/model_compare_sheet/test_logic.py
@@ -20,8 +20,29 @@ class TestResolveRunDir:
             str(tmp_path), "model_compare", "illustrious"
         )
 
-    @pytest.mark.parametrize("bad", ["", "../escape", "/abs/path", "a/../../b"])
-    def test_rejects_names_that_leave_the_output_dir(self, tmp_path, bad):
+    def test_nested_run_names_are_allowed(self, tmp_path):
+        assert resolve_run_dir(str(tmp_path), "proj/2026-10-15/sweep") == os.path.join(
+            str(tmp_path), "model_compare", "proj", "2026-10-15", "sweep"
+        )
+
+    @pytest.mark.parametrize(
+        "bad",
+        [
+            "",
+            "../escape",
+            "/abs/path",
+            "a/../../b",
+            "..\\escape",
+            "a\\..\\..\\b",
+            "C:\\abs",
+            ".",
+            "./x",
+            "a/./b",
+            "a//b",
+            "x/..",
+        ],
+    )
+    def test_rejects_names_that_leave_model_compare(self, tmp_path, bad):
         with pytest.raises(ValueError, match="run_name"):
             resolve_run_dir(str(tmp_path), bad)
 

From 852864a270fdd6c6712845eba6091df008e7d1fe Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Fri, 16 Oct 2026 15:47:47 +0000
Subject: [PATCH 3/5] build(deps): bump actions/setup-python from 6 to 7

Bumps [actions/setup-python](https://github.com/actions/setup-python) from 6 to 7.
- [Release notes](https://github.com/actions/setup-python/releases)
- [Commits](https://github.com/actions/setup-python/compare/v6...v7)

---
updated-dependencies:
- dependency-name: actions/setup-python
  dependency-version: '7'
  dependency-type: direct:production
  update-type: version-update:semver-major
...

Signed-off-by: dependabot[bot] <support@github.com>
---
 .github/workflows/code-quality.yml | 6 +++---
 .github/workflows/release.yml      | 2 +-
 .github/workflows/tests.yml        | 6 +++---
 3 files changed, 7 insertions(+), 7 deletions(-)

diff --git a/.github/workflows/code-quality.yml b/.github/workflows/code-quality.yml
index 69168a1..7c78bcc 100644
--- a/.github/workflows/code-quality.yml
+++ b/.github/workflows/code-quality.yml
@@ -16,7 +16,7 @@ jobs:
     - uses: actions/checkout@v7
 
     - name: Set up Python 3.10
-      uses: actions/setup-python@v6
+      uses: actions/setup-python@v7
       with:
         python-version: '3.10'
 
@@ -145,7 +145,7 @@ jobs:
     - uses: actions/checkout@v7
 
     - name: Set up Python 3.10
-      uses: actions/setup-python@v6
+      uses: actions/setup-python@v7
       with:
         python-version: '3.10'
 
@@ -176,7 +176,7 @@ jobs:
     - uses: actions/checkout@v7
 
     - name: Set up Python 3.10
-      uses: actions/setup-python@v6
+      uses: actions/setup-python@v7
       with:
         python-version: '3.10'
 
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index fd01af8..0e69f68 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -20,7 +20,7 @@ jobs:
     - uses: actions/checkout@v7
 
     - name: Set up Python 3.10
-      uses: actions/setup-python@v6
+      uses: actions/setup-python@v7
       with:
         python-version: '3.10'
 
diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml
index d99ddcc..866fbcd 100644
--- a/.github/workflows/tests.yml
+++ b/.github/workflows/tests.yml
@@ -23,7 +23,7 @@ jobs:
       - uses: actions/checkout@v7
 
       - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v6
+        uses: actions/setup-python@v7
         with:
           python-version: ${{ matrix.python-version }}
           cache: pip
@@ -60,7 +60,7 @@ jobs:
     steps:
       - uses: actions/checkout@v7
 
-      - uses: actions/setup-python@v6
+      - uses: actions/setup-python@v7
         with:
           python-version: "3.12"
           cache: pip
@@ -110,7 +110,7 @@ jobs:
     timeout-minutes: 15
     steps:
       - uses: actions/checkout@v7
-      - uses: actions/setup-python@v6
+      - uses: actions/setup-python@v7
         with:
           python-version: "3.12"
           cache: pip

From ae0fb7f22910a44af4a6f7f67e7ad41a5ce93eb9 Mon Sep 17 00:00:00 2001
From: Vito Sansevero <vito.sansevero@gmail.com>
Date: Fri, 16 Oct 2026 08:58:21 -0700
Subject: [PATCH 4/5] fix(model_compare_sheet): replace rerun tiles without
 retaining stale batches

---
 README.md                                     |   2 +
 kikotools/tools/model_compare_sheet/logic.py  |  37 +++-
 kikotools/tools/model_compare_sheet/node.py   |  35 ++--
 .../tools/model_compare_sheet/test_logic.py   |  12 ++
 .../tools/model_compare_sheet/test_node.py    | 172 ++++++++++++++++++
 5 files changed, 244 insertions(+), 14 deletions(-)

diff --git a/README.md b/README.md
index 78e25e1..8bd9482 100644
--- a/README.md
+++ b/README.md
@@ -322,6 +322,8 @@ Output node that pairs with Checkpoint Folder Iterator.
 - After the last queued run the preview shows the complete sheet
 - Wire Project File Path into `run_name` for `project/date/sweep` folders
 - A run at index 0 moves tiles already in the folder to `<run_name>_<timestamp>`, so an interrupted sweep never leaks into the new grid
+- Rerunning a nonzero index replaces its complete batch, even when the label or batch size changes; other indexes are preserved
+- Replacement PNGs are fully written before existing tiles are changed; a failed tile write preserves the prior tiles and grid
 
 #### 📊 Plot Parameters
 Visual analysis tool for understanding parameter relationships and effects.
diff --git a/kikotools/tools/model_compare_sheet/logic.py b/kikotools/tools/model_compare_sheet/logic.py
index cad81b1..c66ae19 100644
--- a/kikotools/tools/model_compare_sheet/logic.py
+++ b/kikotools/tools/model_compare_sheet/logic.py
@@ -4,7 +4,7 @@ import math
 import os
 import re
 from datetime import datetime
-from typing import List, Optional
+from typing import List, Optional, Tuple
 
 from PIL import Image, ImageDraw, ImageFont
 
@@ -55,11 +55,44 @@ def list_tiles(run_dir: str) -> List[str]:
     names = [
         f
         for f in os.listdir(run_dir)
-        if f.lower().endswith(".png") and f not in (GRID_FILENAME, PREVIEW_FILENAME)
+        if f.lower().endswith(".png")
+        and f not in (GRID_FILENAME, PREVIEW_FILENAME)
+        and os.path.isfile(os.path.join(run_dir, f))
     ]
     return [os.path.join(run_dir, f) for f in natural_sort(names)]
 
 
+def replace_index_tiles(
+    run_dir: str, index: int, staged_dir: str, names: List[str]
+) -> None:
+    """Publish one index's staged tiles, restoring old files on a rename failure."""
+    previous_dir = os.path.join(staged_dir, "previous")
+    os.mkdir(previous_dir)
+    prefix = f"{index:02d}_"
+    old_tiles = [
+        path
+        for path in list_tiles(run_dir)
+        if os.path.basename(path).startswith(prefix)
+    ]
+    moved: List[Tuple[str, str]] = []
+    published: List[str] = []
+    try:
+        for path in old_tiles:
+            backup = os.path.join(previous_dir, os.path.basename(path))
+            os.replace(path, backup)
+            moved.append((path, backup))
+        for name in names:
+            destination = os.path.join(run_dir, name)
+            os.replace(os.path.join(staged_dir, name), destination)
+            published.append(destination)
+    except OSError:
+        for path in published:
+            os.remove(path)
+        for original, backup in reversed(moved):
+            os.replace(backup, original)
+        raise
+
+
 def archive_previous_sweep(run_dir: str) -> Optional[str]:
     """Rename a run folder that already holds tiles to '<run_dir>_<timestamp>'.
 
diff --git a/kikotools/tools/model_compare_sheet/node.py b/kikotools/tools/model_compare_sheet/node.py
index 8bfa1e8..b75b82a 100644
--- a/kikotools/tools/model_compare_sheet/node.py
+++ b/kikotools/tools/model_compare_sheet/node.py
@@ -2,7 +2,8 @@
 
 import json
 import os
-from typing import Dict, Optional
+from tempfile import TemporaryDirectory
+from typing import Any, Dict, Optional
 
 import numpy as np
 import torch
@@ -17,6 +18,7 @@ from .logic import (
     build_contact_sheet,
     list_tiles,
     preview_of,
+    replace_index_tiles,
     resolve_run_dir,
     tile_filename,
 )
@@ -67,27 +69,36 @@ class ModelCompareSheetNode(ComfyAssetsBaseNode):
         font_size: int,
         prompt: Optional[Dict] = None,
         extra_pnginfo: Optional[Dict] = None,
-    ):
+    ) -> Dict[str, Any]:
         import folder_paths
 
+        if images.shape[0] == 0:
+            raise ValueError("images must contain at least one image")
+
         output_dir = folder_paths.get_output_directory()
         run_dir = resolve_run_dir(output_dir, run_name)
-        if index == 0:
-            archived = archive_previous_sweep(run_dir)
-            if archived:
-                self.log_info(f"New sweep: previous tiles moved to {archived}")
-        os.makedirs(run_dir, exist_ok=True)
-
         metadata = PngInfo()
         if prompt is not None:
             metadata.add_text("prompt", json.dumps(prompt))
         for key, value in (extra_pnginfo or {}).items():
             metadata.add_text(key, json.dumps(value))
 
-        for i, image in enumerate(images):
-            array = (image.cpu().numpy().clip(0, 1) * 255).round().astype(np.uint8)
-            name = tile_filename(index, label, i, images.shape[0])
-            Image.fromarray(array).save(os.path.join(run_dir, name), pnginfo=metadata)
+        parent = os.path.dirname(run_dir)
+        os.makedirs(parent, exist_ok=True)
+        with TemporaryDirectory(prefix=".model-compare-", dir=parent) as staging:
+            names = []
+            for i, image in enumerate(images):
+                array = (image.cpu().numpy().clip(0, 1) * 255).round().astype(np.uint8)
+                name = tile_filename(index, label, i, images.shape[0])
+                with Image.fromarray(array) as tile:
+                    tile.save(os.path.join(staging, name), pnginfo=metadata)
+                names.append(name)
+            if index == 0:
+                archived = archive_previous_sweep(run_dir)
+                if archived:
+                    self.log_info(f"New sweep: previous tiles moved to {archived}")
+            os.makedirs(run_dir, exist_ok=True)
+            replace_index_tiles(run_dir, index, staging, names)
 
         sheet = build_contact_sheet(list_tiles(run_dir), columns, tile_width, font_size)
         sheet.save(os.path.join(run_dir, GRID_FILENAME))
diff --git a/tests/unit/tools/model_compare_sheet/test_logic.py b/tests/unit/tools/model_compare_sheet/test_logic.py
index c0dfef0..d46d20a 100644
--- a/tests/unit/tools/model_compare_sheet/test_logic.py
+++ b/tests/unit/tools/model_compare_sheet/test_logic.py
@@ -46,6 +46,18 @@ class TestResolveRunDir:
         with pytest.raises(ValueError, match="run_name"):
             resolve_run_dir(str(tmp_path), bad)
 
+    def test_rejects_symlink_escape_into_another_output_folder(self, tmp_path):
+        base = tmp_path / "model_compare"
+        base.mkdir()
+        outside = tmp_path / "unrelated"
+        outside.mkdir()
+        try:
+            (base / "link").symlink_to(outside, target_is_directory=True)
+        except OSError as exc:
+            pytest.skip(f"Directory symlinks unavailable: {exc}")
+        with pytest.raises(ValueError, match="run_name"):
+            resolve_run_dir(str(tmp_path), "link/run")
+
 
 class TestTileFilename:
     def test_single_image_run(self):
diff --git a/tests/unit/tools/model_compare_sheet/test_node.py b/tests/unit/tools/model_compare_sheet/test_node.py
index 89c4833..a9b5830 100644
--- a/tests/unit/tools/model_compare_sheet/test_node.py
+++ b/tests/unit/tools/model_compare_sheet/test_node.py
@@ -1,9 +1,12 @@
 """Tests for the Model Compare Sheet node."""
 
+import json
 import os
+from pathlib import Path
 import sys
 from unittest.mock import MagicMock, patch
 
+import pytest
 import torch
 from PIL import Image
 
@@ -123,3 +126,172 @@ class TestPreview:
             ModelCompareSheetNode().collect(_image(), "a", 0, "run1", 1, 32, 8)
         run_dir = tmp_path / "model_compare" / "run1"
         assert Image.open(run_dir / "grid_preview.png").size[0] == 32
+
+
+class TestReplaceIndex:
+    @pytest.mark.parametrize(
+        "old_batch, old_label, new_batch, new_label, expected",
+        [
+            (2, "a", 1, "a", ["01_a.png"]),
+            (1, "a", 1, "b", ["01_b.png"]),
+            (1, "a", 1, "A", ["01_A.png"]),
+            (2, "a", 3, "b", ["01_b_1.png", "01_b_2.png", "01_b_3.png"]),
+            (1, "a", 2, "a", ["01_a_1.png", "01_a_2.png"]),
+            (3, "a", 2, "a", ["01_a_1.png", "01_a_2.png"]),
+        ],
+    )
+    def test_rerun_replaces_only_its_index(
+        self,
+        tmp_path: Path,
+        old_batch: int,
+        old_label: str,
+        new_batch: int,
+        new_label: str,
+        expected: list[str],
+    ) -> None:
+        with _fake_output_dir(tmp_path):
+            node = ModelCompareSheetNode()
+            node.collect(_image(), "first", 0, "run1", 8, 32, 8)
+            node.collect(_image(batch=old_batch), old_label, 1, "run1", 8, 32, 8)
+            node.collect(_image(), "neighbor", 10, "run1", 8, 32, 8)
+            run_dir = tmp_path / "model_compare" / "run1"
+            untouched = {
+                name: (run_dir / name).read_bytes()
+                for name in ("00_first.png", "10_neighbor.png")
+            }
+            (run_dir / "notes.txt").write_text("keep this note")
+            archived = run_dir.parent / "run1_archived"
+            archived.mkdir()
+            (archived / "01_a.png").write_bytes(b"archived tile")
+            result = node.collect(
+                torch.ones(new_batch, 64, 32, 3),
+                new_label,
+                1,
+                "run1",
+                8,
+                32,
+                8,
+                prompt={"model": "replacement"},
+                extra_pnginfo={"workflow": {"id": "retry"}},
+            )
+        assert sorted(path.name for path in run_dir.glob("01_*.png")) == expected
+        assert result["result"][0].shape == (1, 80, (new_batch + 2) * 32, 3)
+        assert sorted(path.name for path in run_dir.iterdir()) == sorted(
+            [
+                "00_first.png",
+                "10_neighbor.png",
+                "grid.png",
+                "grid_preview.png",
+                "notes.txt",
+                *expected,
+            ]
+        )
+        for name, data in untouched.items():
+            assert (run_dir / name).read_bytes() == data
+        assert (run_dir / "notes.txt").read_text() == "keep this note"
+        assert (archived / "01_a.png").read_bytes() == b"archived tile"
+        for name in expected:
+            with Image.open(run_dir / name) as image:
+                assert image.getpixel((0, 0)) == (255, 255, 255)
+                assert json.loads(image.info["prompt"]) == {"model": "replacement"}
+                assert json.loads(image.info["workflow"]) == {"id": "retry"}
+
+    @pytest.mark.parametrize("index", [0, 1])
+    @pytest.mark.parametrize("failed_image", [1, 2])
+    def test_failed_tile_write_preserves_the_existing_batch_and_grid(
+        self, tmp_path: Path, index: int, failed_image: int
+    ) -> None:
+        with _fake_output_dir(tmp_path):
+            node = ModelCompareSheetNode()
+            node.collect(torch.zeros(2, 64, 32, 3), "same", index, "run1", 8, 32, 8)
+            base = tmp_path / "model_compare"
+            before = {
+                str(path.relative_to(base)): path.read_bytes()
+                for path in base.rglob("*")
+                if path.is_file()
+            }
+            original_save = Image.Image.save
+            tile_writes = 0
+
+            def fail_tile_write(image, path, *args, **kwargs):
+                nonlocal tile_writes
+                if Path(path).name.startswith(f"{index:02d}_"):
+                    tile_writes += 1
+                    if tile_writes == failed_image:
+                        raise OSError("disk full")
+                return original_save(image, path, *args, **kwargs)
+
+            with patch.object(Image.Image, "save", new=fail_tile_write):
+                with pytest.raises(OSError, match="disk full"):
+                    node.collect(
+                        torch.ones(2, 64, 32, 3), "same", index, "run1", 8, 32, 8
+                    )
+        assert {
+            str(path.relative_to(base)): path.read_bytes()
+            for path in base.rglob("*")
+            if path.is_file()
+        } == before
+        assert list(base.iterdir()) == [base / "run1"]
+
+    def test_empty_batch_does_not_remove_existing_tiles(self, tmp_path: Path) -> None:
+        with _fake_output_dir(tmp_path):
+            node = ModelCompareSheetNode()
+            node.collect(_image(), "a", 1, "run1", 8, 32, 8)
+            run_dir = tmp_path / "model_compare" / "run1"
+            before = {path.name: path.read_bytes() for path in run_dir.iterdir()}
+            with pytest.raises(ValueError, match="at least one image"):
+                node.collect(torch.empty(0, 64, 32, 3), "b", 1, "run1", 8, 32, 8)
+        assert {path.name: path.read_bytes() for path in run_dir.iterdir()} == before
+
+    @pytest.mark.parametrize("failed_image", [1, 2])
+    def test_failed_publication_restores_the_previous_batch(
+        self, tmp_path: Path, failed_image: int
+    ) -> None:
+        with _fake_output_dir(tmp_path):
+            node = ModelCompareSheetNode()
+            node.collect(torch.zeros(2, 64, 32, 3), "same", 1, "run1", 8, 32, 8)
+            base = tmp_path / "model_compare"
+            run_dir = base / "run1"
+            before = {
+                str(path.relative_to(base)): path.read_bytes()
+                for path in base.rglob("*")
+                if path.is_file()
+            }
+            original_replace = os.replace
+            published = 0
+
+            def fail_publication(source, destination):
+                nonlocal published
+                if (
+                    Path(destination).parent == run_dir
+                    and Path(source).parent.name != "previous"
+                ):
+                    published += 1
+                    if published == failed_image:
+                        raise OSError("publication failed")
+                return original_replace(source, destination)
+
+            with patch("os.replace", side_effect=fail_publication):
+                with pytest.raises(OSError, match="publication failed"):
+                    node.collect(torch.ones(2, 64, 32, 3), "same", 1, "run1", 8, 32, 8)
+        assert {
+            str(path.relative_to(base)): path.read_bytes()
+            for path in base.rglob("*")
+            if path.is_file()
+        } == before
+        assert list(base.iterdir()) == [run_dir]
+
+    def test_rerun_preserves_directories_with_tile_like_names(
+        self, tmp_path: Path
+    ) -> None:
+        with _fake_output_dir(tmp_path):
+            node = ModelCompareSheetNode()
+            node.collect(_image(), "a", 1, "run1", 8, 32, 8)
+            run_dir = tmp_path / "model_compare" / "run1"
+            notes = run_dir / "01_notes.png"
+            notes.mkdir()
+            (notes / "notes.txt").write_text("keep this folder")
+            node.collect(_image(), "b", 1, "run1", 8, 32, 8)
+        assert (notes / "notes.txt").read_text() == "keep this folder"
+        assert (run_dir / "01_b.png").is_file()
+        assert not (run_dir / "01_a.png").exists()

From 64f70b6970e5b6d676850bd32ae9f2fcf09c3fda Mon Sep 17 00:00:00 2001
From: Vito Sansevero <vito.sansevero@gmail.com>
Date: Fri, 16 Oct 2026 09:03:56 -0700
Subject: [PATCH 5/5] fix(model_compare_sheet): hide staging files from output
 image discovery

---
 kikotools/tools/model_compare_sheet/logic.py  |  4 +--
 kikotools/tools/model_compare_sheet/node.py   |  6 +++-
 .../tools/model_compare_sheet/test_node.py    | 32 +++++++++++++++++++
 3 files changed, 39 insertions(+), 3 deletions(-)

diff --git a/kikotools/tools/model_compare_sheet/logic.py b/kikotools/tools/model_compare_sheet/logic.py
index c66ae19..a469417 100644
--- a/kikotools/tools/model_compare_sheet/logic.py
+++ b/kikotools/tools/model_compare_sheet/logic.py
@@ -78,12 +78,12 @@ def replace_index_tiles(
     published: List[str] = []
     try:
         for path in old_tiles:
-            backup = os.path.join(previous_dir, os.path.basename(path))
+            backup = os.path.join(previous_dir, os.path.basename(path) + ".previous")
             os.replace(path, backup)
             moved.append((path, backup))
         for name in names:
             destination = os.path.join(run_dir, name)
-            os.replace(os.path.join(staged_dir, name), destination)
+            os.replace(os.path.join(staged_dir, name + ".tmp"), destination)
             published.append(destination)
     except OSError:
         for path in published:
diff --git a/kikotools/tools/model_compare_sheet/node.py b/kikotools/tools/model_compare_sheet/node.py
index b75b82a..d9f3902 100644
--- a/kikotools/tools/model_compare_sheet/node.py
+++ b/kikotools/tools/model_compare_sheet/node.py
@@ -91,7 +91,11 @@ class ModelCompareSheetNode(ComfyAssetsBaseNode):
                 array = (image.cpu().numpy().clip(0, 1) * 255).round().astype(np.uint8)
                 name = tile_filename(index, label, i, images.shape[0])
                 with Image.fromarray(array) as tile:
-                    tile.save(os.path.join(staging, name), pnginfo=metadata)
+                    tile.save(
+                        os.path.join(staging, name + ".tmp"),
+                        format="PNG",
+                        pnginfo=metadata,
+                    )
                 names.append(name)
             if index == 0:
                 archived = archive_previous_sweep(run_dir)
diff --git a/tests/unit/tools/model_compare_sheet/test_node.py b/tests/unit/tools/model_compare_sheet/test_node.py
index a9b5830..6948260 100644
--- a/tests/unit/tools/model_compare_sheet/test_node.py
+++ b/tests/unit/tools/model_compare_sheet/test_node.py
@@ -295,3 +295,35 @@ class TestReplaceIndex:
         assert (notes / "notes.txt").read_text() == "keep this folder"
         assert (run_dir / "01_b.png").is_file()
         assert not (run_dir / "01_a.png").exists()
+
+    def test_staging_does_not_expose_temporary_images_to_output_galleries(
+        self, tmp_path: Path
+    ) -> None:
+        with _fake_output_dir(tmp_path):
+            node = ModelCompareSheetNode()
+            node.collect(_image(), "a", 1, "run1", 8, 32, 8)
+            base = tmp_path / "model_compare"
+            run_dir = base / "run1"
+            temporary_images = []
+            original_save = Image.Image.save
+            original_replace = os.replace
+
+            def observe_images() -> None:
+                temporary_images.extend(
+                    path for path in base.rglob("*.png") if path.parent != run_dir
+                )
+
+            def save_and_observe(image, path, *args, **kwargs):
+                result = original_save(image, path, *args, **kwargs)
+                observe_images()
+                return result
+
+            def replace_and_observe(source, destination):
+                result = original_replace(source, destination)
+                observe_images()
+                return result
+
+            with patch.object(Image.Image, "save", new=save_and_observe):
+                with patch("os.replace", side_effect=replace_and_observe):
+                    node.collect(_image(batch=2), "b", 1, "run1", 8, 32, 8)
+        assert temporary_images == []