engine-dj-mcp 0.11.3 → 0.15.0

package/README.md

@@ -54,11 +54,15 @@ the configuration you are reading:
 ```json
 {
   "mcpServers": {
-    "engine-dj": { "command": "npx", "args": ["-y", "engine-dj-mcp", "--allow-writes"] }
+    "engine-dj": { "command": "npx", "args": ["-y", "engine-dj-mcp@0.15.0", "--allow-writes"] }
   }
 }
 ```
 
+Pin the version in this one. Unpinned, `npx` fetches whatever is newest at
+every launch, and this configuration gives that code write access to your
+library. Pinned, a new release reaches it only when you change the number.
+
 **Requirements:** Node.js 22.16 or newer (`node:sqlite` stopped needing a
 flag in 22.13, but the pre-write snapshot uses its `backup()`, added in
 22.16;
@@ -67,10 +71,11 @@ through 3.0.2 — Engine DJ 4.5 and 5.x.
 
 ## Tools
 
-Nine read-only tools, and a tenth — `create_playlist` — that appears only
-when you start the server with `--allow-writes`. Every tool that reads
-library data also accepts an optional `library` argument — see
-[Choosing a library](#choosing-a-library).
+Nine read-only tools, and four that write — `create_playlist`,
+`add_tracks_to_playlist`, `remove_tracks_from_playlist` and
+`reorder_playlist` — that appear only when you start the server with
+`--allow-writes`. Every tool that reads library data also accepts an
+optional `library` argument — see [Choosing a library](#choosing-a-library).
 
 ### `search_tracks`
 
@@ -155,7 +160,7 @@ Positions are sample offsets; cue and loop items also carry seconds.
 
 ### `audit_library`
 
-Ten collection health checks. Returns a count and a small sample of ids per
+Eleven collection health checks. Returns a count and a small sample of ids per
 check, never the full result set — a library with thousands of unanalysed
 tracks should not fill an assistant's context.
 
@@ -168,11 +173,12 @@ tracks should not fill an assistant's context.
 | `no_beatgrid` | Tracks with no beatgrid data |
 | `missing_key` | Tracks with no key detected |
 | `suspicious_bpm` | Analysed and tagged tempo disagree, or tempo is outside 60–200 |
-| `duplicates` | Same artist and title, or same size and length |
+| `duplicates` | Same artist and title, compared regardless of case in any script |
 | `empty_metadata` | No artist or no title |
 | `orphan_entries` | Playlist entries pointing at tracks not in this library — `get_playlist_tracks` shows where each one sits |
+| `path_form_mismatch` | The file is on disk, but its name there — or a folder's on the way — is in a different Unicode form from the path Engine stored. macOS finds it anyway; Linux does not (measured on the kernel's exFAT driver), and Engine OS on a player is Linux, so these may fail to load on hardware. Differences in case alone are not counted: exFAT and Windows ignore case |
 
-`checks` — omit it to run all ten.
+`checks` — omit it to run all eleven.
 
 ### `run_sql`
 
@@ -204,7 +210,7 @@ server checks staleness itself before answering.
 
 ### `create_playlist`
 
-The only tool that writes, and the only one that is not registered at all
+The first of the four tools that write, none of which is registered at all
 unless the server was started with `--allow-writes`.
 
 Creates one new top-level playlist from track ids — `track_ids` sets both
@@ -223,19 +229,140 @@ Each entry stores the track's origin identity — `(originDatabaseUuid,
 originTrackId)`, the pair Engine matches on — not the local row id, so a
 playlist built here reads the same way Engine's own does.
 
-The result carries `playlist_id`, `tracks_added` and `backup_path`. **To undo
+The result carries `playlist_id`, `tracks_added`, `library` and `backup_path`. **To undo
 it, delete the playlist in Engine DJ**; `backup_path` is a whole-library
 snapshot for the case where something went wrong at a lower level, not an
 undo — see [Restoring a snapshot](#restoring-a-snapshot).
 
-Refusals name themselves: `playlist_exists` for a taken title,
-`unknown_track` for an id this library does not have, `duplicate_track` for
-the same id twice, `library_busy` if something else holds a conflicting lock
-right then, `library_needs_recovery` if Engine DJ left an unrecovered
-journal behind. Every error also carries `detail`: `not_committed` means the
-library is exactly what it was, and `committed_unverified` — the rare one —
-means the write may have landed but could not be verified afterwards, and is
-the only case that hands back a `backup_path`.
+Its own refusals: `playlist_exists` for a taken title, `unknown_track` for an
+id this library does not have, `duplicate_track` for the same id twice — plus
+the ones [every write tool shares](#refusals-every-write-tool-shares).
+
+### `add_tracks_to_playlist`
+
+Adds one or more tracks to an **existing** playlist — this edits that
+playlist's contents, it does not create a new one (`create_playlist` does
+that). If the playlist's entry chain is already damaged, the write is
+refused outright rather than repaired, and nothing is added.
+
+A playlist that is a **folder** (`is_folder: true` — it has child lists) is
+edited like any other: Engine has no separate folder type, a folder can hold
+entries of its own, and all three edit tools add to, remove from and reorder
+those entries without complaint. The lists inside it are untouched either
+way.
+
+| Argument | What it does |
+| --- | --- |
+| `playlist_id` / `playlist_name` | Exactly one of the two, resolved the same way `get_playlist_tracks` does: a name matching more than one playlist is refused with every candidate's id and full path listed, not guessed at. |
+| `track_ids` | Ids from `search_tracks` or `get_tracks`, in the order they should appear. A track already in the playlist is refused as `duplicate_track` — Engine allows a track in a playlist only once. |
+| `at` | Where the new tracks land, against the playlist's current 1-based positions (the same numbering `get_playlist_tracks` reports): `"start"`, `"end"` (the default), or `{ after_position: n }`. |
+
+The result carries `playlist_id`, `tracks_added`, `positions` — where the
+new tracks landed — `undo`, `undo_complete` (always `true` here), `library`
+and `backup_path`. `undo` is the exact `remove_tracks_from_playlist` call that
+reverses this edit: the positions the tracks landed at, plus
+`expect_track_ids` naming the tracks that landed there, so a playlist
+something else changed in the meantime is refused rather than having the
+wrong rows removed. Call it to undo rather than restoring `backup_path` —
+see [Restoring a snapshot](#restoring-a-snapshot), and
+[An undo covers one library](#an-undo-covers-one-library) for what it does
+not reach. Its own refusals: `playlist_not_found`, `playlist_chain_damaged`,
+`invalid_position`, and `unknown_track` / `duplicate_track` as for
+`create_playlist` — plus the ones
+[every write tool shares](#refusals-every-write-tool-shares).
+
+### `remove_tracks_from_playlist`
+
+Removes one or more tracks from an **existing** playlist by position — this
+edits that playlist's contents; it never touches any other playlist. If the
+entry chain is already damaged, the write is refused outright rather than
+repaired.
+
+| Argument | What it does |
+| --- | --- |
+| `playlist_id` / `playlist_name` | Exactly one of the two, resolved the same way `get_playlist_tracks` does. |
+| `positions` | 1-based positions `get_playlist_tracks` reports for this playlist right now. Includes entries whose track is missing from the library (`missing: true`) — removing one is a legitimate way to clean up a hole, and the one removal `undo` cannot reverse (see below). |
+| `expect_track_ids` | Optional, one entry per position: verifies each named position still holds the track expected before anything is removed, refusing the whole call otherwise. `null` means "this position should hold an entry whose track is missing", not "no expectation". |
+
+The result carries `playlist_id`, `tracks_removed`, `removed` — each
+position's `track_id`, `null` for a missing one — `undo`, `undo_complete`,
+`library` and `backup_path`. `undo` is a **sequence** of `add_tracks_to_playlist` calls,
+one per removed track that can be restored. Run them in the order given,
+never in parallel and never reversed — each step's target position is
+computed against the list as it stands after the previous step has already
+run, so firing them out of order puts tracks back in the wrong places.
+Preferred over restoring `backup_path` for the same reason as above.
+
+`undo_complete` is `false` when the removal included an entry whose track is
+missing from the library: that entry named a track this library does not
+have, so no `add_tracks_to_playlist` call can put it back, and an
+`undo_note` names those positions. The steps that are returned still run and
+still restore everything else; the missing entries are recoverable only from
+`backup_path`, which reverts the whole library.
+
+Its own refusals: `playlist_not_found`, `playlist_chain_damaged`, and
+`invalid_position` — for a repeated or out-of-range position, or one that
+does not hold what `expect_track_ids` expected — plus the ones
+[every write tool shares](#refusals-every-write-tool-shares).
+
+`playlist_chain_damaged` always means the same thing for all three edit
+tools: the playlist's entry chain was already broken **before** the edit,
+which is why the edit refused to touch it. If instead the check each edit
+runs on its own work disagrees — the chain did not read back as it was
+written — the transaction is rolled back and that comes back as
+`library_unreadable`, with `detail: "not_committed"`. Both leave the library
+exactly as it was; only the second one is this server saying it does not
+understand what the library just did.
+
+### `reorder_playlist`
+
+Reorders an **existing** playlist's tracks — this changes the order of that
+playlist's existing entries; it adds nothing and removes nothing. If the
+entry chain is already damaged, the write is refused outright rather than
+repaired.
+
+| Argument | What it does |
+| --- | --- |
+| `playlist_id` / `playlist_name` | Exactly one of the two, resolved the same way `get_playlist_tracks` does. |
+| `order` | A full permutation of `1..n`, `n` being the playlist's current entry count. `order[i]` names the *current* 1-based position (from `get_playlist_tracks`) of the track that should end up at position `i + 1`. A partial "move x to y" instruction is not accepted — name every position, including ones that do not move. |
+
+The result carries `playlist_id`, `undo`, `undo_complete` (always `true`
+here), `library` and `backup_path`. `undo` is the exact inverse permutation, as a single
+`reorder_playlist` call. Its own refusals: `playlist_not_found`,
+`playlist_chain_damaged`, and `invalid_position` if `order` is not a full
+permutation of the playlist's current positions — plus the ones
+[every write tool shares](#refusals-every-write-tool-shares).
+
+Reordering to the order a playlist is already in is accepted and rewrites no
+entry: it still stamps the playlist's `lastEditTime`, and still costs this
+session's snapshot if nothing had been written yet.
+
+### Refusals every write tool shares
+
+These come from what happens before the write itself — choosing the library,
+bringing its index up to date, resolving the playlist — and from the write's
+own checks.
+
+| Code | Means | Nothing written? |
+| --- | --- | --- |
+| `invalid_argument` | The arguments do not make sense — both `playlist_id` and `playlist_name`, an empty list where one is required, or a `playlist_name` that matches several playlists (every candidate is listed). | yes |
+| `library_not_found` | `library` names nothing connected — the refusal lists what is — or the library's header could not be read. | yes |
+| `ambiguous_library` | No `library` given, and two libraries tie for the default. Lists both — see [Choosing a library](#choosing-a-library). | yes |
+| `unsupported_schema` | The library's version is outside what this server supports. | yes |
+| `library_needs_recovery` | Engine DJ left an unrecovered journal. Launch Engine once. | yes |
+| `library_busy` | Something holds a conflicting lock right now. Retry. | yes |
+| `index_stale` | The index could not be built yet, typically because Engine holds a lock on a first run. Carries `retry_after_ms`. | yes |
+| `query_timeout`, `query_process_crashed` | The lookup that resolves a playlist failed. Edit tools only. | yes |
+| `library_unreadable` | The library could not be read; the snapshot taken before the first write could not be made (a full disk, or a Node older than 22.16); or a write's own read-back disagreed with what it wrote, and it was rolled back. | see `detail` |
+
+**`detail` on these errors.** Once the write itself has started, `detail` is
+exactly one of two strings, and a client can read it to decide whether the
+library changed: `not_committed` — the library is what it was — or
+`committed_unverified` — the rare one: the write may have landed but could not
+be confirmed, and only this case hands back a `backup_path`. Refusals raised
+*before* that point — every row above marked "yes" — never opened the library
+for writing, whatever their `detail` says: it may be absent, `not_committed`,
+or explanatory text such as the candidates an ambiguous `playlist_name` lists.
 
 ## Resources
 
@@ -260,6 +387,26 @@ tracks**. That matters: the local library Engine DJ creates on install is
 scanned first and is often empty, so "the first one found" would hide the
 drive you actually work from.
 
+When two supported libraries hold the *same* highest number of tracks, that
+rule names no winner — and a tie is the ordinary case, not an exotic one: a
+USB drive and its copy on the computer tie precisely because one is a copy of
+the other. Measured 2026-09-01, both real libraries reported 257 tracks.
+
+**A read still chooses for itself.** Tied libraries hold the same tracks, so
+either answer is very nearly the same answer, and making you name a library
+you have no reason to care about would be noise.
+
+**A write refuses**, with `ambiguous_library` listing every candidate and its
+track count, and `detail: "not_committed"`. The choice decides which physical
+disk changes, and one of the two may be the drive you perform from; scan
+order is not a reason to pick it. Name a library and the write goes through,
+tie or not — the ambiguity being refused is the server's, not yours.
+
+The refusal tells the assistant to **ask you** rather than choose. Otherwise
+"pass `library`, here are the two" is an invitation to take the first one,
+which puts the write back on an arbitrary disk and makes the refusal
+pointless.
+
 Each library gets its own index and its own connection, opened the first time
 you ask that library something. Comparing two libraries against each other —
 *"what is on this drive but not that one?"* — is **not** something this server
@@ -278,11 +425,32 @@ created inside your `Engine Library` folder. The search index lives in
 Without `--allow-writes` the server has no tool that can write, and the
 paragraph above holds exactly as written: SQLite itself refuses.
 
-With the flag, one tool appears — `create_playlist`. It adds a new playlist
-and nothing else: no existing playlist is renamed, reordered, emptied or
-deleted, and no track, cue or beatgrid is touched. The single change to an
-existing row is the previous last playlist's link, made by Engine's own
-trigger.
+With the flag, four tools appear. `create_playlist` adds a new playlist and
+nothing else. `add_tracks_to_playlist`, `remove_tracks_from_playlist` and
+`reorder_playlist` go further: with the flag, an **existing** playlist can
+now be changed, not only created — its tracks added to, removed from, or put
+in a different order. What each one touches is the named playlist's own
+entries, plus exactly two rows elsewhere: that playlist's own row, whose
+`lastEditTime` every edit stamps so Engine sees the change, and — for
+`create_playlist` only — the previous last playlist's link, made by Engine's
+own insert trigger. No other playlist is renamed, emptied or deleted, and no
+track, cue or beatgrid is touched by any of the four.
+
+Every edit returns `undo` — the exact tool call that reverses it, expressed
+against the positions the edit itself produced — and `undo_complete`, saying
+whether replaying it puts the playlist back exactly as it was. Replaying
+`undo` is the right way back from an edit; restoring `backup_path` is not,
+because it reverts the **whole library** to before this session's first
+write, discarding every play count, import, cue and beatgrid change Engine
+DJ has recorded since, along with the one edit you actually wanted undone.
+See [Restoring a snapshot](#restoring-a-snapshot).
+
+There is exactly one edit `undo` cannot reverse, and it says so rather than
+pretending otherwise: removing an entry whose track is missing from the
+library (`missing: true`). Such an entry names a track this library does not
+have, so there is no track id to add back — the result comes back with
+`undo_complete: false` and an `undo_note` naming those positions, and the
+steps it does return still restore everything else.
 
 Before the first write of a session the database is snapshotted to
 `~/.engine-dj-mcp/backups/`, and every write of that session returns its
@@ -302,23 +470,74 @@ and without `--allow-writes` not even this.
 The write takes SQLite's own write lock for the length of one transaction and
 does not wait for it: if something else — Engine DJ mid-save, a player — is
 holding a conflicting lock at that moment, the write is refused with
-`library_busy` and nothing is changed. Merely having Engine DJ *open* is not
-usually a conflict, and the write normally succeeds with Engine running;
-Engine will show the new playlist after it next re-reads the library.
+`library_busy` and nothing is changed.
+
+**Quit Engine DJ before writing.** Having Engine open is not usually a lock
+conflict, so the write itself will normally go through — but what Engine then
+does with a change made underneath it has never been measured here. Every
+acceptance check of a write was run with Engine closed. What *has* been
+measured is that Engine does its own work on the library as it loads: it
+renumbers playlist entries, and it copies playlist changes to another
+connected library (see below). Quit, write, relaunch — Engine reads the
+library on startup and shows the change.
+
+Quit, not close. On macOS, closing Engine's window leaves the application
+running: observed 2026-09-01 with the main process and seven
+`OfflineAnalyzer` workers — which write to the database — still alive
+afterwards. Use ⌘Q.
+
+### An undo covers one library
+
+Every write result carries a `library` field — the `uuid` and `path` of the
+library the write actually landed in. Two libraries connected at once is the
+ordinary setup: a USB drive and its copy on the computer. This is where you
+check which of them a write went to.
+
+**`undo` reverses the edit in that one library, and only there.** Engine DJ
+moves playlist changes between connected libraries by itself, so a copy of
+your edit can end up somewhere `undo` cannot reach.
+
+Measured 2026-09-01. A track was added to a playlist in the library on the
+computer. Engine DJ was then launched with the USB drive attached, and the
+same playlist on the USB came back with the same track added — the copy
+carrying the very `lastEditTime` this server's `INSERT` had written. The
+`undo` was then run and reversed the edit on the computer. The USB kept it.
+
+Nothing was damaged: both libraries stayed sound. But the two had diverged,
+and the `undo` reported success, correctly, because within its own library it
+did exactly what it promised.
+
+So: if a second library is connected, look at the `library` field, and undo
+against each library separately. Undoing before Engine DJ next runs avoids
+the problem entirely.
+
+Which library a change propagates to, and in which direction, is Engine's own
+business — this project does not model it and will not guess at it.
 
 ### Restoring a snapshot
 
 `backup_path` is not an undo. It is a copy of the **whole** `m.db` from
 before the session's first write, so putting it back reverts the entire
 library to that moment: every play count, import, cue, beatgrid and rating
-Engine DJ has written since is discarded along with the playlist you wanted
-gone. Reach for it only if the library itself is damaged — the case where
-`create_playlist` comes back with `detail: "committed_unverified"`.
-
-**To undo a playlist, delete it in Engine DJ.** Engine's own delete trigger
-repairs the playlist chain and cascades the entries away, which is exactly
-what removing it should do and is not something restoring a snapshot does
-better.
+Engine DJ has written since is discarded along with the one edit you wanted
+gone. Reach for it only if the library itself is damaged — the case where a
+write comes back with `detail: "committed_unverified"`.
+
+Snapshots live in `~/.engine-dj-mcp/backups/`, ten per library. Only a name
+ending in `.db` is a snapshot. A file ending in `.partial-<number>` — with or
+without `-journal` after it — is a copy still being written, or one whose
+process died before it finished: **never restore one of those**. A copy is
+renamed to its `.db` name only once it is complete, and an abandoned one is
+cleared the next time that library is snapshotted.
+
+**To undo a playlist you created, delete it in Engine DJ.** Engine's own
+delete trigger repairs the playlist chain and cascades the entries away,
+which is exactly what removing it should do and is not something restoring
+a snapshot does better. **To undo an edit to an existing playlist, replay
+the `undo` the edit returned instead** — it names the precise
+`add_tracks_to_playlist`, `remove_tracks_from_playlist` or
+`reorder_playlist` call that puts the playlist back exactly as it was,
+without touching anything else Engine DJ has recorded since.
 
 `run_sql` accepts arbitrary SQL, but only the first statement is ever
 executed, and `VACUUM`, `ATTACH` and `DETACH` are rejected outright, so a
@@ -327,7 +546,7 @@ chained or exfiltrating statement cannot slip past the read-only connection.
 If Engine DJ was closed uncleanly and left an unrecovered journal, this
 server will not open the library to "fix" it, with or without
 `--allow-writes` — rolling a journal forward is a repair on someone else's
-file, and `create_playlist` refuses such a library outright rather than
+file, and every write tool refuses such a library outright rather than
 letting SQLite do it on the way in. It reports `library_needs_recovery` and
 asks you to launch Engine DJ once so it can recover its own library.
 
@@ -374,9 +593,9 @@ still test for the blob: `beatData` has no "written but empty" state.
 
 **It writes nothing but playlists, and only when you ask for it.** Without
 `--allow-writes` the library is opened read-only at the OS level and there is
-no tool that could write. With the flag, `create_playlist` adds playlists —
-and that is the whole list. Not a cue, not a tag, not a rating, and not even
-the recovery of a journal Engine DJ left behind.
+no tool that could write. With the flag, the four write tools add, edit and
+reorder playlists — and that is the whole list. Not a cue, not a tag, not a
+rating, and not even the recovery of a journal Engine DJ left behind.
 
 **It does not read play history.** `Track.timeLastPlayed` answers "what have I
 not played in six months?", but the separate Engine history database —
@@ -392,11 +611,12 @@ flag — a folder is simply a playlist that other playlists sit under — so
 `is_folder` means "has child lists". A folder you have emptied is
 indistinguishable from a playlist with no tracks.
 
-**Playlists can be created, not edited.** With `--allow-writes` a new
-playlist can be added; there is no reordering, renaming, deleting, or adding
-a track to a playlist that already exists, and no set lists or suggested
-transitions. It answers questions about the collection and writes down the
-answer if you ask; the mixing is yours.
+**A playlist's tracks can be edited; the playlist itself cannot.** With
+`--allow-writes` a new playlist can be created, and an existing one can have
+tracks added, removed or reordered — but not renamed, deleted, moved between
+folders, or turned into a folder itself, and there are no set lists or
+suggested transitions. It answers questions about the collection and writes
+down the answer if you ask; the mixing is yours.
 
 **Schema 3.0.0 through 3.0.2 only.** Older and newer libraries are listed with
 their version and reported as unsupported rather than read on a guess.

package/dist/errors.d.ts

@@ -1,4 +1,4 @@
-export declare const ERROR_CODES: readonly ["library_busy", "library_not_found", "library_unreadable", "unsupported_schema", "query_timeout", "query_process_crashed", "index_stale", "decode_failed", "invalid_argument", "library_needs_recovery", "playlist_exists", "unknown_track", "duplicate_track"];
+export declare const ERROR_CODES: readonly ["library_busy", "library_not_found", "library_unreadable", "unsupported_schema", "query_timeout", "query_process_crashed", "index_stale", "decode_failed", "invalid_argument", "library_needs_recovery", "playlist_exists", "unknown_track", "duplicate_track", "playlist_chain_damaged", "playlist_not_found", "invalid_position", "ambiguous_library"];
 export type ErrorCode = (typeof ERROR_CODES)[number];
 export interface EngineError {
     error: ErrorCode;

package/dist/errors.js

@@ -27,6 +27,18 @@ export const ERROR_CODES = [
     "playlist_exists",
     "unknown_track",
     "duplicate_track",
+    // Editing an existing playlist. playlist_chain_damaged is the one that
+    // matters: a chain with a cycle or a severed link cannot be edited without
+    // making it worse, and the edit would not notice.
+    "playlist_chain_damaged",
+    "playlist_not_found",
+    "invalid_position",
+    // No `library` was passed and the default rule names no single winner --
+    // two supported libraries hold the same, highest track count. Its own code
+    // rather than invalid_argument because the useful client response is
+    // specific: ask which drive, then retry with `library` set. Only writes
+    // raise it; see library-select.ts for why reads still choose.
+    "ambiguous_library",
 ];
 export function err(error, message, extra = {}) {
     return { error, message, ...extra };

package/dist/library-select.d.ts

@@ -34,6 +34,42 @@ export declare const LibraryArg: z.ZodOptional<z.ZodString>;
  * supported library" would otherwise collapse into.
  */
 export declare function pickDefaultLibrary(libs: readonly LibraryInfo[]): LibraryInfo | null;
+/**
+ * The supported libraries tied for the default pick -- more than one holding
+ * the same, highest track count. Empty when the default is unambiguous, which
+ * includes the single-library case every DJ starts from.
+ *
+ * A tie is not an exotic shape: it is what a USB drive and its copy on the
+ * computer produce, and they tie *because* one is a copy of the other.
+ * Measured 2026-09-01, both real libraries reported 257 tracks.
+ *
+ * For a read, either answer is very nearly the same answer -- the two are
+ * copies -- so `pickDefaultLibrary` keeps choosing, and a read never has to
+ * name a library it does not care about. For a write the choice decides which
+ * physical disk changes, and one of them is the drive the DJ performs from.
+ * Hence: reads choose, writes refuse. Callers wanting the strict behaviour
+ * check this first.
+ *
+ * Skips unsupported libraries for the same reason `pickDefaultLibrary` does:
+ * one can never be chosen while a supported library exists, so it is not a
+ * competing candidate and must not make a write refuse.
+ */
+export declare function defaultLibraryTies(libs: readonly LibraryInfo[]): LibraryInfo[];
+/**
+ * The refusal for an ambiguous default on a write.
+ *
+ * Every candidate is named, with its track count, because the caller has to
+ * pick one and cannot do that from "it was ambiguous" -- the same reason
+ * get_playlist_tracks lists candidates for an ambiguous playlist name.
+ *
+ * The list goes in `message`, never in `detail`. This is only ever returned
+ * from a write tool, and on that path `detail` carries exactly
+ * `"not_committed"` or `"committed_unverified"` -- a client reads it to
+ * decide whether its library changed. Prose there would break that read for
+ * the one error whose answer is least in doubt: nothing was opened, let alone
+ * written.
+ */
+export declare function ambiguousLibrary(tied: readonly LibraryInfo[]): EngineError;
 /**
  * Resolves a caller-supplied `library` value: uuid first, then filesystem
  * path. Returns null when it matches neither -- the caller decides what

package/dist/library-select.js

@@ -14,7 +14,10 @@ import { expandHome, redactPath } from "./paths.js";
  */
 export const LIBRARY_ARG_DESCRIPTION = "Which library to use: either the uuid or the path reported by list_libraries " +
     "(the reported ~/... form is accepted, as is the absolute path). Omit it to use " +
-    "the supported library holding the most tracks.";
+    "the supported library holding the most tracks. If two supported libraries hold " +
+    "the same most tracks -- what a USB drive and its copy on the computer produce -- " +
+    "a read still picks one, but a WRITE refuses with ambiguous_library listing both, " +
+    "since the choice decides which disk changes; ask the user which, then pass it here.";
 export const LibraryArg = z.string().min(1).optional().describe(LIBRARY_ARG_DESCRIPTION);
 /**
  * The default when no `library` was given: the supported library with the
@@ -47,6 +50,55 @@ export function pickDefaultLibrary(libs) {
     }
     return best ?? libs[0] ?? null;
 }
+/**
+ * The supported libraries tied for the default pick -- more than one holding
+ * the same, highest track count. Empty when the default is unambiguous, which
+ * includes the single-library case every DJ starts from.
+ *
+ * A tie is not an exotic shape: it is what a USB drive and its copy on the
+ * computer produce, and they tie *because* one is a copy of the other.
+ * Measured 2026-09-01, both real libraries reported 257 tracks.
+ *
+ * For a read, either answer is very nearly the same answer -- the two are
+ * copies -- so `pickDefaultLibrary` keeps choosing, and a read never has to
+ * name a library it does not care about. For a write the choice decides which
+ * physical disk changes, and one of them is the drive the DJ performs from.
+ * Hence: reads choose, writes refuse. Callers wanting the strict behaviour
+ * check this first.
+ *
+ * Skips unsupported libraries for the same reason `pickDefaultLibrary` does:
+ * one can never be chosen while a supported library exists, so it is not a
+ * competing candidate and must not make a write refuse.
+ */
+export function defaultLibraryTies(libs) {
+    const supported = libs.filter((l) => l.supported);
+    if (supported.length < 2)
+        return [];
+    const best = Math.max(...supported.map((l) => l.trackCount ?? -1));
+    const tied = supported.filter((l) => (l.trackCount ?? -1) === best);
+    return tied.length > 1 ? tied : [];
+}
+/**
+ * The refusal for an ambiguous default on a write.
+ *
+ * Every candidate is named, with its track count, because the caller has to
+ * pick one and cannot do that from "it was ambiguous" -- the same reason
+ * get_playlist_tracks lists candidates for an ambiguous playlist name.
+ *
+ * The list goes in `message`, never in `detail`. This is only ever returned
+ * from a write tool, and on that path `detail` carries exactly
+ * `"not_committed"` or `"committed_unverified"` -- a client reads it to
+ * decide whether its library changed. Prose there would break that read for
+ * the one error whose answer is least in doubt: nothing was opened, let alone
+ * written.
+ */
+export function ambiguousLibrary(tied) {
+    const list = tied.map((l) => `${l.uuid} -- ${redactPath(l.path)} (${l.trackCount} tracks)`).join("; ");
+    return err("ambiguous_library", `More than one library holds the most tracks, so there is no default to write to: ${list}. ` +
+        `Nothing was written. ASK which one to write to, then retry with \`library\` set -- ` +
+        `do not choose for them. These are usually a USB drive and its copy on the computer, ` +
+        `and one of them may be the drive they perform from.`, { detail: "not_committed" });
+}
 /**
  * Resolves a caller-supplied `library` value: uuid first, then filesystem
  * path. Returns null when it matches neither -- the caller decides what

package/dist/paths.d.ts

@@ -19,6 +19,17 @@ export declare function libraryCandidates(root: string): string[];
  * shipped to a model provider, so the home prefix is folded to `~` by default.
  */
 export declare function redactPath(p: string): string;
