Fix incomplete GGUF downloads, group sharded models, surface download errors

Three related bugs in the llama.cpp/GGUF local model flow:

- Incomplete downloads: downloadGgufFile() wrote straight to the final
  .gguf name, so a network drop, crash, or force-quit mid-download left a
  truncated file indistinguishable from a real model — listModels() would
  offer it, and loading it failed with a confusing 'corrupt GGUF' error
  instead of the app just knowing it never finished. Now downloads go to a
  .gguf.part file and only get renamed to the final name after every byte
  is confirmed received; any leftover .part files from a session that never
  got to clean up after itself (crash/force-quit) are swept on next launch.

- Sharded models (e.g. *-00001-of-00002.gguf) listed as two separate,
  confusing, and partially-broken entries — selecting the second shard on
  its own doesn't load. groupShardedModels() merges same-model shards into
  one entry keyed off the lowest part present, with a synthetic "(N parts)"
  label, and deleteModel() now removes every sibling shard instead of
  orphaning the rest.

- A failed Hugging Face download was silently swallowed in the Settings UI
  — the progress bar just vanished with no toast, no error, nothing.

Also fixes the Settings label bug from the previous commit's follow-up:
LocalGgufModel now carries both name (real filename, used for
load/delete) and label (display-only) so the grouped "(N parts)" text
never gets sent back as if it were a real file name.

Author: voidstackloop

app/src/huggingface.ts

@@ -47,6 +47,14 @@ export interface DownloadProgress {
     totalBytes: number | null;
 }
 
+// Suffix for in-progress downloads. Writing directly to the final .gguf name
+// would let a truncated file — from a network drop, a crash, or the app
+// being force-quit mid-download, none of which run our error-path cleanup —
+// sit there indistinguishable from a real model, so listModels() would offer
+// it and loading it would fail with a confusing "corrupt GGUF" error instead
+// of the app just not knowing about it.
+export const PARTIAL_DOWNLOAD_SUFFIX = ".part";
+
 export async function downloadGgufFile(
     modelId: string,
     filename: string,
@@ -66,7 +74,8 @@ export async function downloadGgufFile(
 
     const totalBytes = Number(res.headers.get("content-length")) || null;
     let receivedBytes = 0;
-    const writeStream = fs.createWriteStream(destPath);
+    const partPath = destPath + PARTIAL_DOWNLOAD_SUFFIX;
+    const writeStream = fs.createWriteStream(partPath);
     const reader = res.body.getReader();
 
     try {
@@ -79,7 +88,33 @@ export async function downloadGgufFile(
                 writeStream.write(value, (err) => (err ? reject(err) : resolve()));
             });
         }
-    } finally {
+    } catch (err) {
         writeStream.end();
+        fs.rmSync(partPath, { force: true });
+        throw err;
+    }
+    await new Promise<void>((resolve, reject) => {
+        writeStream.once("error", reject);
+        writeStream.end(() => resolve());
+    });
+    if (totalBytes !== null && receivedBytes !== totalBytes) {
+        fs.rmSync(partPath, { force: true });
+        throw new Error(`Download of "${filename}" was incomplete (got ${receivedBytes} of ${totalBytes} bytes).`);
+    }
+    fs.renameSync(partPath, destPath);
+}
+
+// Leftover *.gguf.part files can only come from a download that never
+// finished (crash, force-quit, killed process) — there's no resume support,
+// so they're permanently unusable. Called once at startup rather than left
+// for the user to notice a phantom download stuck at some old percentage.
+export async function cleanupIncompleteDownloads(modelsDir: string): Promise<void> {
+    const fs = await import("node:fs");
+    const path = await import("node:path");
+    if (!fs.existsSync(modelsDir)) return;
+    for (const f of fs.readdirSync(modelsDir)) {
+        if (f.toLowerCase().endsWith(PARTIAL_DOWNLOAD_SUFFIX)) {
+            fs.rmSync(path.join(modelsDir, f), { force: true });
+        }
     }
 }

app/src/llamacpp-manager.test.ts

