cursedbelt-server 1.0.0

package/src/server/dropzone/index.ts

@@ -0,0 +1,30 @@
+/**
+ * `cursedbelt-server/dropzone` — the reusable drop-folder scraper.
+ *
+ * Drop a tree of files into a folder; a sweep walks it, hands each file to the app's handler,
+ * deletes only what the handler confirmed was filed somewhere else, and prunes the folders it
+ * empties. Nothing app-specific lives here: what a file MEANS is the app's, what happens to a
+ * file on disk is this module's.
+ *
+ * Consumers (2026-08-13): `apps/music`, `apps/family`, `apps/collections` in
+ * cursed-satellites. Each supplies a `DropHandler` and nothing else.
+ */
+export {
+	describeSweep,
+	isJunkName,
+	isStable,
+	pruneEmptyDirs,
+	scanDropzone,
+	sweepDropzone,
+	type DropHandler,
+	type DropOutcome,
+	type DroppedFile,
+	type ScanOptions,
+	type SweepReport,
+} from "./scan";
+export {
+	askBinaryServerAboutDuplicate,
+	hashFile,
+	type DuplicateVerdict,
+	type DuplicateQuestion,
+} from "./duplicates";

package/src/server/dropzone/scan.spec.ts

@@ -0,0 +1,255 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { existsSync, mkdirSync, mkdtempSync, rmSync, utimesSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+	describeSweep,
+	isJunkName,
+	pruneEmptyDirs,
+	scanDropzone,
+	sweepDropzone,
+	type DropOutcome,
+	type DroppedFile,
+} from "./scan";
+
+/**
+ * The drop-folder scraper.
+ *
+ * Almost every test here is about DESTRUCTION — what the sweep deletes and, more importantly,
+ * what it must not. The dropzone is the one place the owner's copy may be the only copy: they
+ * dragged the file in expecting it to be taken, and if the sweep is wrong the original is
+ * gone with nothing to restore from.
+ */
+
+let root: string;
+
+const write = (rel: string, bytes = 8): void => {
+	const full = join(root, rel);
+	mkdirSync(join(full, ".."), { recursive: true });
+	writeFileSync(full, Buffer.alloc(bytes, 7));
+};
+
+beforeEach(() => {
+	root = mkdtempSync(join(tmpdir(), "dropzone-spec-"));
+});
+afterEach(() => rmSync(root, { recursive: true, force: true }));
+
+// A stability window of 0 keeps these tests fast; rule 2 gets its own test below.
+const sweep = (handle: (f: DroppedFile) => Promise<DropOutcome>, opts = {}) =>
+	sweepDropzone(root, handle, { stabilityMs: 0, ...opts });
+
+describe("scanDropzone", () => {
+	test("finds files at every depth, with their path relative to the root", async () => {
+		write("a.mp3");
+		write("Album/b.mp3");
+		write("Album/Disc 2/c.mp3");
+		const found = await scanDropzone(root);
+		expect(found.map((f) => f.relativePath).sort()).toEqual([
+			"Album/Disc 2/c.mp3",
+			"Album/b.mp3",
+			"a.mp3",
+		]);
+	});
+
+	test("🔴 returns junk too, because a sweep that must DELETE junk has to see it", async () => {
+		// "if it's a wrong type of file delete it" — a scanner that filtered these out would
+		// leave them in the folder forever, and the owner's requirement is an EMPTY folder.
+		write(".DS_Store");
+		write("track.mp3");
+		expect((await scanDropzone(root)).map((f) => f.name).sort()).toEqual([".DS_Store", "track.mp3"]);
+	});
+
+	test("captureSiblings records each directory's file list on the ONE walk", async () => {
+		// A folder's cover.jpg is only reachable while the directory still exists, and filing
+		// the audio out of it removes the neighbours. Re-reading later finds nothing.
+		write("Album/track.mp3");
+		write("Album/cover.jpg");
+		const found = await scanDropzone(root, { captureSiblings: true });
+		const track = found.find((f) => f.name === "track.mp3");
+		expect(track?.siblings.sort()).toEqual(["cover.jpg", "track.mp3"]);
+	});
+
+	test("skipDirs keeps the sweep out of another app's queue", async () => {
+		write("collections/video.mp4");
+		write("mine.mp3");
+		const found = await scanDropzone(root, { skipDirs: ["collections"] });
+		expect(found.map((f) => f.name)).toEqual(["mine.mp3"]);
+	});
+
+	test("the extension is lowercased and includes the dot; a dotless name has none", async () => {
+		write("LOUD.MP3");
+		write("README");
+		const byName = new Map((await scanDropzone(root)).map((f) => [f.name, f.ext]));
+		expect(byName.get("LOUD.MP3")).toBe(".mp3");
+		expect(byName.get("README")).toBe("");
+	});
+});
+
+describe("isJunkName", () => {
+	test("OS bookkeeping, resource forks and in-flight downloads", () => {
+		for (const name of [".DS_Store", "Thumbs.db", "._track.mp3", "movie.mp4.part", ".hidden"])
+			expect(isJunkName(name)).toBe(true);
+	});
+	test("real content is not junk, whatever it is called", () => {
+		for (const name of ["track.mp3", "cover.jpg", "Holiday.MP4", "notes"])
+			expect(isJunkName(name)).toBe(false);
+	});
+});
+
+describe("sweepDropzone — what gets deleted", () => {
+	test("🔴 a CONFIRMED file is deleted; a FAILED one is left exactly where it is", async () => {
+		// Rule 1, and the whole reason this module exists. Deleting on "the upload didn't throw"
+		// turns any catalog failure into permanent data loss.
+		write("good.mp3");
+		write("bad.mp3");
+		const report = await sweep(async (f) =>
+			f.name === "good.mp3"
+				? { kind: "stored" }
+				: { kind: "failed", detail: "the catalog said no" },
+		);
+		expect(existsSync(join(root, "good.mp3"))).toBe(false);
+		expect(existsSync(join(root, "bad.mp3"))).toBe(true);
+		expect(report.stored).toBe(1);
+		expect(report.failed).toHaveLength(1);
+	});
+
+	test("🔴 a DUPLICATE is deleted — that is the point of recognising one", async () => {
+		// "if it's a dup skip it then delete it". The bytes are already safe at the destination,
+		// so keeping the local copy is exactly the two-copies problem the owner is solving.
+		write("already-have.mp3");
+		await sweep(async () => ({ kind: "duplicate" }));
+		expect(existsSync(join(root, "already-have.mp3"))).toBe(false);
+	});
+
+	test("🔴 a HELD file survives — it is a question, not a failure", async () => {
+		write("maybe-dup.mp3");
+		const report = await sweep(async () => ({ kind: "held", detail: "waiting on the owner" }));
+		expect(existsSync(join(root, "maybe-dup.mp3"))).toBe(true);
+		expect(report.held).toBe(1);
+		expect(report.failed).toHaveLength(0);
+	});
+
+	test("a DISCARD is deleted, so junk cannot accumulate", async () => {
+		write("junk.txt");
+		await sweep(async () => ({ kind: "discard", detail: "not audio" }));
+		expect(existsSync(join(root, "junk.txt"))).toBe(false);
+	});
+
+	test("🔴 a handler that THROWS costs one file, never the sweep", async () => {
+		// "This should not stall uploading the rest of the in progress uploads" — stated by the
+		// owner about duplicates, and just as true of a corrupt file in the middle of 4,000.
+		write("one.mp3");
+		write("two.mp3");
+		write("three.mp3");
+		const report = await sweep(async (f) => {
+			if (f.name === "two.mp3") throw new Error("kaboom");
+			return { kind: "stored" };
+		});
+		expect(report.stored).toBe(2);
+		expect(report.failed).toHaveLength(1);
+		expect(report.failed[0]?.error).toContain("kaboom");
+		expect(existsSync(join(root, "two.mp3"))).toBe(true);
+	});
+
+	test("dryRun deletes nothing at all", async () => {
+		write("a.mp3");
+		write("b.mp3");
+		await sweep(async () => ({ kind: "stored" }), { dryRun: true });
+		expect(existsSync(join(root, "a.mp3"))).toBe(true);
+		expect(existsSync(join(root, "b.mp3"))).toBe(true);
+	});
+
+	test("🔴 a genuinely EMPTY file is handled, not stranded as forever-copying", async () => {
+		// The obvious "same size twice AND non-empty" test treats a real 0-byte file as
+		// permanently mid-copy: never handled, never deleted, so the folder never empties —
+		// which is the one thing the owner's brief measures success by. Measured on a first
+		// run: three real files, all 0 bytes, reported "still copying" on every sweep.
+		writeFileSync(join(root, "empty.txt"), "");
+		const old = new Date(Date.now() - 5 * 60_000);
+		utimesSync(join(root, "empty.txt"), old, old);
+		const report = await sweep(async () => ({ kind: "discard" }));
+		expect(report.unstable).toEqual([]);
+		expect(report.discarded).toBe(1);
+		expect(existsSync(join(root, "empty.txt"))).toBe(false);
+	});
+
+	test("a BRAND-NEW empty file is still treated as arriving", async () => {
+		// Emptiness is evidence of an unfinished copy only while the file is new.
+		writeFileSync(join(root, "arriving.bin"), "");
+		const report = await sweep(async () => ({ kind: "discard" }));
+		expect(report.unstable).toEqual(["arriving.bin"]);
+		expect(existsSync(join(root, "arriving.bin"))).toBe(true);
+	});
+
+	test("🔴 an unstable file is skipped and reported as still-copying, not as failed", async () => {
+		// Dropping a 4 GB video is not atomic. Calling this a failure would send the owner
+		// looking for a bug in a file that is arriving perfectly.
+		write("growing.mp4", 10);
+		let handled = 0;
+		const report = await sweepDropzone(
+			root,
+			async () => {
+				handled++;
+				return { kind: "stored" };
+			},
+			{
+				// A real gap, and the file grows during it — exactly the live case.
+				stabilityMs: 30,
+				onProgress: () => writeFileSync(join(root, "growing.mp4"), Buffer.alloc(9999)),
+			},
+		);
+		expect(handled).toBe(0);
+		expect(report.unstable).toEqual(["growing.mp4"]);
+		expect(existsSync(join(root, "growing.mp4"))).toBe(true);
+	});
+});
+
+describe("sweepDropzone — leaving nothing behind", () => {
+	test("🔴 an emptied tree is removed and the report says the folder is empty", async () => {
+		// The owner's actual acceptance test: "In the end there should be nothing left in the
+		// myMusic dir."
+		write("Album/Disc 1/a.mp3");
+		write("Album/Disc 1/b.mp3");
+		write("Album/cover.jpg");
+		const report = await sweep(async () => ({ kind: "stored" }));
+		expect(existsSync(join(root, "Album"))).toBe(false);
+		expect(existsSync(root)).toBe(true); // never the root itself
+		expect(report.remaining).toBe(0);
+		expect(describeSweep(report)).toContain("folder is empty");
+	});
+
+	test("🔴 a directory holding a HELD or FAILED file is NOT removed", async () => {
+		// rmdir refusing a non-empty directory is the safety property. A recursive delete here
+		// would take exactly the files the sweep decided to keep.
+		write("Keep/held.mp3");
+		write("Gone/stored.mp3");
+		await sweep(async (f) => (f.name === "held.mp3" ? { kind: "held" } : { kind: "stored" }));
+		expect(existsSync(join(root, "Keep/held.mp3"))).toBe(true);
+		expect(existsSync(join(root, "Gone"))).toBe(false);
+	});
+
+	test("the report counts the bytes reclaimed from the queue", async () => {
+		write("a.mp3", 1000);
+		write("b.mp3", 2000);
+		const report = await sweep(async () => ({ kind: "stored" }));
+		expect(report.bytesRemoved).toBe(3000);
+	});
+});
+
+describe("pruneEmptyDirs", () => {
+	test("collapses a deep empty chain in ONE pass and never removes the root", async () => {
+		mkdirSync(join(root, "a/b/c/d"), { recursive: true });
+		const removed = await pruneEmptyDirs(root);
+		expect(removed).toBe(4);
+		expect(existsSync(join(root, "a"))).toBe(false);
+		expect(existsSync(root)).toBe(true);
+	});
+
+	test("stops at a directory that still holds something", async () => {
+		write("a/b/keep.txt");
+		mkdirSync(join(root, "a/b/empty"), { recursive: true });
+		await pruneEmptyDirs(root);
+		expect(existsSync(join(root, "a/b/empty"))).toBe(false);
+		expect(existsSync(join(root, "a/b/keep.txt"))).toBe(true);
+	});
+});