+/**
+ * redactPath for a URI. A uri carries its path after a scheme and usually
+ * percent-encoded -- the home directory shows up as `%2FUsers%2F<name>`, not
+ * as a leading `/Users/<name>` -- so redactPath's prefix check would never fire
+ * on one, and a "redacted" uri would leak exactly what redaction is there to
+ * hide. Folds every occurrence, raw or encoded, either case of hex digit since
+ * encoders differ. Only a whole path component: the home directory must be
+ * followed by a separator or the end, so a sibling account whose name merely
+ * starts the same is left alone.
+ */
+export declare function redactUri(u: string): string;
 /**
  * The inverse of redactPath, for values coming back *in*. Every library path
  * this server reports has been through redactPath, so the most obvious way

package/dist/paths.js

@@ -34,6 +34,26 @@ export function redactPath(p) {
     const home = homedir();
     return p === home || p.startsWith(home + "/") ? "~" + p.slice(home.length) : p;
 }
+/**
+ * redactPath for a URI. A uri carries its path after a scheme and usually
+ * percent-encoded -- the home directory shows up as `%2FUsers%2F<name>`, not
+ * as a leading `/Users/<name>` -- so redactPath's prefix check would never fire
+ * on one, and a "redacted" uri would leak exactly what redaction is there to
+ * hide. Folds every occurrence, raw or encoded, either case of hex digit since
+ * encoders differ. Only a whole path component: the home directory must be
+ * followed by a separator or the end, so a sibling account whose name merely
+ * starts the same is left alone.
+ */
+export function redactUri(u) {
+    const home = homedir();
+    if (!home || home === "/")
+        return u;
+    const esc = (x) => x.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const raw = new RegExp(`${esc(home)}(?=/|$)`, "g");
+    const encoded = esc(encodeURIComponent(home)).replace(/%([0-9A-F])([0-9A-F])/g, (_, a, b) => `%[${a}${a.toLowerCase()}][${b}${b.toLowerCase()}]`);
+    const enc = new RegExp(`${encoded}(?=%2[Ff]|$)`, "g");
+    return u.replace(raw, "~").replace(enc, "~");
+}
 /**
  * The inverse of redactPath, for values coming back *in*. Every library path
  * this server reports has been through redactPath, so the most obvious way

package/dist/playlists.d.ts

@@ -1,4 +1,4 @@
-import { type EngineError } from "./errors.js";
+import { type EngineError, type ErrorCode } from "./errors.js";
 import type { QueryProcess } from "./proc/query-client.js";
 /**
  * Engine stores both playlist order and playlist-entry order as singly
@@ -191,6 +191,16 @@ export interface PlaylistSelector {
 export interface SelectorNames {
     id: string;
     name: string;
+    /**
+     * The code for "this library has no such playlist", when the caller has a
+     * more accurate one than the default `invalid_argument`. The write tools
+     * pass `playlist_not_found`, which their own store functions already
+     * return for an id that reaches them -- without this, that code was
+     * unreachable through MCP, because resolution runs first and every miss
+     * came back as invalid_argument. Ambiguity is never reported through this:
+     * a name matching several playlists really is a problem with the argument.
+     */
+    notFound?: ErrorCode;
 }
 export interface ResolvedPlaylist {
     playlist: PlaylistItem;
@@ -205,10 +215,14 @@ export interface ResolvedPlaylist {
  * whole function exists to prevent. The error names every candidate with its
  * id and its full path, so the retry is a copy-paste rather than a guess.
  *
- * Deliberately reuses `invalid_argument` rather than adding an error code:
- * the taxonomy is closed (see errors.ts), and "the playlist you named is not
- * in this library" is a problem with the argument, reported the same way an
- * unknown field name is -- with the recognised values in `detail`.
+ * Reuses `invalid_argument` by default rather than adding an error code: the
+ * taxonomy is closed (see errors.ts), and for a reader "the playlist you
+ * named is not in this library" is a problem with the argument, reported the
+ * same way an unknown field name is -- with the recognised values in
+ * `detail`. A caller that already owns a more accurate code for that one
+ * case passes it as `names.notFound`; the write tools do, so their documented
+ * `playlist_not_found` is what a client actually sees. Ambiguity is never
+ * reported through it.
  */
 export declare function resolvePlaylist(qp: QueryProcess, sel: PlaylistSelector, names?: SelectorNames): Promise<ResolvedPlaylist | EngineError>;
 /** One entry of a playlist, in playlist order. */