@@ -0,0 +1,86 @@
+import { describe, it, expect, beforeEach } from "vitest";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { groupShardedModels, listModels, deleteModel } from "./llamacpp-manager";
+
+describe("groupShardedModels", () => {
+    it("leaves a normal single-file model untouched", () => {
+        const result = groupShardedModels([{ name: "llama-3.2-3b.gguf", path: "/m/llama-3.2-3b.gguf", sizeBytes: 100 }]);
+        expect(result).toEqual([
+            { name: "llama-3.2-3b.gguf", label: "llama-3.2-3b.gguf", path: "/m/llama-3.2-3b.gguf", sizeBytes: 100 },
+        ]);
+    });
+
+    it("merges a multi-part model into a single labeled entry using the first shard as the loadable path", () => {
+        const result = groupShardedModels([
+            { name: "Qwen3-Coder-Next-Q6_K-00002-of-00002.gguf", path: "/m/part2.gguf", sizeBytes: 25_109_299 },
+            { name: "Qwen3-Coder-Next-Q6_K-00001-of-00002.gguf", path: "/m/part1.gguf", sizeBytes: 38_883_345 },
+        ]);
+        expect(result).toEqual([
+            {
+                name: "Qwen3-Coder-Next-Q6_K-00001-of-00002.gguf",
+                label: "Qwen3-Coder-Next-Q6_K.gguf (2 parts)",
+                path: "/m/part1.gguf",
+                sizeBytes: 25_109_299 + 38_883_345,
+            },
+        ]);
+    });
+
+    it("uses the lowest present part as the representative when part 1 is missing", () => {
+        const result = groupShardedModels([
+            { name: "model-00002-of-00003.gguf", path: "/m/p2.gguf", sizeBytes: 10 },
+            { name: "model-00003-of-00003.gguf", path: "/m/p3.gguf", sizeBytes: 10 },
+        ]);
+        expect(result[0].name).toBe("model-00002-of-00003.gguf");
+        expect(result[0].label).toBe("model.gguf (2 parts)");
+    });
+
+    it("keeps unrelated models and shard groups separate", () => {
+        const result = groupShardedModels([
+            { name: "other.gguf", path: "/m/other.gguf", sizeBytes: 5 },
+            { name: "a-00001-of-00002.gguf", path: "/m/a1.gguf", sizeBytes: 1 },
+            { name: "a-00002-of-00002.gguf", path: "/m/a2.gguf", sizeBytes: 1 },
+        ]);
+        expect(result).toHaveLength(2);
+        expect(result.map((m) => m.name).sort()).toEqual(["a-00001-of-00002.gguf", "other.gguf"]);
+    });
+});
+
+describe("listModels", () => {
+    let dir: string;
+
+    beforeEach(() => {
+        dir = fs.mkdtempSync(path.join(os.tmpdir(), "llamacpp-models-test-"));
+    });
+
+    it("returns an empty list when the directory doesn't exist", () => {
+        expect(listModels(path.join(dir, "missing"))).toEqual([]);
+    });
+
+    it("ignores incomplete .gguf.part downloads", () => {
+        fs.writeFileSync(path.join(dir, "finished.gguf"), "x".repeat(10));
+        fs.writeFileSync(path.join(dir, "still-downloading.gguf.part"), "x".repeat(3));
+        const names = listModels(dir).map((m) => m.name);
+        expect(names).toEqual(["finished.gguf"]);
+    });
+});
+
+describe("deleteModel", () => {
+    let dir: string;
+
+    beforeEach(() => {
+        dir = fs.mkdtempSync(path.join(os.tmpdir(), "llamacpp-delete-test-"));
+    });
+
+    it("deletes every shard of a multi-part model, not just the representative one", async () => {
+        fs.writeFileSync(path.join(dir, "big-00001-of-00002.gguf"), "x");
+        fs.writeFileSync(path.join(dir, "big-00002-of-00002.gguf"), "x");
+        await deleteModel(dir, "big-00001-of-00002.gguf");
+        expect(fs.readdirSync(dir)).toEqual([]);
+    });
+
+    it("rejects a path-traversal attempt", async () => {
+        await expect(deleteModel(dir, "../evil.gguf")).rejects.toThrow(/Invalid model file name/);
+    });
+});

app/src/llamacpp-manager.ts

