spotifify 0.1.1 → 0.1.3

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # Changelog
 
+## [0.1.3](https://github.com/FYWinds/Spotifify/compare/v0.1.2...v0.1.3) (2026-09-05)
+
+
+### Bug Fixes
+
+* **match:** let a fingerprint hit decide for a pooled track ([75c2717](https://github.com/FYWinds/Spotifify/commit/75c27178f16b277a5062ff3aff5c396bbc36ec4b))
+* **sources:** unreadable files and partial pulls are not deletions ([0fb80a7](https://github.com/FYWinds/Spotifify/commit/0fb80a7a3af3a03d06543e118be1cb7171fd5880))
+* **spotify:** make playlist writes safe to interrupt and retry ([5882336](https://github.com/FYWinds/Spotifify/commit/5882336ec47f4c8ededef8712312864f7d1d7f16))
+* **sync:** never prune beyond what the run reconciles ([fd1d732](https://github.com/FYWinds/Spotifify/commit/fd1d732fa06cfcff5b855f60ff90c68414d41bb9))
+
+## [0.1.2](https://github.com/FYWinds/Spotifify/compare/v0.1.1...v0.1.2) (2026-09-05)
+
+
+### Features
+
+* **doctor:** check the client's local-file index ([bdc099b](https://github.com/FYWinds/Spotifify/commit/bdc099bfa54abaae2a9f75b4d804fd9fd41f90eb))
+* **sync:** prune superseded exports with --prune ([4db0559](https://github.com/FYWinds/Spotifify/commit/4db05590f9c318e57703a5f8cdcc7be96850a58e))
+
+
+### Bug Fixes
+
+* **sync:** prune against the listing snapshot ([8c1634a](https://github.com/FYWinds/Spotifify/commit/8c1634a91b2228c4ff4916e42e621ddc54c91737))
+
 ## [0.1.1](https://github.com/FYWinds/Spotifify/compare/v0.1.0...v0.1.1) (2026-09-05)
 
 

package/README.md

@@ -65,9 +65,9 @@ State lives in `~/.spotifify` (`config.toml`, `state.db`, logs); override with `
 | Command | What it does |
 |---|---|
 | `init [--force\|--upgrade]` | Write the config template; `--upgrade` merges options added in newer versions into your file (values kept, `.bak` written). |
-| `doctor` | Check config, state db, `ffmpeg`/`fpcalc`, token scopes, search-quota deadline. |
+| `doctor` | Check config, state db, `ffmpeg`/`fpcalc`, token scopes, search-quota deadline, and the desktop client's local-files index (exports it never indexed or indexed with another duration — the two causes of grey rows). |
 | `auth spotify` / `auth netease [--cookie …]` | Log in. |
-| `sync [--dry-run] [--prune] [--source netease\|local] [--playlist NAME] [--skip-match]` | Pull → match → export → plan → apply → report. Exit code `3` = re-authenticate. |
+| `sync [--dry-run] [--prune] [--source netease\|local] [--playlist NAME] [--skip-match]` | Pull → match → export → plan → apply → report. `--prune` also removes superseded local entries and exported files no longer needed — never beyond what the run can account for: with `--playlist`/`--source` nothing is unliked that another mirrored playlist wants, exports still referenced from a playlist outside the run are kept, and a run that mirrors no playlist at all prunes nothing. Exit code `3` = re-authenticate. |
 | `review` | Ink TUI: `j/k` move, `1-9`/`Enter` pick a candidate, `/` custom search, `p` paste a Spotify URL/URI, `o`/`O` open candidate/source in the browser, `l` keep as local file, `s` skip, `u` undo, `?` help. |
 | `status` | Match counts, playlist mappings, last run. |
 | `unmatched [--status local\|review\|all] [--tsv]` | Tracks without a Spotify match and the local file that backs them. |

package/README.zh-CN.md

@@ -65,9 +65,9 @@ spotifify review               # 处理低置信度匹配
 | 命令 | 作用 |
 |---|---|
 | `init [--force\|--upgrade]` | 写配置模板；`--upgrade` 把新版本新增的选项合并进现有文件（保留原值，写 `.bak`）。 |
-| `doctor` | 检查配置、状态库、`ffmpeg`/`fpcalc`、token scope、搜索配额截止时间。 |
+| `doctor` | 检查配置、状态库、`ffmpeg`/`fpcalc`、token scope、搜索配额截止时间，以及桌面端的本地文件索引（哪些导出没被索引、哪些时长和我们算的不一致——歌单里灰掉的两种原因）。 |
 | `auth spotify` / `auth netease [--cookie …]` | 登录。 |
-| `sync [--dry-run] [--prune] [--source netease\|local] [--playlist 名称] [--skip-match]` | 拉取 → 匹配 → 导出 → 计划 → 执行 → 报告。退出码 `3` = 需要重新登录。 |
+| `sync [--dry-run] [--prune] [--source netease\|local] [--playlist 名称] [--skip-match]` | 拉取 → 匹配 → 导出 → 计划 → 执行 → 报告。`--prune` 还会删掉被取代的本地条目和不再需要的导出文件——但只在本次能对账的范围内：带 `--playlist`/`--source` 时不会取消其他镜像歌单想要的喜欢，本次计划外的歌单仍引用的导出文件保留，没有任何镜像歌单的运行什么都不删。退出码 `3` = 需要重新登录。 |
 | `review` | Ink TUI：`j/k` 移动，`1-9`/`Enter` 选候选，`/` 自定义搜索，`p` 粘贴 Spotify 链接/URI，`o`/`O` 在浏览器打开候选/来源，`l` 保持为本地文件，`s` 跳过，`u` 撤销，`?` 帮助。 |
 | `status` | 匹配统计、歌单映射、上次运行。 |
 | `unmatched [--status local\|review\|all] [--tsv]` | 没有 Spotify 匹配的歌以及对应的本地文件。 |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spotifify",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "type": "module",
   "description": "Idempotently sync Netease Cloud Music playlists and a local music library (incl. .ncm) to Spotify",
   "keywords": [

package/src/cli.ts

@@ -1,6 +1,7 @@
 #!/usr/bin/env bun
 import { existsSync, mkdirSync, statSync } from "node:fs";
-import { join } from "node:path";
+import { readFile } from "node:fs/promises";
+import { basename, dirname, join } from "node:path";
 import { Command, InvalidArgumentError } from "commander";
 import qrcode from "qrcode-terminal";
 import { CONFIG_FILENAME, CONFIG_TEMPLATE, loadConfig, missingConfigKeys, stateDir, upgradeConfig, withArtistAliases, type Config } from "./config.ts";
@@ -12,6 +13,7 @@ import { NeteaseAuthError, NeteaseClient } from "./sources/netease/client.ts";
 import { SpotifyApi } from "./spotify/api.ts";
 import { AuthExpiredError, loginPkce, type TokenStore } from "./spotify/auth.ts";
 import { SpotifyClient } from "./spotify/client.ts";
+import { compareExports, findLocalFilesIndexes, parseLocalFilesIndex } from "./spotify/localIndex.ts";
 import { SCOPES, type SpotifyTokens } from "./spotify/types.ts";
 import { openDatabase, schemaVersion } from "./state/db.ts";
 import { Repo } from "./state/repo.ts";
@@ -42,7 +44,7 @@ interface Ctx {
 const program = new Command()
   .name("spotifify")
   .description("Sync Netease Cloud Music playlists and a local library to Spotify")
-  .version("0.1.1") // x-release-please-version
+  .version("0.1.3") // x-release-please-version
   .option("--config <path>", "config file (default: <state-dir>/config.toml)")
   .option("--state-dir <dir>", "state directory (default: ~/.spotifify or $SPOTIFIFY_STATE_DIR)")
   .option("--log-file <path>", "append log lines to this file")
@@ -91,6 +93,38 @@ function fail(e: unknown): never {
   process.exit(EXIT_ERROR);
 }
 
+/**
+ * Compare `local_export` with the desktop client's own local-files index. Every grey "can't play"
+ * row traces back to one of: the client never indexed the file, or it indexed it with another
+ * identity (a different duration); both are visible here without touching the network.
+ */
+async function checkClientIndex(repo: Repo, report: (ok: boolean, label: string, detail: string) => void): Promise<void> {
+  const exports = repo.listExports();
+  if (exports.length === 0) return;
+  const indexes = findLocalFilesIndexes();
+  if (indexes.length === 0) {
+    report(true, "client index", "desktop client index not found; skipped");
+    return;
+  }
+  for (const file of indexes) {
+    const written = statSync(file).mtime.toLocaleString();
+    const entries = parseLocalFilesIndex(await readFile(file));
+    const user = basename(dirname(file)).replace(/-user$/, "");
+    if (entries.length === 0) {
+      report(false, "client index", `empty for user ${user} (written ${written}); restart the desktop client or toggle the folder under Settings → Local Files`);
+      continue;
+    }
+    const c = compareExports(entries, exports);
+    const examples = (xs: string[]) => xs.slice(0, 3).join(", ") + (xs.length > 3 ? ", …" : "");
+    if (c.mismatched.length > 0) {
+      report(false, "client index", `${c.mismatched.length} export(s) indexed with another duration: ${examples(c.mismatched.map((m) => `${m.file} (client ${m.client}s, ours ${m.ours}s)`))}`);
+    }
+    if (c.missing.length > 0) {
+      report(false, "client index", `${c.missing.length} export(s) not indexed by the desktop client (user ${user}, written ${written}): ${examples(c.missing)}; restart the client or toggle the folder`);
+    }
+    if (c.mismatched.length === 0 && c.missing.length === 0) report(true, "client index", `${c.matched} export(s) indexed with matching identity (user ${user}, written ${written})`);
+  }
+}
 // ---- init / doctor ----------------------------------------------------------
 
 program
@@ -185,6 +219,7 @@ program
       } else {
         report(true, "auth netease", "disabled");
       }
+      await checkClientIndex(repo, report);
       db.close();
     } catch (e) {
       report(false, "state.db", e instanceof Error ? e.message : String(e));
@@ -242,7 +277,7 @@ program
   .command("sync")
   .description("pull sources, match, and apply the diff to Spotify")
   .option("--dry-run", "print the plan without applying")
-  .option("--prune", "remove tool-added items that left the source (default: report only)")
+  .option("--prune", "remove tool-added items that left the source, superseded local entries, and exported files no longer needed (default: report only)")
   .option("--source <kind>", "only this source: netease | local", (v: string) => {
     if (v !== "netease" && v !== "local") throw new InvalidArgumentError("expected netease or local");
     return v;
@@ -289,10 +324,10 @@ function printSummary(s: SyncSummary): void {
   } else if (s.matched.budgetExhausted) {
     console.log(`  search budget for this run used up (matching.max_searches_per_run); rerun later or raise the budget`);
   }
-  console.log(`plan: create ${s.plan.creates}, add ${s.plan.adds}, move ${s.plan.moves}, prune ${s.plan.prune}, like ${s.plan.likes}, unlike ${s.plan.unlikes}, export ${s.plan.exports}`);
+  console.log(`plan: create ${s.plan.creates}, add ${s.plan.adds}, move ${s.plan.moves}, prune ${s.plan.prune}, like ${s.plan.likes}, unlike ${s.plan.unlikes}, export ${s.plan.exports}, remove export ${s.plan.exportGc}`);
   if (s.apply) {
     console.log(
-      `applied: created ${s.apply.created}, added ${s.apply.added}, moved ${s.apply.moved}, replaced ${s.apply.replaced}, pruned ${s.apply.pruned}, liked ${s.apply.liked}, unliked ${s.apply.unliked}, exported ${s.apply.exported}${s.apply.exportErrors ? ` (${s.apply.exportErrors} export errors)` : ""}`,
+      `applied: created ${s.apply.created}, added ${s.apply.added}, moved ${s.apply.moved}, replaced ${s.apply.replaced}, pruned ${s.apply.pruned}, liked ${s.apply.liked}, unliked ${s.apply.unliked}, exported ${s.apply.exported}${s.apply.exportErrors ? ` (${s.apply.exportErrors} export errors)` : ""}, removed exports ${s.apply.exportsRemoved}`,
     );
   }
   console.log(`match state: ${Object.entries(s.matchCounts).map(([k, v]) => `${k} ${v}`).join(", ")}`);

package/src/match/matcher.ts

@@ -17,6 +17,7 @@ const TRACK_REF = /^(?:spotify:track:|https?:\/\/open\.spotify\.com\/(?:intl-[a-
 /** Dedupes search results by id (and relinked origin id) and scores each one once. */
 class CandidatePool {
   private readonly seen = new Set<string>();
+  private readonly byId = new Map<string, Candidate>();
   private readonly candidates: Candidate[] = [];
 
   constructor(
@@ -37,11 +38,23 @@ class CandidatePool {
       if (scored.parts.artist < minArtist) continue;
       const c = toCandidate(t.id, t, scored);
       this.candidates.push(c);
+      this.byId.set(t.id, c);
+      if (t.linked_from) this.byId.set(t.linked_from.id, c);
       added.push(c);
     }
     return added;
   }
 
+  /** Pooled candidates for these tracks, whichever query admitted them (an identity hit must count even for a track a text query saw first). */
+  known(tracks: SpotifyTrack[]): Candidate[] {
+    const out = new Set<Candidate>();
+    for (const t of tracks) {
+      const c = (t.id !== null ? this.byId.get(t.id) : undefined) ?? (t.linked_from !== undefined ? this.byId.get(t.linked_from.id) : undefined);
+      if (c) out.add(c);
+    }
+    return [...out];
+  }
+
   sorted(): Candidate[] {
     return [...this.candidates].sort((a, b) => b.score - a.score);
   }
@@ -63,19 +76,24 @@ function toCandidate(id: string, t: SpotifyTrack, scored: { score: number; parts
 
 type Hit = { by: "isrc" | "fingerprint"; candidate: Candidate } | { by: "auto" };
 
+/** ISRCs for a local file (Chromaprint → AcoustID → MusicBrainz); replaceable so the decision path can be exercised without `fpcalc`. */
+export type IsrcLookup = (path: string, contentHash: string, cfg: Config["matching"], repo: Repo, now: number) => Promise<string[]>;
+
 export class Matcher {
   private readonly api: SpotifyApi;
   private readonly repo: Repo;
   private readonly cfg: Config;
   private readonly market: string;
   private readonly search: TrackSearch;
+  private readonly isrcLookup: IsrcLookup;
 
-  constructor(deps: { api: SpotifyApi; repo: Repo; cfg: Config; market: string }) {
+  constructor(deps: { api: SpotifyApi; repo: Repo; cfg: Config; market: string; isrcLookup?: IsrcLookup }) {
     this.api = deps.api;
     this.repo = deps.repo;
     this.cfg = deps.cfg;
     this.market = deps.market;
     this.search = new TrackSearch(deps.api, deps.repo, deps.cfg.matching, deps.market);
+    this.isrcLookup = deps.isrcLookup ?? isrcsByFingerprint;
   }
 
   /** Network searches spent by this matcher (cache hits excluded). */
@@ -92,10 +110,11 @@ export class Matcher {
     for (const q of queries) {
       const tracks = await this.search.search(q, now);
       const added = pool.add(tracks, true, q === bareTitle ? BARE_TITLE_MIN_ARTIST : 0);
-      if (added.length === 0) continue;
       if (q.startsWith("isrc:")) {
-        let best = added[0]!;
-        for (const c of added) if (c.score > best.score) best = c;
+        const hits = pool.known(tracks);
+        if (hits.length === 0) continue;
+        let best = hits[0]!;
+        for (const c of hits) if (c.score > best.score) best = c;
         return { by: isrcBy, candidate: best };
       }
       if (added.some((c) => passesAutoGate(c.score, c.parts, m))) return { by: "auto" };
@@ -114,7 +133,7 @@ export class Matcher {
     const bareTitle = track.artists.length > 0 ? queryTitle(track.title) : null;
     let hit = await this.runQueries(pool, this.search.queriesFor(track), bareTitle, "isrc", now);
     if (hit === null && track.file && m.fingerprint) {
-      const isrcs = await isrcsByFingerprint(track.file.path, track.file.contentHash, m, this.repo, now);
+      const isrcs = await this.isrcLookup(track.file.path, track.file.contentHash, m, this.repo, now);
       for (const isrc of isrcs) {
         hit = await this.runQueries(pool, [`isrc:${isrc}`], null, "fingerprint", now);
         if (hit !== null) break;

package/src/sources/local/source.ts

@@ -89,17 +89,26 @@ export class LocalSource implements Source {
 
   private async track(file: ScannedFile): Promise<SourceTrack | null> {
     const cached = this.cache.get(file.path);
-    if (cached?.file !== undefined && cached.file.size === file.size && cached.file.mtimeMs === file.mtimeMs) {
-      const { id: _id, canonicalKey: _key, lastSeenAt: _seen, ...track } = cached;
-      return track;
-    }
+    if (cached?.file !== undefined && cached.file.size === file.size && cached.file.mtimeMs === file.mtimeMs) return stripRow(cached);
     try {
       const contentHash = await hashFile(file.path);
       const meta = await describe(file.path, this.cfg.filename_pattern);
       return { kind: "local", externalId: file.path, ...meta, file: { path: file.path, contentHash, size: file.size, mtimeMs: file.mtimeMs } };
     } catch (e) {
-      log.warn(`skipping unreadable file ${file.path}: ${e instanceof Error ? e.message : String(e)}`);
+      // A file that cannot be read right now (half-downloaded, locked, damaged) is not a file that left the
+      // library: the previous row stands until it can be read again, so the track is never treated as removed.
+      const error = e instanceof Error ? e.message : String(e);
+      if (cached?.file !== undefined) {
+        log.warn(`cannot read ${file.path}; keeping its previous metadata: ${error}`);
+        return stripRow(cached);
+      }
+      log.warn(`skipping unreadable file ${file.path}: ${error}`);
       return null;
     }
   }
 }
+
+function stripRow(row: SourceTrackRow): SourceTrack {
+  const { id: _id, canonicalKey: _key, lastSeenAt: _seen, ...track } = row;
+  return track;
+}

package/src/sources/netease/client.ts

@@ -35,26 +35,26 @@ export class NeteaseAuthError extends Error {
 const LoginStatusBody = z.object({
   data: z.object({ profile: z.object({ userId: z.number(), nickname: z.string().default("") }).nullish() }).optional(),
 });
+// Fields a pull cannot do without (`playlist`, `trackIds`) are required: a shape change must fail the run, not
+// read as "the user has no playlists / the playlist is empty" and delete everything downstream.
 const UserPlaylistBody = z.object({
   more: z.boolean().default(false),
-  playlist: z
-    .array(
-      z.object({
-        id: z.number(),
-        name: z.string(),
-        creator: z.object({ userId: z.number() }).nullish(),
-        userId: z.number().optional(),
-        specialType: z.number().default(0),
-        trackCount: z.number().default(0),
-        updateTime: z.number().default(0),
-        trackUpdateTime: z.number().optional(),
-      }),
-    )
-    .default([]),
+  playlist: z.array(
+    z.object({
+      id: z.number(),
+      name: z.string(),
+      creator: z.object({ userId: z.number() }).nullish(),
+      userId: z.number().optional(),
+      specialType: z.number().default(0),
+      trackCount: z.number().default(0),
+      updateTime: z.number().default(0),
+      trackUpdateTime: z.number().optional(),
+    }),
+  ),
 });
 const PlaylistDetailBody = z.object({
   playlist: z.object({
-    trackIds: z.array(z.object({ id: z.number() })).default([]),
+    trackIds: z.array(z.object({ id: z.number() })),
     updateTime: z.number().default(0),
     trackUpdateTime: z.number().optional(),
   }),

package/src/sources/netease/source.ts

@@ -78,10 +78,17 @@ export class NeteaseSource implements Source {
       }
 
       const tracks: SourceTrack[] = [];
+      const omitted: string[] = [];
       for (const id of ids) {
         const t = known.get(id) ?? fetched.get(id);
         if (t) tracks.push(t);
-        else log.warn("netease song_detail omitted a track", { playlist: summary.name, id });
+        else omitted.push(id);
+      }
+      if (omitted.length > 0) {
+        // Songs the detail endpoint left out were never known, so nothing is lost yet; but the playlist must not be
+        // recorded as pulled at this version, or the cache would serve the short list until the playlist changes.
+        log.warn("netease song_detail omitted tracks; the playlist will be pulled again next run", { playlist: summary.name, omitted: omitted.length, ids: omitted.slice(0, 5) });
+        playlist.sourceUpdatedAt = undefined;
       }
       log.info("netease playlist pulled", { name: summary.name, tracks: tracks.length, fetched: fetched.size, cached: known.size });
       playlists.push({ playlist, tracks });

package/src/spotify/api.ts

@@ -6,8 +6,8 @@ import type { SpotifyPlaylist, SpotifyPlaylistItem, SpotifyTrack } from "./types
 // `/me/library?uris=`; the legacy `/tracks` and `/me/tracks/contains` paths answer 403 for newer apps.
 const ITEM_FIELDS = "next,total,items(added_at,is_local,item(id,uri,name,is_local,duration_ms,artists(id,name),album(id,name)))";
 
-/** Playlist item batch limit for add/remove/replace. */
-const ITEMS_BATCH = 100;
+/** Playlist item batch limit for add/remove; also the most a single replace can hold. */
+export const ITEMS_BATCH = 100;
 /** `/me/library` batch limit (probed: 41+ uris → 400 "Too many uris requested"). */
 const LIBRARY_BATCH = 40;
 
@@ -70,6 +70,12 @@ export class SpotifyApi {
     return this.client.paginate<SpotifyPlaylistItem>(`/v1/playlists/${id}/items`, { limit: 50, fields: ITEM_FIELDS });
   }
 
+  /** Current snapshot id only (used to bracket an items listing). */
+  async getPlaylistSnapshot(id: string): Promise<string> {
+    const res = await this.client.request<{ snapshot_id: string }>("GET", `/v1/playlists/${id}`, { query: { fields: "snapshot_id" } });
+    return res.snapshot_id;
+  }
+
   /** ≤100 per request; `position` advances by batch size so the whole run lands contiguously. Returns the last snapshot_id. */
   async addPlaylistItems(id: string, uris: string[], position?: number): Promise<string> {
     let snapshot = "";
@@ -86,8 +92,9 @@ export class SpotifyApi {
 
   /**
    * ≤100 per request. Catalog tracks are removed by URI; local files must be removed by position only
-   * (`/items` answers 400 "Invalid base62 id" for a `spotify:local:` URI). Positions are removed highest
-   * first with chained snapshot ids, so earlier indexes never shift underneath later batches.
+   * (`/items` answers 400 "Invalid base62 id" for a `spotify:local:` URI). Every position batch names the
+   * snapshot the positions were read from: Spotify resolves them against that snapshot, so batches never
+   * see each other's shifts (or a concurrent edit). Positions are still sent highest first.
    */
   async removePlaylistItems(id: string, items: Array<{ uri: string; positions?: number[] }>, snapshotId: string): Promise<string> {
     let snapshot = snapshotId;
@@ -95,7 +102,7 @@ export class SpotifyApi {
     const uris = items.filter((x) => x.positions === undefined).map((x) => ({ uri: x.uri }));
     for (const batch of chunk(positions, ITEMS_BATCH)) {
       const res = await this.client.request<{ snapshot_id: string }>("DELETE", `/v1/playlists/${id}/items`, {
-        body: { positions: batch, snapshot_id: snapshot },
+        body: { positions: batch, snapshot_id: snapshotId },
       });
       snapshot = res.snapshot_id;
     }
@@ -115,13 +122,11 @@ export class SpotifyApi {
     return res.snapshot_id;
   }
 
-  /** PUT the first ≤100 (which also clears the playlist), then append the rest. */
+  /** One atomic PUT (≤100 items: a longer list would need a follow-up POST that can fail half-way and lose the tail). */
   async replacePlaylistItems(id: string, uris: string[]): Promise<string> {
-    const res = await this.client.request<{ snapshot_id: string }>("PUT", `/v1/playlists/${id}/items`, {
-      body: { uris: uris.slice(0, ITEMS_BATCH) },
-    });
-    const rest = uris.slice(ITEMS_BATCH);
-    return rest.length === 0 ? res.snapshot_id : this.addPlaylistItems(id, rest);
+    if (uris.length > ITEMS_BATCH) throw new Error(`replacePlaylistItems: ${uris.length} items exceed the single-request limit of ${ITEMS_BATCH}`);
+    const res = await this.client.request<{ snapshot_id: string }>("PUT", `/v1/playlists/${id}/items`, { body: { uris } });
+    return res.snapshot_id;
   }
 
   /** ≤50 per request; result aligns with `ids` order. */

package/src/spotify/auth.ts

@@ -48,7 +48,8 @@ async function postToken(form: Record<string, string>, previous?: SpotifyTokens)
     access_token: body.access_token,
     refresh_token: refresh,
     expires_at: Date.now() + body.expires_in * 1000 - EXPIRY_MARGIN_MS,
-    scope: body.scope ?? previous?.scope ?? SCOPES.join(" "),
+    // A refresh response may omit `scope` (or an older store may hold ""): the grant did not shrink, so keep what was known.
+    scope: body.scope || previous?.scope || SCOPES.join(" "),
   };
 }
 
@@ -110,12 +111,7 @@ export async function loginPkce(opts: { clientId: string; port: number; store: T
   }
 }
 
-/** PKCE refresh responses may omit `refresh_token`; the previous one is kept in that case. */
-export async function refreshTokens(clientId: string, refreshToken: string): Promise<SpotifyTokens> {
-  return postToken({ client_id: clientId, grant_type: "refresh_token", refresh_token: refreshToken }, {
-    access_token: "",
-    refresh_token: refreshToken,
-    expires_at: 0,
-    scope: "",
-  });
+/** PKCE refresh responses may omit `refresh_token` and `scope`; the previous values are kept in that case. */
+export async function refreshTokens(clientId: string, previous: SpotifyTokens): Promise<SpotifyTokens> {
+  return postToken({ client_id: clientId, grant_type: "refresh_token", refresh_token: previous.refresh_token }, previous);
 }

package/src/spotify/client.ts

@@ -77,7 +77,9 @@ export class SpotifyClient {
           log.warn(`Spotify rate limited; waiting ${secs}s`, { method, path: url.pathname });
           throw new RetryableError(`429 on ${method} ${url.pathname}`, waitMs);
         }
-        if (res.status >= 500) throw new RetryableError(`${res.status} on ${method} ${url.pathname}`);
+        // A 5xx on a write may arrive after Spotify applied it (a re-sent POST would add twice, a re-sent
+        // reorder move twice), so only reads are retried; a failed write ends the run and the next one re-plans.
+        if (res.status >= 500 && method === "GET") throw new RetryableError(`${res.status} on ${method} ${url.pathname}`);
         throw new SpotifyHttpError(res.status, text, method, url.pathname);
       },
       { attempts: ATTEMPTS },
@@ -107,7 +109,7 @@ export class SpotifyClient {
     if (this.refreshing) return this.refreshing;
     const tokens = this.store.load();
     if (tokens === null) throw new AuthExpiredError();
-    this.refreshing = refreshTokens(this.clientId, tokens.refresh_token)
+    this.refreshing = refreshTokens(this.clientId, tokens)
       .then((fresh) => {
         this.store.save(fresh);
         return fresh;

package/src/spotify/localIndex.ts

@@ -0,0 +1,143 @@
+/**
+ * Reader for the desktop client's local-file index (`local-files.bnk`), the source of truth for which
+ * files it knows and which identity (tags + its own duration) it computed for each. `spotifify doctor`
+ * compares it with `local_export` so a broken index (half-written file, dropped entry, duration
+ * mismatch) is diagnosed instead of showing up as grey playlist rows.
+ *
+ * The format is undocumented ("SPCO" container, protobuf-like records); this parser only walks the
+ * repeating record shape observed in the wild and gives up quietly when it does not match:
+ *   09 <len> title  09 <len> artist  09 <len> album  10 <varint seconds> … 2c 01 <len> path … 08 01 78 78 04
+ * The file is written when the client flushes (shutdown, rescan), so it may lag the live index.
+ */
+import { existsSync, readdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, join } from "node:path";
+import type { LocalExportRow } from "../state/repo.ts";
+import { parseLocalUri } from "./localUri.ts";
+
+export interface LocalIndexEntry {
+  title: string;
+  artist: string;
+  album: string;
+  durationSec: number;
+  path: string;
+}
+
+const RECORD_SEPARATOR = [0x08, 0x01, 0x78, 0x78, 0x04];
+
+/** Every `Users/<id>-user/local-files.bnk` of every known client install location. */
+export function findLocalFilesIndexes(): string[] {
+  const home = homedir();
+  const local = process.env.LOCALAPPDATA ?? join(home, "AppData", "Local");
+  const roots =
+    process.platform === "win32"
+      ? [join(local, "Packages", "SpotifyAB.SpotifyMusic_zpdnekdrzrea0", "LocalState", "Spotify", "Users"), join(local, "Spotify", "Users")]
+      : process.platform === "darwin"
+        ? [join(home, "Library", "Application Support", "Spotify", "Users")]
+        : [join(home, ".config", "spotify", "Users"), join(home, ".var", "app", "com.spotify.Client", "config", "spotify", "Users")];
+  const out: string[] = [];
+  for (const root of roots) {
+    if (!existsSync(root)) continue;
+    for (const user of readdirSync(root)) {
+      const file = join(root, user, "local-files.bnk");
+      if (user.endsWith("-user") && existsSync(file)) out.push(file);
+    }
+  }
+  return out;
+}
+
+function readVarint(b: Uint8Array, at: number): [value: number, next: number] | null {
+  let value = 0;
+  let shift = 0;
+  for (let i = at; i < b.length && shift <= 35; i++, shift += 7) {
+    const c = b[i]!;
+    value += (c & 0x7f) * 2 ** shift;
+    if (c < 0x80) return [value, i + 1];
+  }
+  return null;
+}
+
+const decoder = new TextDecoder("utf-8", { fatal: true });
+/** paths occasionally carry stray bytes in the file (seen once in 81 records); identity fields never did */
+const lenientDecoder = new TextDecoder("utf-8");
+
+/** `09 <varint len> <utf-8>` */
+function readString(b: Uint8Array, at: number): [value: string, next: number] | null {
+  if (b[at] !== 0x09) return null;
+  const len = readVarint(b, at + 1);
+  if (!len) return null;
+  const [n, start] = len;
+  if (start + n > b.length) return null;
+  try {
+    return [decoder.decode(b.subarray(start, start + n)), start + n];
+  } catch {
+    return null;
+  }
+}
+
+function indexOfSeq(b: Uint8Array, seq: readonly number[], from: number): number {
+  outer: for (let i = from; i + seq.length <= b.length; i++) {
+    for (let j = 0; j < seq.length; j++) if (b[i + j] !== seq[j]) continue outer;
+    return i;
+  }
+  return -1;
+}
+
+export function parseLocalFilesIndex(b: Uint8Array): LocalIndexEntry[] {
+  const out: LocalIndexEntry[] = [];
+  let at = indexOfSeq(b, RECORD_SEPARATOR, 0);
+  while (at !== -1) {
+    const next = indexOfSeq(b, RECORD_SEPARATOR, at + RECORD_SEPARATOR.length);
+    const end = next === -1 ? b.length : next;
+    const entry = parseRecord(b, at + RECORD_SEPARATOR.length, end);
+    if (entry) out.push(entry);
+    at = next;
+  }
+  return out;
+}
+
+function parseRecord(b: Uint8Array, at: number, end: number): LocalIndexEntry | null {
+  const title = readString(b, at);
+  if (!title) return null;
+  const artist = readString(b, title[1]);
+  if (!artist) return null;
+  const album = readString(b, artist[1]);
+  if (!album) return null;
+  if (b[album[1]] !== 0x10) return null;
+  const duration = readVarint(b, album[1] + 1);
+  if (!duration) return null;
+  // the path follows further down the record: 2c 01 <varint len> <utf-8>
+  const p = indexOfSeq(b, [0x2c, 0x01], duration[1]);
+  if (p === -1 || p >= end) return null;
+  const len = readVarint(b, p + 2);
+  if (!len) return null;
+  const [n, start] = len;
+  if (n === 0 || start + n > end) return null;
+  return { title: title[0], artist: artist[0], album: album[0], durationSec: duration[0], path: lenientDecoder.decode(b.subarray(start, start + n)) };
+}
+
+export interface IndexComparison {
+  /** exports the client has not indexed at all (file names) */
+  missing: string[];
+  /** exports the client indexed with a different duration: the pasted uri will never link */
+  mismatched: Array<{ file: string; ours: number; client: number }>;
+  /** exports found with the identical identity */
+  matched: number;
+}
+
+/** Compare `local_export` identities with the client's index, keyed by tags (the client's own key); paths are not compared. */
+export function compareExports(entries: readonly LocalIndexEntry[], exports: readonly LocalExportRow[]): IndexComparison {
+  const key = (title: string, artist: string, album: string) => `${title}\u0000${artist}\u0000${album}`;
+  const byIdentity = new Map(entries.map((e) => [key(e.title, e.artist, e.album), e]));
+  const out: IndexComparison = { missing: [], mismatched: [], matched: 0 };
+  for (const e of exports) {
+    const p = parseLocalUri(e.localUri);
+    if (!p) continue;
+    const file = basename(e.exportPath);
+    const hit = byIdentity.get(key(p.title, p.artist, p.album));
+    if (!hit) out.missing.push(file);
+    else if (hit.durationSec !== p.durationSec) out.mismatched.push({ file, ours: p.durationSec ?? -1, client: hit.durationSec });
+    else out.matched++;
+  }
+  return out;
+}

package/src/state/repo.ts

@@ -386,6 +386,29 @@ export class Repo {
     })();
   }
 
+  /** `spotify:local:` uris recorded as present in a managed playlist → ids of the playlists referencing each. */
+  localUriReferences(): Map<string, string[]> {
+    const out = new Map<string, string[]>();
+    for (const r of this.db.query<{ uri: string; spotify_playlist_id: string }, []>("SELECT uri, spotify_playlist_id FROM managed_item WHERE uri LIKE 'spotify:local:%'").all()) {
+      let ids = out.get(r.uri);
+      if (!ids) {
+        ids = [];
+        out.set(r.uri, ids);
+      }
+      ids.push(r.spotify_playlist_id);
+    }
+    return out;
+  }
+
+  /** Record exactly which of our local entries a playlist holds after a sync (rows for entries the user removed by hand go away). */
+  replaceManagedLocal(spotifyPlaylistId: string, uris: string[], now: number): void {
+    const q = this.db.query("INSERT OR IGNORE INTO managed_item (spotify_playlist_id, uri, added_at) VALUES (?, ?, ?)");
+    this.db.transaction(() => {
+      this.db.run("DELETE FROM managed_item WHERE spotify_playlist_id = ? AND uri LIKE 'spotify:local:%'", [spotifyPlaylistId]);
+      for (const u of uris) q.run(spotifyPlaylistId, u, now);
+    })();
+  }
+
   likedIds(): Set<string> {
     return new Set(this.db.query<{ spotify_id: string }, []>("SELECT spotify_id FROM liked").all().map((r) => r.spotify_id));
   }
@@ -423,6 +446,10 @@ export class Repo {
     );
   }
 
+  deleteExport(key: string): void {
+    this.db.run("DELETE FROM local_export WHERE canonical_key = ?", [key]);
+  }
+
   // ---- caches -----------------------------------------------------------
 
   cacheGet<T>(key: string, now: number, ttlMs: number): T | null {

package/src/sync/apply.ts

@@ -3,7 +3,7 @@
  * remote operation so a crash mid-way leaves a consistent (re-plannable) state. See DESIGN.md §6.
  */
 import type { Config } from "../config.ts";
-import type { SpotifyApi } from "../spotify/api.ts";
+import { ITEMS_BATCH, type SpotifyApi } from "../spotify/api.ts";
 import { MANAGED_DESCRIPTION } from "../spotify/types.ts";
 import type { Repo } from "../state/repo.ts";
 import { chunk } from "../util/retry.ts";
@@ -30,15 +30,24 @@ export interface ApplySummary {
   unliked: number;
   exported: number;
   exportErrors: number;
+  /** exports garbage-collected after the playlist prune (--prune only) */
+  exportsRemoved: number;
 }
 
 /** Replace the whole playlist only when it saves real calls: more than this many moves AND more than a third of the list. */
 const REPLACE_MIN_MOVES = 5;
 const REPLACE_MOVE_RATIO = 1 / 3;
 
+export class PlaylistDriftError extends Error {
+  constructor(name: string) {
+    super(`playlist "${name}" changed since it was read; nothing was applied to it — rerun \`spotifify sync\``);
+    this.name = "PlaylistDriftError";
+  }
+}
+
 /** Applies playlist and library changes. Exports run separately (`applyExports`) before planning. */
 export async function applyPlan(plan: Plan, deps: ApplyDeps): Promise<ApplySummary> {
-  const s: ApplySummary = { created: 0, renamed: 0, added: 0, pruned: 0, moved: 0, replaced: 0, liked: 0, unliked: 0, exported: 0, exportErrors: 0 };
+  const s: ApplySummary = { created: 0, renamed: 0, added: 0, pruned: 0, moved: 0, replaced: 0, liked: 0, unliked: 0, exported: 0, exportErrors: 0, exportsRemoved: 0 };
 
   for (const p of plan.playlists) await applyPlaylist(p, deps, s);
 
@@ -91,6 +100,14 @@ async function applyPlaylist(p: PlaylistPlan, deps: ApplyDeps, s: ApplySummary):
   }
   if (spotifyId === null) throw new Error(`playlist plan for ${p.sourceName} has neither spotifyId nor create`);
 
+  // Moves and the replace order describe the playlist as it was listed and carry no snapshot Spotify could
+  // validate them against (unlike position removals), so an edit since the listing would reorder the wrong
+  // rows: such a playlist is checked before anything is written to it.
+  const willPrune = deps.prune && p.prune.length > 0;
+  if (p.snapshotId !== null && p.moves.length > 0 && (await api.getPlaylistSnapshot(spotifyId)) !== p.snapshotId) {
+    throw new PlaylistDriftError(name);
+  }
+
   if (p.rename) {
     await api.renamePlaylist(spotifyId, p.rename.to);
     name = p.rename.to;
@@ -98,8 +115,10 @@ async function applyPlaylist(p: PlaylistPlan, deps: ApplyDeps, s: ApplySummary):
     log.info("renamed playlist", p.rename);
   }
 
-  // Replace-all fast path: only when no local items exist and moving would cost noticeably more calls.
-  const useReplace = p.replaceAllowed && p.moves.length > REPLACE_MIN_MOVES && p.moves.length > p.targetOrder.length * REPLACE_MOVE_RATIO;
+  // Replace-all fast path: one atomic PUT, only for lists it can hold whole, with no local items, and when
+  // moving would cost noticeably more calls.
+  const useReplace =
+    p.replaceAllowed && p.targetOrder.length <= ITEMS_BATCH && p.moves.length > REPLACE_MIN_MOVES && p.moves.length > p.targetOrder.length * REPLACE_MOVE_RATIO;
   let snapshot: string | null = null;
 
   if (useReplace) {
@@ -112,21 +131,24 @@ async function applyPlaylist(p: PlaylistPlan, deps: ApplyDeps, s: ApplySummary):
     s.replaced++;
     log.info("replaced playlist contents", { name, items: p.targetOrder.length });
   } else {
-    for (const uris of chunk(p.adds, 100)) {
+    for (const uris of chunk(p.adds, ITEMS_BATCH)) {
       snapshot = await api.addPlaylistItems(spotifyId, uris);
       repo.addManaged(spotifyId, uris, now);
       s.added += uris.length;
     }
-    if (deps.prune && p.prune.length > 0) {
-      snapshot ??= (await api.getPlaylist(spotifyId))?.snapshot_id ?? null;
-      if (snapshot === null) throw new Error(`playlist ${spotifyId} vanished during apply`);
+    if (willPrune) {
+      // Positions come from the planning-time listing, so they are validated against that snapshot
+      // (Spotify checks them against the snapshot given, not the current one). Adds only append.
+      const base = p.snapshotId ?? snapshot ?? (await api.getPlaylist(spotifyId))?.snapshot_id ?? null;
+      if (base === null) throw new Error(`playlist ${spotifyId} vanished during apply`);
       const items = p.prune.map((x) => (x.uri.startsWith("spotify:local:") ? { uri: x.uri, positions: x.positions } : { uri: x.uri }));
-      snapshot = await api.removePlaylistItems(spotifyId, items, snapshot);
+      snapshot = await api.removePlaylistItems(spotifyId, items, base);
       repo.removeManaged(spotifyId, p.prune.map((x) => x.uri));
       s.pruned += p.prune.length;
     }
     if (p.moves.length > 0) {
-      snapshot ??= (await api.getPlaylist(spotifyId))?.snapshot_id ?? null;
+      // Moves are computed on the post-add/post-prune order, so they chain from the latest write.
+      snapshot ??= p.snapshotId ?? (await api.getPlaylist(spotifyId))?.snapshot_id ?? null;
       if (snapshot === null) throw new Error(`playlist ${spotifyId} vanished during apply`);
       for (const m of p.moves) {
         snapshot = await api.reorderPlaylistItems(spotifyId, m.rangeStart, m.insertBefore, snapshot);
@@ -134,6 +156,11 @@ async function applyPlaylist(p: PlaylistPlan, deps: ApplyDeps, s: ApplySummary):
       }
     }
   }
+  // Local entries present after this run reference their export from this playlist; an export is only
+  // garbage-collected once no playlist references it any more (see planExportGc). Without --prune the
+  // stale ones are still there.
+  const localPresent = deps.prune ? p.linked : [...p.linked, ...p.prune.map((x) => x.uri).filter((u) => u.startsWith("spotify:local:"))];
+  repo.replaceManagedLocal(spotifyId, localPresent, now);
 
   if (p.adds.length > 0 || p.moves.length > 0 || p.prune.length > 0) {
     log.info("synced playlist", { name, added: p.adds.length, pruned: deps.prune ? p.prune.length : 0, moves: p.moves.length, awaiting: p.awaiting.length });

package/src/sync/export.ts

@@ -8,7 +8,7 @@ import { tmpdir } from "node:os";
 import { extname, join } from "node:path";
 import type { Config } from "../config.ts";
 import { decryptNcm } from "../sources/local/ncm.ts";
-import type { SourceTrackRow } from "../state/repo.ts";
+import type { LocalExportRow, Repo, SourceTrackRow } from "../state/repo.ts";
 import { buildLocalUri } from "../spotify/localUri.ts";
 import { probeMp3, probeMp4DurationSec } from "./duration.ts";
 import { log } from "../util/log.ts";
@@ -93,26 +93,47 @@ export async function exportTrack(plan: ExportPlan, track: SourceTrackRow, cfg:
  * that fails with EPERM/EBUSY while the client has it open (playing), which clears within seconds.
  */
 async function placeExport(partPath: string, exportPath: string): Promise<void> {
+  await removeFile(exportPath);
+  try {
+    await link(partPath, exportPath);
+  } catch (e) {
+    const code = (e as NodeJS.ErrnoException).code;
+    if (code !== "EXDEV" && code !== "EPERM" && code !== "ENOSYS" && code !== "ENOTSUP") throw e;
+    log.warn("hard link unavailable, renaming instead; the desktop client will only index the file after a restart", { path: exportPath });
+    await rename(partPath, exportPath);
+  }
+}
+
+/** Delete with retries: the desktop client holds an exported file open while it plays it (EPERM/EBUSY on Windows). */
+async function removeFile(path: string): Promise<void> {
   await withRetry(
     async () => {
       try {
-        await rm(exportPath, { force: true });
+        await rm(path, { force: true });
       } catch (e) {
         const code = (e as NodeJS.ErrnoException).code;
-        if (code === "EPERM" || code === "EBUSY") throw new RetryableError(`${code} replacing ${exportPath}`);
+        if (code === "EPERM" || code === "EBUSY") throw new RetryableError(`${code} removing ${path}`);
         throw e;
       }
     },
     { attempts: 6, baseMs: 500 },
   );
-  try {
-    await link(partPath, exportPath);
-  } catch (e) {
-    const code = (e as NodeJS.ErrnoException).code;
-    if (code !== "EXDEV" && code !== "EPERM" && code !== "ENOSYS" && code !== "ENOTSUP") throw e;
-    log.warn("hard link unavailable, renaming instead; the desktop client will only index the file after a restart", { path: exportPath });
-    await rename(partPath, exportPath);
+}
+
+/** Garbage-collect exports (file + record). A file that cannot be deleted keeps its record so the next run retries. Returns the number removed. */
+export async function removeExports(rows: readonly LocalExportRow[], repo: Repo): Promise<number> {
+  let removed = 0;
+  for (const e of rows) {
+    try {
+      await removeFile(e.exportPath);
+      repo.deleteExport(e.canonicalKey);
+      removed++;
+      log.info("removed export", { path: e.exportPath });
+    } catch (err) {
+      log.error("export removal failed", { path: e.exportPath, error: err instanceof Error ? err.message : String(err) });
+    }
   }
+  return removed;
 }
 
 /** null: unparsable, or a VBR mp3 whose client duration is not predictable. */

package/src/sync/plan.ts

@@ -25,6 +25,8 @@ export interface PlaylistPlan {
   sourceName: string;
   /** null when the playlist must be created first */
   spotifyId: string | null;
+  /** snapshot the remote listing (and therefore `prune[].positions`) belongs to; null when created */
+  snapshotId: string | null;
   create: { name: string } | null;
   rename: { from: string; to: string } | null;
   /** spotify:track URIs to POST, in desired order */
@@ -35,11 +37,13 @@ export interface PlaylistPlan {
   prune: Array<{ uri: string; positions: number[] }>;
   /** remote items not managed by this tool; never removed, kept at the tail */
   foreign: string[];
+  /** owned local entries that resolve to a desired export: the user's paste landed, so the export is referenced from this playlist */
+  linked: string[];
   /** minimal move sequence to reach desired order (after adds, and prune when enabled) */
   moves: Move[];
   /** full target order (after adds/prune) — used by the replace-all fast path */
   targetOrder: string[];
-  /** when true, apply may replace the whole playlist instead of moving (no local items involved) */
+  /** when true, apply may replace the whole playlist instead of moving (no local or unresolved items involved) */
   replaceAllowed: boolean;
 }
 
@@ -62,18 +66,22 @@ export interface Plan {
   playlists: PlaylistPlan[];
   likes: LikePlan;
   exports: ExportPlan[];
+  /** export records (and files) no longer needed; removed only with --prune, after the playlist prune */
+  exportGc: LocalExportRow[];
   /** canonical keys needing human review */
   reviewPending: number;
 }
 
 export interface RemoteItem {
+  /** empty when Spotify returned the entry without an item (unresolvable): it keeps its position but is never touched */
   uri: string;
   isLocal: boolean;
   /**
-   * A local entry that names one of our exports but with an identity the client will never resolve
-   * (different duration segment, tags from an earlier export). Removed with --prune so a correct paste can replace it.
+   * A local entry that names one of our exports — exactly, or with an identity the client will never
+   * resolve (different duration segment, tags from an earlier export). Ours to remove with --prune
+   * when it is no longer desired (superseded by a Spotify match, gone from the source, wrong identity).
    */
-  stale: boolean;
+  owned: boolean;
 }
 
 export interface PlaylistPlanInput {
@@ -82,6 +90,8 @@ export interface PlaylistPlanInput {
   targetName: string;
   /** existing remote playlist (already verified to exist), or null */
   spotify: { id: string; name: string } | null;
+  /** snapshot id the `remote` listing was taken at (null when `spotify` is null) */
+  snapshotId: string | null;
   /** ordered, deduped by uri */
   desired: DesiredItem[];
   /** current remote order; local uris already canonicalized via `resolveRemoteLocalUri` */
@@ -96,27 +106,27 @@ const LEGACY_TITLE_SUFFIX = / \(local\)$/;
 
 export interface ResolvedRemoteLocal {
   uri: string;
-  stale: boolean;
+  owned: boolean;
 }
 
 /**
  * Map a remote local-file uri onto our export identities. Same artist/album/title/duration as an export
  * → the export's `local_uri`. Same artist/album/title but a different identity (wrong or missing
- * duration segment, legacy title suffix) → stale. Anything else is left untouched (a foreign local file).
+ * duration segment, legacy title suffix) → the verbatim uri (removal by position needs it exactly).
+ * Both are `owned`. Anything else is left untouched (a foreign local file).
  */
 export function resolveRemoteLocalUri(remoteUri: string, exports: readonly LocalExportRow[]): ResolvedRemoteLocal {
   const parts = parseLocalUri(remoteUri);
-  if (!parts) return { uri: remoteUri, stale: false };
+  if (!parts) return { uri: remoteUri, owned: false };
   const fold = (s: string) => s.replace(LEGACY_TITLE_SUFFIX, "").trim().toLowerCase();
   for (const e of exports) {
     const p = parseLocalUri(e.localUri);
     if (!p) continue;
     if (fold(p.artist) !== fold(parts.artist) || fold(p.album) !== fold(parts.album) || fold(p.title) !== fold(parts.title)) continue;
     const exact = parts.durationSec === p.durationSec && parts.title === p.title;
-    // stale entries keep the API's exact uri: removal of local items needs it verbatim alongside positions
-    return exact ? { uri: e.localUri, stale: false } : { uri: remoteUri, stale: true };
+    return { uri: exact ? e.localUri : remoteUri, owned: true };
   }
-  return { uri: buildLocalUri(parts), stale: false };
+  return { uri: buildLocalUri(parts), owned: false };
 }
 
 export function computePlaylistPlan(input: PlaylistPlanInput): PlaylistPlan {
@@ -128,12 +138,14 @@ export function computePlaylistPlan(input: PlaylistPlanInput): PlaylistPlan {
       sourcePlaylistId: input.sourcePlaylistId,
       sourceName: input.sourceName,
       spotifyId: null,
+      snapshotId: null,
       create: { name: input.targetName },
       rename: null,
       adds: desired.filter((d) => d.kind === "spotify").map((d) => d.uri),
       awaiting: desired.filter((d) => d.kind === "local"),
       prune: [],
       foreign: [],
+      linked: [],
       moves: [],
       targetOrder: desired.filter((d) => d.kind === "spotify").map((d) => d.uri),
       replaceAllowed: false,
@@ -143,13 +155,19 @@ export function computePlaylistPlan(input: PlaylistPlanInput): PlaylistPlan {
   const remoteSet = new Set(remote.map((r) => r.uri));
   const adds = desired.filter((d) => d.kind === "spotify" && !remoteSet.has(d.uri)).map((d) => d.uri);
   const awaiting = desired.filter((d) => d.kind === "local" && !remoteSet.has(d.uri));
+  const linked = desired.filter((d) => d.kind === "local" && remoteSet.has(d.uri)).map((d) => d.uri);
 
   const prune: PlaylistPlan["prune"] = [];
   const pruneByUri = new Map<string, number[]>();
   const foreign: string[] = [];
+  let unresolved = false;
   remote.forEach((r, i) => {
+    if (r.uri === "") {
+      unresolved = true;
+      return;
+    }
     if (desiredSet.has(r.uri)) return;
-    if (managed.has(r.uri) || r.stale) {
+    if (managed.has(r.uri) || r.owned) {
       let positions = pruneByUri.get(r.uri);
       if (!positions) {
         positions = [];
@@ -192,14 +210,16 @@ export function computePlaylistPlan(input: PlaylistPlanInput): PlaylistPlan {
     sourcePlaylistId: input.sourcePlaylistId,
     sourceName: input.sourceName,
     spotifyId: input.spotify.id,
+    snapshotId: input.snapshotId,
     create: null,
     rename: input.spotify.name === input.targetName ? null : { from: input.spotify.name, to: input.targetName },
     adds,
     awaiting,
     prune,
     foreign,
+    linked,
     moves,
     targetOrder,
-    replaceAllowed: !anyLocal,
+    replaceAllowed: !anyLocal && !unresolved,
   };
 }

package/src/sync/run.ts

@@ -12,13 +12,14 @@ import { NeteaseSource } from "../sources/netease/source.ts";
 import type { SourceKind, SourceTrack } from "../sources/types.ts";
 import type { SpotifyApi } from "../spotify/api.ts";
 import { SpotifyHttpError, SpotifyRateLimitedError } from "../spotify/client.ts";
-import { MANAGED_DESCRIPTION } from "../spotify/types.ts";
+import { MANAGED_DESCRIPTION, type SpotifyPlaylistItem } from "../spotify/types.ts";
 import { parseLocalUri } from "../spotify/localUri.ts";
 import type { LocalExportRow, Repo, SourcePlaylistRow } from "../state/repo.ts";
-import { sanitizeFilename } from "../util/fs.ts";
+import { MAX_FILENAME, sanitizeFilename } from "../util/fs.ts";
 import { log } from "../util/log.ts";
 import { mapLimit } from "../util/retry.ts";
 import { applyExports, applyPlan, type ApplySummary } from "./apply.ts";
+import { removeExports } from "./export.ts";
 import { computePlaylistPlan, resolveRemoteLocalUri, type DesiredItem, type ExportPlan, type Plan, type PlaylistPlan, type RemoteItem } from "./plan.ts";
 
 export interface SyncOptions {
@@ -58,7 +59,7 @@ export interface MatchPhaseSummary {
 export interface SyncSummary {
   pulled: Record<SourceKind, { playlists: number; tracks: number }>;
   matched: MatchPhaseSummary;
-  plan: { creates: number; adds: number; prune: number; moves: number; likes: number; unlikes: number; exports: number; reviewPending: number };
+  plan: { creates: number; adds: number; prune: number; moves: number; likes: number; unlikes: number; exports: number; exportGc: number; reviewPending: number };
   apply: ApplySummary | null;
   awaiting: AwaitingEntry[];
   matchCounts: Record<string, number>;
@@ -92,6 +93,12 @@ export async function runSync(deps: SyncDeps, opts: SyncOptions): Promise<SyncRe
       apply.exported = exported.exported;
       apply.exportErrors = exported.errors;
     }
+    // After apply: the playlist entries pointing at these files were pruned above, so the files can go —
+    // unless some playlist outside this plan still holds an entry for them.
+    if (apply && opts.prune) {
+      const referenced = repo.localUriReferences();
+      apply.exportsRemoved = await removeExports(plan.exportGc.filter((e) => !referenced.has(e.localUri)), repo);
+    }
     const summary: SyncSummary = {
       pulled,
       matched,
@@ -103,6 +110,7 @@ export async function runSync(deps: SyncDeps, opts: SyncOptions): Promise<SyncRe
         likes: plan.likes.add.length,
         unlikes: plan.likes.prune.length,
         exports: plan.exports.length,
+        exportGc: plan.exportGc.length,
         reviewPending: plan.reviewPending,
       },
       apply,
@@ -130,6 +138,27 @@ export function planExportsOnly(repo: Repo, cfg: Config, opts: Pick<SyncOptions,
   return planExports(repo, repo.listMatches("local").map((m) => m.canonicalKey).filter((k) => keys.has(k)), repo.listExports(), force);
 }
 
+/**
+ * Exported files no longer needed: the track left every mirrored playlist, or it has a Spotify match
+ * now. Only meaningful for a full run — with `--playlist`/`--source` the other playlists' exports
+ * would look unneeded — and never when nothing is mirrored (a config slip must not delete everything).
+ * An export whose entry sits in a playlist outside `planned` (retired from mirroring, or filtered out)
+ * is kept: only the playlists in this plan prune their entries in the same run.
+ */
+export function planExportGc(repo: Repo, cfg: Config, opts: Pick<SyncOptions, "source" | "playlist">, planned: ReadonlySet<string>): LocalExportRow[] {
+  if (opts.source || opts.playlist) return [];
+  if (selectedSourcePlaylists(repo, cfg, {}).length === 0) return [];
+  const needed = selectedKeys(repo, cfg, {});
+  // `review` keeps its export: a candidate that still needs a human must not undo a paste (see desiredItems)
+  const keep = new Set([...repo.listMatches("local"), ...repo.listMatches("review")].map((m) => m.canonicalKey));
+  const referenced = repo.localUriReferences();
+  return repo.listExports().filter((e) => {
+    if (needed.has(e.canonicalKey) && keep.has(e.canonicalKey)) return false;
+    const refs = referenced.get(e.localUri);
+    return refs === undefined || refs.every((id) => planned.has(id));
+  });
+}
+
 // ---- pull -------------------------------------------------------------------
 
 async function pull(deps: SyncDeps, opts: SyncOptions, now: number): Promise<SyncSummary["pulled"]> {
@@ -244,45 +273,34 @@ export async function buildPlan(deps: SyncDeps, opts: Pick<SyncOptions, "prune"
   const me = await api.me();
   const remotePlaylists = (await api.listMyPlaylists()).filter((p) => p.owner.id === me.id);
   const exports = repo.listExports();
+  const exportByKey = new Map(exports.map((e) => [e.canonicalKey, e] as const));
 
-  const sourcePlaylists = selectedSourcePlaylists(repo, cfg, opts);
+  const mirrored = selectedSourcePlaylists(repo, cfg, {});
+  const selected = new Set(selectedSourcePlaylists(repo, cfg, opts).map((p) => p.id));
 
   const playlists: PlaylistPlan[] = [];
+  /** ids the playlists this run acts on want liked → saved if not yet */
   const likeDesired = new Set<string>();
+  /** ids any mirrored playlist wants liked → never pruned, whatever `--playlist`/`--source` selected */
+  const likeNeeded = new Set<string>();
 
-  for (const sp of sourcePlaylists) {
-    const targetName = cfg.sync.playlist_prefix + sp.name;
-    const tracks = repo.playlistTracks(sp.id);
-    const matches = repo.matchesForKeys(tracks.map((t) => t.canonicalKey));
-    const exportByKey = new Map(exports.map((e) => [e.canonicalKey, e] as const));
-    const likeThis = sp.kind === "netease" ? cfg.netease.like_matched : cfg.local.like_matched;
-
-    const desired: DesiredItem[] = [];
-    const seen = new Set<string>();
-    for (const t of tracks) {
-      const m = matches.get(t.canonicalKey);
-      if (!m) continue;
-      let item: DesiredItem | null = null;
-      if (m.status === "matched" && m.spotifyUri && m.spotifyId) {
-        item = { uri: m.spotifyUri, kind: "spotify", canonicalKey: t.canonicalKey };
-        if (likeThis) likeDesired.add(m.spotifyId);
-      } else if (m.status === "local") {
-        const e = exportByKey.get(t.canonicalKey);
-        if (e) item = { uri: e.localUri, kind: "local", canonicalKey: t.canonicalKey };
-      }
-      if (item && !seen.has(item.uri)) {
-        seen.add(item.uri);
-        desired.push(item);
-      }
-    }
+  for (const sp of mirrored) {
+    const { desired, likes } = desiredItems(repo, cfg, sp, exportByKey);
+    for (const id of likes) likeNeeded.add(id);
+    if (!selected.has(sp.id)) continue;
+    for (const id of likes) likeDesired.add(id);
 
+    const targetName = cfg.sync.playlist_prefix + sp.name;
     const remote = await resolveRemotePlaylist(sp, targetName, remotePlaylists, deps);
     let remoteItems: RemoteItem[] = [];
+    let snapshotId: string | null = null;
     if (remote) {
-      remoteItems = (await api.getPlaylistItems(remote.id)).map((it) => {
-        if (!it.item) return { uri: "", isLocal: false, stale: false };
+      const listing = await listPlaylistItemsConsistently(api, remote.id);
+      snapshotId = listing.snapshotId;
+      remoteItems = listing.items.map((it) => {
+        if (!it.item) return { uri: "", isLocal: false, owned: false };
         if (it.is_local || it.item.is_local) return { ...resolveRemoteLocalUri(it.item.uri, exports), isLocal: true };
-        return { uri: it.item.uri, isLocal: false, stale: false };
+        return { uri: it.item.uri, isLocal: false, owned: false };
       });
     }
 
@@ -292,6 +310,7 @@ export async function buildPlan(deps: SyncDeps, opts: Pick<SyncOptions, "prune"
         sourceName: sp.name,
         targetName,
         spotify: remote,
+        snapshotId,
         desired,
         remote: remoteItems,
         managed: remote ? repo.managedUris(remote.id) : new Set<string>(),
@@ -300,15 +319,53 @@ export async function buildPlan(deps: SyncDeps, opts: Pick<SyncOptions, "prune"
     );
   }
 
-  // Likes: everything desired that is not already saved; prune tool-liked ids no longer desired.
+  // Likes: everything desired that is not already saved; prune tool-liked ids no mirrored playlist wants any
+  // more. With nothing mirrored there is nothing to reconcile against, so nothing is pruned.
   const likeIds = [...likeDesired];
   const saved = await savedFlags(api, likeIds);
   const likes = {
     add: likeIds.filter((_, i) => !saved[i]),
-    prune: [...repo.likedIds()].filter((id) => !likeDesired.has(id)),
+    prune: mirrored.length === 0 ? [] : [...repo.likedIds()].filter((id) => !likeNeeded.has(id)),
   };
+  if (mirrored.length === 0 && (repo.likedIds().size > 0 || exports.length > 0)) {
+    log.warn("no playlist is mirrored (check netease.include_playlists / local.mirror_playlist); keeping every tool-liked track and export", {
+      liked: repo.likedIds().size,
+      exports: exports.length,
+    });
+  }
+
+  const planned = new Set<string>();
+  for (const p of playlists) if (p.spotifyId !== null) planned.add(p.spotifyId);
+  return { playlists, likes, exports: exportPlans, exportGc: planExportGc(repo, cfg, opts, planned), reviewPending: repo.countMatches().review };
+}
 
-  return { playlists, likes, exports: exportPlans, reviewPending: repo.countMatches().review };
+/** What one source playlist wants on Spotify, in source order and deduped by uri, plus the ids it wants liked. */
+function desiredItems(repo: Repo, cfg: Config, sp: SourcePlaylistRow, exportByKey: ReadonlyMap<string, LocalExportRow>): { desired: DesiredItem[]; likes: string[] } {
+  const tracks = repo.playlistTracks(sp.id);
+  const matches = repo.matchesForKeys(tracks.map((t) => t.canonicalKey));
+  const likeThis = sp.kind === "netease" ? cfg.netease.like_matched : cfg.local.like_matched;
+  const desired: DesiredItem[] = [];
+  const likes: string[] = [];
+  const seen = new Set<string>();
+  for (const t of tracks) {
+    const m = matches.get(t.canonicalKey);
+    if (!m) continue;
+    let item: DesiredItem | null = null;
+    if (m.status === "matched" && m.spotifyUri && m.spotifyId) {
+      item = { uri: m.spotifyUri, kind: "spotify", canonicalKey: t.canonicalKey };
+      if (likeThis) likes.push(m.spotifyId);
+    } else if (m.status === "local" || m.status === "review") {
+      // `review` keeps the export already in place: a candidate that still needs a human (a re-search after
+      // retry_unmatched_after_days, say) must not undo the user's paste. Only `local` gets a new export.
+      const e = exportByKey.get(t.canonicalKey);
+      if (e) item = { uri: e.localUri, kind: "local", canonicalKey: t.canonicalKey };
+    }
+    if (item && !seen.has(item.uri)) {
+      seen.add(item.uri);
+      desired.push(item);
+    }
+  }
+  return { desired, likes };
 }
 
 /** Which of `ids` are already liked. `/me/tracks/contains` is 403 for some development-mode apps; then list the library instead. */
@@ -324,6 +381,22 @@ async function savedFlags(api: SpotifyApi, ids: string[]): Promise<boolean[]> {
   }
 }
 
+/**
+ * Items plus the snapshot id they belong to. The listing is paginated and the snapshot endpoint is
+ * separate, so the listing is bracketed by two snapshot reads and retried while they differ; the
+ * snapshot is what position-based removals are validated against, so a wrong one must never be sent.
+ */
+async function listPlaylistItemsConsistently(api: SpotifyApi, id: string): Promise<{ items: SpotifyPlaylistItem[]; snapshotId: string }> {
+  for (let attempt = 1; ; attempt++) {
+    const before = await api.getPlaylistSnapshot(id);
+    const items = await api.getPlaylistItems(id);
+    const after = await api.getPlaylistSnapshot(id);
+    if (before === after) return { items, snapshotId: after };
+    if (attempt === 3) throw new Error(`playlist ${id} keeps changing while it is being read; retry later`);
+    log.warn("playlist changed while listing, retrying", { id, attempt });
+  }
+}
+
 /**
  * Find the remote playlist for a source playlist: the stored mapping if it still exists, else a
  * remote playlist with the target name carrying our description (adoption after state loss), else null.
@@ -362,9 +435,14 @@ function planExports(repo: Repo, localKeys: string[], exports: LocalExportRow[],
     // An export is current when the source is unchanged and its recorded identity is complete
     // (rows written before the duration segment was known cannot match anything the client indexes).
     if (!force && existing && existing.contentHash === t.file.contentHash && parseLocalUri(existing.localUri)?.durationSec !== null) continue;
-    let base = sanitizeFilename(`${t.artists.join(", ") || "Unknown Artist"} - ${t.title}`);
+    const raw = `${t.artists.join(", ") || "Unknown Artist"} - ${t.title}`;
+    let base = sanitizeFilename(raw);
     if (!existing) {
-      for (let n = 2; usedNames.has(base.toLowerCase()); n++) base = sanitizeFilename(`${t.artists.join(", ") || "Unknown Artist"} - ${t.title} (${n})`);
+      // The suffix is appended after truncation, so a name at the length limit still gets a distinct one.
+      for (let n = 2; usedNames.has(base.toLowerCase()); n++) {
+        const suffix = ` (${n})`;
+        base = sanitizeFilename(raw, MAX_FILENAME - suffix.length) + suffix;
+      }
     } else {
       base = existing.exportPath.replace(/\.[^.\\/]+$/, "").replace(/^.*[\\/]/, "");
     }
@@ -396,9 +474,11 @@ export function formatPlan(plan: Plan, prune: boolean): string {
     for (const x of p.prune) lines.push(`    ${prune ? "-" : "?"} ${x.uri}`);
   }
   lines.push(`likes: +${plan.likes.add.length}, prune ${plan.likes.prune.length}${prune ? "" : " (report only)"}`);
-  lines.push(`exports: ${plan.exports.length}`);
+  lines.push(`exports: ${plan.exports.length}, remove ${plan.exportGc.length}${prune ? "" : " (report only)"}`);
   for (const e of plan.exports.slice(0, 20)) lines.push(`    → ${e.baseName}  (${e.sourcePath})`);
   if (plan.exports.length > 20) lines.push(`    → … ${plan.exports.length - 20} more`);
+  for (const e of plan.exportGc.slice(0, 20)) lines.push(`    ${prune ? "-" : "?"} ${e.exportPath}`);
+  if (plan.exportGc.length > 20) lines.push(`    ${prune ? "-" : "?"} … ${plan.exportGc.length - 20} more`);
   lines.push(`review pending: ${plan.reviewPending}`);
   return lines.join("\n");
 }

package/src/util/fs.ts

@@ -1,7 +1,10 @@
 import { createReadStream } from "node:fs";
 
+/** Longest base name (without extension) an export file gets, in UTF-16 units (NTFS's limit is 255). */
+export const MAX_FILENAME = 150;
+
 /** Replace characters Windows/NTFS rejects and trim trailing dots/spaces. */
-export function sanitizeFilename(name: string, max = 150): string {
+export function sanitizeFilename(name: string, max = MAX_FILENAME): string {
   const cleaned = name
     .replace(/[<>:"/\\|?*\u0000-\u001f]/g, "_")
     .replace(/\s+/g, " ")