spotifify 0.1.1 → 0.1.2

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## [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. 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` 还会删掉被取代的本地条目和不再需要的导出文件。退出码 `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.2",
   "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.2") // 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/spotify/api.ts

@@ -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 = "";

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

@@ -423,6 +423,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

@@ -30,6 +30,8 @@ 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. */
@@ -38,7 +40,7 @@ const REPLACE_MOVE_RATIO = 1 / 3;
 
 /** 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);
 
@@ -118,15 +120,18 @@ async function applyPlaylist(p: PlaylistPlan, deps: ApplyDeps, s: ApplySummary):
       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`);
+      // 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);

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 */
@@ -62,6 +64,8 @@ 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;
 }
@@ -70,10 +74,11 @@ export interface RemoteItem {
   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 +87,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 +103,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,6 +135,7 @@ 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),
@@ -149,7 +157,7 @@ export function computePlaylistPlan(input: PlaylistPlanInput): PlaylistPlan {
   const foreign: string[] = [];
   remote.forEach((r, i) => {
     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,6 +200,7 @@ 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,

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 { 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,8 @@ 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.
+    if (apply && opts.prune) apply.exportsRemoved = await removeExports(plan.exportGc, repo);
     const summary: SyncSummary = {
       pulled,
       matched,
@@ -103,6 +106,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 +134,19 @@ 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 the remote entries pointing at these files are pruned in the same run
+ * (they are `owned`), so nothing in a playlist is left pointing at a deleted file.
+ */
+export function planExportGc(repo: Repo, cfg: Config, opts: Pick<SyncOptions, "source" | "playlist">): LocalExportRow[] {
+  if (opts.source || opts.playlist) return [];
+  const needed = selectedKeys(repo, cfg, opts);
+  const local = new Set(repo.listMatches("local").map((m) => m.canonicalKey));
+  return repo.listExports().filter((e) => !needed.has(e.canonicalKey) || !local.has(e.canonicalKey));
+}
+
 // ---- pull -------------------------------------------------------------------
 
 async function pull(deps: SyncDeps, opts: SyncOptions, now: number): Promise<SyncSummary["pulled"]> {
@@ -278,11 +295,14 @@ export async function buildPlan(deps: SyncDeps, opts: Pick<SyncOptions, "prune"
 
     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 +312,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>(),
@@ -308,7 +329,7 @@ export async function buildPlan(deps: SyncDeps, opts: Pick<SyncOptions, "prune"
     prune: [...repo.likedIds()].filter((id) => !likeDesired.has(id)),
   };
 
-  return { playlists, likes, exports: exportPlans, reviewPending: repo.countMatches().review };
+  return { playlists, likes, exports: exportPlans, exportGc: planExportGc(repo, cfg, opts), reviewPending: repo.countMatches().review };
 }
 
 /** Which of `ids` are already liked. `/me/tracks/contains` is 403 for some development-mode apps; then list the library instead. */
@@ -324,6 +345,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.
@@ -396,9 +433,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");
 }