@@ -226,20 +226,76 @@ export async function dispose(): Promise<void> {
 }
 
 export interface LocalGgufModel {
+    // Real file name of the representative shard (part 1, or the lowest part
+    // present) — this is what gets passed back to loadModel/deleteModel.
     name: string;
+    // What to show in the UI. Same as `name` for a normal single-file model;
+    // for a multi-part one it's a synthetic "(N parts)" label instead, since
+    // showing the raw "-00001-of-00002.gguf" filename as if it were the
+    // whole model's name is misleading.
+    label: string;
     path: string;
     sizeBytes: number;
 }
 
+// Matches Hugging Face's multi-part GGUF naming convention, e.g.
+// "Qwen3-Coder-Next-Q6_K-00001-of-00002.gguf". node-llama-cpp loads every
+// part automatically once given the path to part 1, so listing each shard
+// as its own separate model is both confusing (one weight file looks like
+// two different models) and wrong (selecting a non-first shard on its own
+// doesn't work) — group them into a single entry instead.
+const SHARD_PATTERN = /^(.*)-(\d+)-of-(\d+)(\.gguf)$/i;
+
+interface RawGgufFile {
+    name: string;
+    path: string;
+    sizeBytes: number;
+}
+
+export function groupShardedModels(files: RawGgufFile[]): LocalGgufModel[] {
+    const groups = new Map<string, { totalSize: number; parts: Map<number, RawGgufFile> }>();
+    const standalone: LocalGgufModel[] = [];
+
+    for (const file of files) {
+        const match = file.name.match(SHARD_PATTERN);
+        if (!match) {
+            standalone.push({ ...file, label: file.name });
+            continue;
+        }
+        const [, base, partStr, , ext] = match;
+        const key = `${base}${ext}`;
+        const part = Number(partStr);
+        const group = groups.get(key) ?? { totalSize: 0, parts: new Map() };
+        group.totalSize += file.sizeBytes;
+        group.parts.set(part, file);
+        groups.set(key, group);
+    }
+
+    const grouped: LocalGgufModel[] = [...groups.entries()].map(([key, group]) => {
+        const lowestPart = Math.min(...group.parts.keys());
+        const representative = group.parts.get(lowestPart)!;
+        const partCount = group.parts.size;
+        return {
+            name: representative.name,
+            label: partCount > 1 ? `${key} (${partCount} parts)` : representative.name,
+            path: representative.path,
+            sizeBytes: group.totalSize,
+        };
+    });
+
+    return [...standalone, ...grouped];
+}
+
 export function listModels(modelsDir: string): LocalGgufModel[] {
     if (!fs.existsSync(modelsDir)) return [];
-    return fs
+    const files = fs
         .readdirSync(modelsDir)
         .filter((f) => f.toLowerCase().endsWith(".gguf"))
         .map((f) => {
             const full = path.join(modelsDir, f);
             return { name: f, path: full, sizeBytes: fs.statSync(full).size };
         });
+    return groupShardedModels(files);
 }
 
 // Model paths currently kept warm in modelCache — used for the
@@ -276,9 +332,26 @@ export async function deleteModel(modelsDir: string, name: string): Promise<void
     }
     await Promise.allSettled(modelsToDispose.map((model) => model.dispose()));
     fs.rmSync(target, { force: true });
+
+    // A multi-part model's sibling shards live under the same name pattern
+    // in the same directory — leaving them behind would orphan otherwise-
+    // unusable files that just sit there confusing the next listModels() call.
+    const shardMatch = name.match(SHARD_PATTERN);
+    if (shardMatch) {
+        const [, base, , , ext] = shardMatch;
+        const siblingPattern = new RegExp(`^${escapeRegExp(base)}-\\d+-of-\\d+${escapeRegExp(ext)}$`, "i");
+        for (const f of fs.readdirSync(root)) {
+            if (f !== name && siblingPattern.test(f)) fs.rmSync(path.join(root, f), { force: true });
+        }
+    }
+
     scheduleIdleEviction();
 }
 