package/src/server/dropzone/scan.ts

@@ -0,0 +1,342 @@
+/**
+ * The drop-folder scraper — the reusable half.
+ *
+ * Owner's ask, 2026-08-13: *"Do this to prepare a reusable strategy for multiple apps to get
+ * intelligent processing for binary-server. Some functionality may be reusable in multiple
+ * apps in different ways and can go in cb where standardized app functionality is shared. The
+ * specific ingestion logic that only binary-server or one app needs can go to the specific
+ * app."* … *"Make this tool reusable in case we need something like it on other folders
+ * later."*
+ *
+ * So: WALKING a drop folder, deciding a file has finished copying, sorting content from junk,
+ * deleting only what has been confirmed elsewhere, and leaving nothing behind — all of that is
+ * the same for music, family photographs, collections videos and notes documents, and all of
+ * it is here. What a file MEANS — which album, which artist, which collection — is the app's,
+ * and none of it is here.
+ *
+ * ── 🔴 Three rules that look like paranoia and are not ─────────────────────────────────
+ *
+ * 1. **A file is deleted only after the destination CONFIRMS it.** The dropzone is the one
+ *    place the owner's copy may be the only copy: they dragged it in expecting it to be taken.
+ *    A sweep that deletes on "the upload didn't throw" turns any catalog failure into data
+ *    loss. The handler returns `stored`/`duplicate` and only then does the original go.
+ *
+ * 2. **A file must measure the same size twice before it is touched.** Dropping a 4 GB video
+ *    into a folder is not atomic. Without this the sweep ingests a truncated file, reports
+ *    success, and deletes the real one as it is still being written. notes' ingester and
+ *    collections' both learned this the same way.
+ *
+ * 3. **One bad file never stops the sweep.** Every handler outcome is per-file, and a throw is
+ *    caught and recorded. The owner's instruction is explicit about the duplicate case — *"This
+ *    should not stall uploading the rest of the in progress uploads"* — and it generalizes: a
+ *    dropzone with one unreadable file in it must still drain the other 4,000.
+ */
+
+import type { Dirent } from "node:fs";
+import { readdir, rm, rmdir, stat } from "node:fs/promises";
+import { join, relative } from "node:path";
+
+/** A file the sweep found, with everything a handler needs to decide about it. */
+export interface DroppedFile {
+	/** Absolute path on disk. */
+	path: string;
+	/** Path relative to the dropzone root — the app's only clue about where it was filed. */
+	relativePath: string;
+	/** The filename, no directories. */
+	name: string;
+	/** Lowercased extension INCLUDING the dot, or `""` for a file that has none. */
+	ext: string;
+	size: number;
+	mtimeMs: number;
+	/** Every other FILE name in the same directory — see {@link ScanOptions.captureSiblings}. */
+	siblings: string[];
+}
+
+export type DropOutcome =
+	/** Filed successfully. The original is deleted. */
+	| { kind: "stored"; detail?: string }
+	/** Already present at the destination. The original is deleted — that is the point. */
+	| { kind: "duplicate"; detail?: string }
+	/** Not content: junk, an unusable sidecar, a format this app does not take. DELETED. */
+	| { kind: "discard"; detail?: string }
+	/** Deliberately parked (a duplicate awaiting a decision). LEFT ALONE, not retried loudly. */
+	| { kind: "held"; detail?: string }
+	/** Could not be filed. LEFT IN PLACE and reported. */
+	| { kind: "failed"; detail: string };
+
+export interface SweepReport {
+	scanned: number;
+	stored: number;
+	duplicate: number;
+	discarded: number;
+	held: number;
+	failed: { relativePath: string; error: string }[];
+	/** Files still being copied in — they are picked up by the next sweep, not an error. */
+	unstable: string[];
+	bytesRemoved: number;
+	emptyDirsRemoved: number;
+	/** Anything left in the root when the sweep finished. Empty is the goal. */
+	remaining: number;
+}
+
+export interface ScanOptions {
+	/** Two size samples this far apart prove a copy finished. */
+	stabilityMs?: number;
+	/** Names that are never content, on top of the built-in OS list. */
+	reservedNames?: string[];
+	/**
+	 * Capture each directory's file listing on the ONE walk.
+	 *
+	 * 🔴 Load-bearing for sidecar art, and it cannot be done later. A folder's `cover.jpg` is
+	 * only reachable while the directory still exists, and filing the audio out of it removes
+	 * the neighbours — by the time anything else could look, they are gone. Capturing on the
+	 * walk also costs one `readdir` per directory instead of one per file, which on a 6,000
+	 * track library is the difference between seconds and minutes.
+	 */
+	captureSiblings?: boolean;
+	/** Directory names to skip entirely at any depth (another app's queue, our own state). */
+	skipDirs?: string[];
+	/** Stop after this many files. Absent means everything. */
+	limit?: number;
+}
+
+/** OS bookkeeping and editor scratch. Never content, in any app. */
+const OS_JUNK = new Set([
+	".DS_Store",
+	".localized",
+	"Icon\r",
+	"Thumbs.db",
+	"desktop.ini",
+	"README.md",
+]);
+
+const PARTIAL_SUFFIXES = [".download", ".crdownload", ".part", ".partial", ".tmp"];
+
+/** A name that is OS noise, editor scratch, or a copy still in flight. */
+export function isJunkName(name: string): boolean {
+	if (OS_JUNK.has(name)) return true;
+	// A dotfile in a drop folder is the operating system's or another tool's state. The owner
+	// drops content, and content does not begin with a dot.
+	if (name.startsWith(".")) return true;
+	if (name.startsWith("._")) return true; // AppleDouble resource forks
+	return PARTIAL_SUFFIXES.some((s) => name.toLowerCase().endsWith(s));
+}
+
+const extOf = (name: string): string => {
+	const dot = name.lastIndexOf(".");
+	return dot > 0 ? name.slice(dot).toLowerCase() : "";
+};
+
+/**
+ * Every candidate file under `root`, deepest-last, with each one's sibling listing.
+ *
+ * Junk is NOT filtered out here — it is returned like anything else, because a sweep whose job
+ * includes *"if it's a wrong type of file delete it"* has to see it in order to delete it.
+ * {@link isJunkName} is exported so a handler can classify without re-deriving the list.
+ */
+export async function scanDropzone(root: string, opts: ScanOptions = {}): Promise<DroppedFile[]> {
+	const skip = new Set(opts.skipDirs ?? []);
+	const out: DroppedFile[] = [];
+
+	const walk = async (dir: string): Promise<void> => {
+		if (opts.limit !== undefined && out.length >= opts.limit) return;
+		let entries: Dirent[];
+		try {
+			entries = await readdir(dir, { withFileTypes: true });
+		} catch {
+			return; // vanished mid-walk — a dropzone is a moving target by nature
+		}
+		const siblings = opts.captureSiblings
+			? entries.filter((e) => e.isFile()).map((e) => e.name)
+			: [];
+
+		for (const entry of entries) {
+			if (opts.limit !== undefined && out.length >= opts.limit) return;
+			const full = join(dir, entry.name);
+			if (entry.isDirectory()) {
+				if (skip.has(entry.name)) continue;
+				await walk(full);
+				continue;
+			}
+			if (!entry.isFile()) continue;
+			try {
+				const info = await stat(full);
+				out.push({
+					path: full,
+					relativePath: relative(root, full),
+					name: entry.name,
+					ext: extOf(entry.name),
+					size: info.size,
+					mtimeMs: info.mtimeMs,
+					siblings,
+				});
+			} catch {
+				/* gone between readdir and stat */
+			}
+		}
+	};
+
+	await walk(root);
+	return out;
+}
+
+/**
+ * How old an EMPTY file has to be before it is believed. See {@link isStable}.
+ *
+ * A file that has just been created and has no bytes yet is almost certainly mid-copy; the
+ * same file a minute later really is empty.
+ */
+export const EMPTY_FILE_GRACE_MS = 60_000;
+
+/**
+ * Has this file finished being copied in? See rule 2 in the header.
+ *
+ * 🔴 A zero-byte file needs its own answer, and getting it wrong strands the folder forever.
+ * The obvious test — "same size twice AND non-empty" — treats a genuinely empty file as
+ * permanently mid-copy: it is never handled, never deleted, and so the dropzone never empties,
+ * which is the one outcome the owner's brief measures success by (*"in the end there should be
+ * nothing left"*). Measured on a first run: three real files, all 0 bytes, reported as "still
+ * copying" on every sweep for as long as they sat there.
+ *
+ * Emptiness is only evidence of an unfinished copy while the file is NEW, so age decides. A
+ * file created a minute ago with no bytes in it is empty, not arriving.
+ */
+export async function isStable(file: DroppedFile, stabilityMs = 750): Promise<boolean> {
+	await new Promise((resolve) => setTimeout(resolve, stabilityMs));
+	try {
+		const now = await stat(file.path);
+		if (now.size !== file.size) return false; // still growing
+		if (now.size > 0) return true;
+		return Date.now() - now.mtimeMs > EMPTY_FILE_GRACE_MS;
+	} catch {
+		return false; // taken by something else, or never really there
+	}
+}
+
+/**
+ * Remove directories left empty by a sweep, deepest first — and never the root.
+ *
+ * 🔴 `rmdir` refuses a non-empty directory, and that refusal IS the safety property. A
+ * recursive delete here would take a file the sweep deliberately chose not to ingest — a held
+ * duplicate, a failure left in place for the owner to look at — which is precisely the set of
+ * files that must survive.
+ */
+export async function pruneEmptyDirs(root: string, dir = root): Promise<number> {
+	let removed = 0;
+	let entries: string[];
+	try {
+		entries = await readdir(dir);
+	} catch {
+		return 0;
+	}
+	for (const name of entries) {
+		const full = join(dir, name);
+		try {
+			if ((await stat(full)).isDirectory()) removed += await pruneEmptyDirs(root, full);
+		} catch {
+			/* gone */
+		}
+	}
+	if (dir === root) return removed;
+	try {
+		await rmdir(dir);
+		return removed + 1;
+	} catch {
+		return removed; // not empty — the right outcome, and not an error
+	}
+}
+
+/** What the app supplies: what to do with one file. */
+export type DropHandler = (file: DroppedFile) => Promise<DropOutcome>;
+
+/**
+ * Walk a dropzone, hand every file to `handle`, and leave nothing behind that was dealt with.
+ *
+ * 🔴 The DELETION is here, and it is deliberately not the handler's job. Every app would
+ * otherwise reimplement rule 1, and the one that got it wrong would lose the owner's only copy
+ * silently. A handler says what happened; this decides what that means for the file on disk.
+ */
+export async function sweepDropzone(
+	root: string,
+	handle: DropHandler,
+	opts: ScanOptions & { dryRun?: boolean; onProgress?: (done: number, total: number) => void } = {},
+): Promise<SweepReport> {
+	const report: SweepReport = {
+		scanned: 0,
+		stored: 0,
+		duplicate: 0,
+		discarded: 0,
+		held: 0,
+		failed: [],
+		unstable: [],
+		bytesRemoved: 0,
+		emptyDirsRemoved: 0,
+		remaining: 0,
+	};
+
+	const files = await scanDropzone(root, opts);
+	for (const [index, file] of files.entries()) {
+		report.scanned++;
+		opts.onProgress?.(index + 1, files.length);
+
+		if (!(await isStable(file, opts.stabilityMs))) {
+			report.unstable.push(file.relativePath);
+			continue;
+		}
+
+		let outcome: DropOutcome;
+		try {
+			outcome = opts.dryRun ? { kind: "held", detail: "dry run" } : await handle(file);
+		} catch (error) {
+			// Rule 3: a handler that throws costs one file, never the sweep.
+			outcome = {
+				kind: "failed",
+				detail: error instanceof Error ? error.message : String(error),
+			};
+		}
+
+		switch (outcome.kind) {
+			case "stored":
+			case "duplicate":
+			case "discard": {
+				if (outcome.kind === "stored") report.stored++;
+				else if (outcome.kind === "duplicate") report.duplicate++;
+				else report.discarded++;
+				if (opts.dryRun) break;
+				try {
+					await rm(file.path);
+					report.bytesRemoved += file.size;
+				} catch (error) {
+					// The bytes are safe at the destination; only the tidying failed. Reporting it
+					// as a FAILURE would send the owner looking for a file that arrived perfectly.
+					report.failed.push({
+						relativePath: file.relativePath,
+						error: `filed, but the original could not be removed: ${
+							error instanceof Error ? error.message : String(error)
+						}`,
+					});
+				}
+				break;
+			}
+			case "held":
+				report.held++;
+				break;
+			case "failed":
+				report.failed.push({ relativePath: file.relativePath, error: outcome.detail });
+				break;
+		}
+	}
+
+	if (!opts.dryRun) report.emptyDirsRemoved = await pruneEmptyDirs(root);
+	report.remaining = (await scanDropzone(root, { skipDirs: opts.skipDirs })).length;
+	return report;
+}
+
+/** A one-line summary — every consumer prints one, and they should read alike. */
+export const describeSweep = (report: SweepReport): string =>
+	`${report.stored} added, ${report.duplicate} already had, ${report.discarded} discarded, ` +
+	`${report.held} held, ${report.failed.length} failed, ${report.unstable.length} still copying` +
+	(report.bytesRemoved > 0
+		? ` · ${(report.bytesRemoved / 1024 ** 3).toFixed(2)} GB freed from the queue`
+		: "") +
+	(report.remaining > 0 ? ` · ${report.remaining} left in the folder` : " · folder is empty");