[thcp]

What changes for the user

• Disk space after a crash comes back on the next start. A stem fill, a vocal split decode, a stem written beside its final name, an export render and an all-stems zip each write to a temp name first. A force quit, a power loss or an OOM kill in the middle used to leave that temp on disk for good, often hundreds of MB, in a dot-named file nobody could find. The startup sweep now removes them.
• A cancelled zip export no longer leaves its zip behind. Stopping the server during an all-stems zip skipped the cleanup (CancelledError is not an Exception), and the build thread went on writing.
• Two exports with the same click no longer lose one click. They shared one temp name, so the first rename could take the other's file away.

What the sweep may remove, and what it never touches

• Song folders: only those registry.job_dirs and holds_job_files accept (the rule from fix(reset): remove only StemDeck's own entries in a shared jobs folder #886), and never through a link or junction (is_real_entry).
  • .fill-<8 hex>/ (stem fill work folder)
  • in stems/: .decode-*/ (vocal split decode), and dot names ending in .tmp or .tmp.mp3, file or folder (stem writes)
• Export caches (cache/mixdown, cache/click): only the exact temp names (.<name>.<32 hex>.tmp[.ext], .stemdeck_zip_*.zip, .zipwork-*/), and only when nothing has written them for 10 minutes, because a second server can share the cache folder.
• It runs once, at startup, before the queue starts anything, like the existing section workspace and render temp sweeps.
• A song's stems, MP3s, peaks, beats, source, metadata and takes, finished or stopped, never match any of these names.

Other changes that make the sweep exact

• The vocal split decode moved from the system temp folder to a dot folder beside the stem.
• The zip, and the folder its stems are transcoded in, moved from the system temp folder to the export cache.
• The sweep therefore never deletes in a folder that other programs share.
• The zip temp now goes once the request has given it up and the build thread has ended, whichever comes second. On Windows, removing it sooner fails while the thread holds the file.
• Each click render gets its own uuid dot name, removed in a finally.
• tests/conftest.py now points the export caches at a per-test folder. Every TestClient lifespan runs the sweep, and it must never reach a developer's real cache.

How it was verified

• New tests in tests/test_crash_leftovers.py. All 4 fail on big-release and pass with this change:
  • Startup removes every planted leftover and keeps every file of a finished song and of a stopped song, plus the cache entries, a recent cache temp, a .DS_Store, and folders that are not StemDeck's.
  • The sweep never follows a junction: neither a linked song folder nor a linked stems/.
  • A zip request cancelled mid-build: the file stays while the thread writes, and is gone once the thread ends. It is built in the export cache.
  • Two renders of one click key: on big-release the second one fails with FileNotFoundError; with this change both finish.
• Full Python suite, ruff check and ruff format --check pass.
• End to end on a throwaway server (Windows, uvicorn, throwaway jobs, data and cache folders):
  • 8 planted leftovers were gone after startup, and none of the 22 song files was lost.
  • WAV and MP3 zips downloaded correctly, with nothing left in the cache.
  • A client that disconnected after the first bytes left nothing either: uvicorn still runs the response's background cleanup.
• Merges cleanly with the open atomic stem writes branch, and its .vocal_split.<hex>.tmp work folder is covered.

Update path

• Does not touch uv.lock or the desktop shell.