+function escapeRegExp(s: string): string {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
 // Maps this app's provider-agnostic ChatMessage[] (system/user/assistant,
 // full history resent on every call — same shape every provider gets) onto
 // node-llama-cpp's ChatHistoryItem[] shape. Tool/function-calling isn't

app/src/main.ts

@@ -767,6 +767,10 @@ app.whenReady().then(async () => {
     await ollama.start();
     llamacpp.setModelCacheLimit(settingsStore.getSettings().llamaCppMaxCachedModels ?? 2);
     await llamacpp.setGpuBackend(settingsStore.getSettings().llamaCppGpuBackend ?? "auto");
+    // Leftover *.gguf.part files from a download that never finished last
+    // session (crash, force-quit) — there's no resume support, so they can
+    // only ever be dead weight; clear them before the model list is ever read.
+    await huggingface.cleanupIncompleteDownloads(getLlamaCppModelsDir());
     setupAutoUpdater(() => mainWindow);
     void connectEnabledMcpServers();
     scheduler.init((provider, model, prompt) => completePrompt(provider as ProviderId, model, prompt));

frontend/src/pages/Chat.tsx

@@ -1456,7 +1456,7 @@ export default function Chat() {
                                 <SelectLabel>llama.cpp (local)</SelectLabel>
                                 {llamaCppModels.map((m) => (
                                     <SelectItem key={m.name} value={formatModelRef("llamacpp", m.name)}>
-                                        {m.name}
+                                        {m.label}
                                     </SelectItem>
                                 ))}
                             </SelectGroup>
@@ -1476,7 +1476,7 @@ export default function Chat() {
                                 <SelectLabel>ROCm (AMD)</SelectLabel>
                                 {llamaCppModels.map((m) => (
                                     <SelectItem key={m.name} value={formatModelRef("rocm", m.name)}>
-                                        {m.name}
+                                        {m.label}
                                     </SelectItem>
                                 ))}
                             </SelectGroup>

frontend/src/pages/Compare.tsx

@@ -42,7 +42,7 @@ export default function Compare() {
 
     const candidates: CandidateModel[] = [
         ...ollamaModels.map((m) => ({ ref: formatModelRef("ollama", m.name), label: `${m.name} (Ollama)` })),
-        ...llamaCppModels.map((m) => ({ ref: formatModelRef("llamacpp", m.name), label: `${m.name} (llama.cpp)` })),
+        ...llamaCppModels.map((m) => ({ ref: formatModelRef("llamacpp", m.name), label: `${m.label} (llama.cpp)` })),
         ...OPENAI_MODELS.map((m) => ({ ref: formatModelRef("openai", m.id), label: m.label })),
         ...ANTHROPIC_MODELS.map((m) => ({ ref: formatModelRef("anthropic", m.id), label: m.label })),
         ...GEMINI_MODELS.map((m) => ({ ref: formatModelRef("gemini", m.id), label: m.label })),

frontend/src/pages/Settings.tsx

@@ -337,7 +337,8 @@ export default function Settings() {
             delete next[key];
             return next;
         });
-        if (!res.error) window.api.llamacpp.listModels().then(setLlamaCppModels);
+        if (res.error) toast.error(res.error);
+        else window.api.llamacpp.listModels().then(setLlamaCppModels);
     }
 
     async function deleteLlamaCppModel(name: string) {
@@ -1094,12 +1095,12 @@ export default function Settings() {
                                     </div>
                                 </SettingsRow>
                                 {llamaCppModels.map((m) => (
-                                    <SettingsRow key={m.name} label={m.name} description={formatBytes(m.sizeBytes)}>
+                                    <SettingsRow key={m.name} label={m.label} description={formatBytes(m.sizeBytes)}>
                                         <Button
                                             size="icon"
                                             variant="ghost"
                                             onClick={() => deleteLlamaCppModel(m.name)}
-                                            aria-label={`Delete ${m.name}`}
+                                            aria-label={`Delete ${m.label}`}
                                         >
                                             <Trash2 className="text-destructive" />
                                         </Button>

frontend/src/types/electron.d.ts

@@ -350,6 +350,7 @@ export interface CustomProviderConfig {
 
 export interface LocalGgufModel {
   name: string;
+  label: string;
   path: string;
   sizeBytes: number;
 }