diff --git a/docs/superpowers/plans/2026-07-06-save-load-playlist.md b/docs/superpowers/plans/2026-07-06-save-load-playlist.md
new file mode 100644
index 0000000..f625d7d
--- /dev/null
+++ b/docs/superpowers/plans/2026-07-06-save-load-playlist.md
@@ -0,0 +1,1443 @@
+# Save/Load Playlists + Queue Persistence Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Stop losing the play queue — add named save/load of queues (chat + web), auto-restore-and-resume the live queue across restarts, and an option to make single-song `!play` insert instead of clearing — all behind default-off toggles.
+
+**Architecture:** New SQLite tables (`saved_queues`, `queue_state`) storing song lists as JSON blobs; a per-user + `__shared__` ownership model for saved queues; a new `/api/saved-queues` router; new chat commands; a `PlayQueue.snapshot/restore` pair driven off the existing `stateChange` emit and the `connected` lifecycle event; and a `BotInstance.playSingleSong` seam that both chat `cmdPlay` and the web `/play-song` route funnel through so the `playKeepsQueue` decision lives in one place.
+
+**Tech Stack:** TypeScript (Node 20, ESM `.js` import suffixes), better-sqlite3, Express, Vitest, Vue 3 + Pinia + vue-tsc.
+
+## Global Constraints
+
+- **All three behaviors default OFF.** `savedQueuesEnabled: false`, `playKeepsQueue: false`. No behavior change until an operator opts in.
+- **`savedQueuesEnabled` is admin-controlled** via `POST /api/bot/settings` (gated `requirePermission("bot.manage")`). When false: chat save/load/queues reply `"此功能未启用"`; `/api/saved-queues/*` returns 403; WebUI page hidden; NO snapshotting; NO auto-restore.
+- **Config sanitization mirrors existing flags:** every new config field is coerced with `=== true` on load (like `spotify.enabled`) so a hand-edited/legacy/corrupt `config.json` can never silently enable a feature.
+- **Songs are stored as a JSON `TEXT` blob** — an array of `Omit<QueuedSong, "url">` (URLs are re-resolved lazily). Corrupt blobs degrade to `[]`, never throw into a route or the restore path.
+- **`SHARED_QUEUE_OWNER = "__shared__"`** — reserved owner id for chat-saved / shared queues; can never collide with a real user id.
+- **Caps:** ≤ 50 saved queues per owner; ≤ 1000 songs per saved queue.
+- **ESM imports** use the `.js` suffix even for `.ts` files. New source files get colocated `*.test.ts`.
+- **Verification per task:** `npx vitest run <file> --no-file-parallelism`. Final gate (Task 13): full `npx vitest run --no-file-parallelism`, `npx tsc --noEmit`, and `cd web && npm run build`.
+- **Branch:** all work on `feat/issue-119-saved-queues` (already created off `main`).
+- **Play-history attribution:** loaded songs are tagged with the loader's `requestedBy` (integrates with #121).
+
+---
+
+## File Structure
+
+**Create:**
+- `src/web/api/saved-queues.ts` — the `/api/saved-queues` router (Feature 1).
+- `src/web/api/saved-queues.test.ts` — its tests.
+- `web/src/views/SavedQueues.vue` — the WebUI page (Feature 1).
+- `web/src/composables/useSavedQueues.ts` — API composable.
+- `web/src/composables/savedQueues.ts` + `savedQueues.test.ts` — pure list/dedup helper (unit-tested).
+
+**Modify:**
+- `src/data/config.ts` — two new `BotConfig` flags + defaults + load sanitization.
+- `src/data/config.test.ts` — sanitization tests.
+- `src/web/api/bot.ts` — settings GET/POST echo the two flags.
+- `src/web/api/bot.test.ts` — settings persistence tests.
+- `web/src/views/Settings.vue` — two toggles in 行为设置; nav gating.
+- `src/bot/instance.ts` — `playSingleSong`, chat `!save`/`!load`/`!queues`, help text, snapshot/restore wiring, `SHARED_QUEUE_OWNER` usage.
+- `src/bot/instance.test.ts` — command + playKeepsQueue + snapshot/restore tests.
+- `src/web/api/player.ts` — `/play-song` funnels through `bot.playSingleSong`.
+- `src/data/database.ts` — `saved_queues` + `queue_state` tables, migrations, methods, interfaces, `SHARED_QUEUE_OWNER` export.
+- `src/data/database.test.ts` — DB method tests.
+- `src/audio/queue.ts` — `snapshot()` / `restore()`.
+- `src/audio/queue.test.ts` — round-trip tests.
+- `src/web/server.ts` — mount the saved-queues router.
+- `README.md` — commands, toggles, caveats.
+
+---
+
+## Stage 1 — Config + gates + Settings UI
+
+### Task 1: Config flags + load sanitization
+
+**Files:**
+- Modify: `src/data/config.ts` (`BotConfig`, `getDefaultConfig`, `loadConfig`)
+- Test: `src/data/config.test.ts`
+
+**Interfaces:**
+- Produces: `BotConfig.savedQueuesEnabled: boolean`, `BotConfig.playKeepsQueue: boolean` (both default `false`).
+
+- [ ] **Step 1: Write the failing tests**
+
+Add to `src/data/config.test.ts`:
+
+```ts
+import { describe, it, expect } from "vitest";
+import { getDefaultConfig, loadConfig } from "./config.js";
+import { writeFileSync, mkdtempSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+describe("savedQueues/playKeepsQueue config", () => {
+  it("defaults both flags to false", () => {
+    const c = getDefaultConfig();
+    expect(c.savedQueuesEnabled).toBe(false);
+    expect(c.playKeepsQueue).toBe(false);
+  });
+
+  it("coerces non-boolean values to false on load", () => {
+    const dir = mkdtempSync(join(tmpdir(), "cfg-"));
+    const p = join(dir, "config.json");
+    writeFileSync(p, JSON.stringify({ savedQueuesEnabled: "yes", playKeepsQueue: 1 }));
+    const c = loadConfig(p);
+    expect(c.savedQueuesEnabled).toBe(false);
+    expect(c.playKeepsQueue).toBe(false);
+  });
+
+  it("preserves true when explicitly enabled", () => {
+    const dir = mkdtempSync(join(tmpdir(), "cfg-"));
+    const p = join(dir, "config.json");
+    writeFileSync(p, JSON.stringify({ savedQueuesEnabled: true, playKeepsQueue: true }));
+    const c = loadConfig(p);
+    expect(c.savedQueuesEnabled).toBe(true);
+    expect(c.playKeepsQueue).toBe(true);
+  });
+});
+```
+
+- [ ] **Step 2: Run to verify it fails**
+
+Run: `npx vitest run src/data/config.test.ts --no-file-parallelism`
+Expected: FAIL — `savedQueuesEnabled` is `undefined`.
+
+- [ ] **Step 3: Implement**
+
+In `src/data/config.ts`, add to the `BotConfig` interface (near `localAudioEnabled`):
+
+```ts
+  /** Enable named save/load of queues + auto-restore of the live queue across restart. Admin-controlled. */
+  savedQueuesEnabled: boolean;
+  /** When true, single-song !play inserts-and-plays instead of clearing the queue. */
+  playKeepsQueue: boolean;
+```
+
+In `getDefaultConfig()` return object (near `localAudioEnabled: true`):
+
+```ts
+    savedQueuesEnabled: false,
+    playKeepsQueue: false,
+```
+
+In `loadConfig()`, inside the final `return { ...defaults, ...partial, ... }` block, override both with strict coercion so junk can't enable them. Add these before the `return`:
+
+```ts
+    const savedQueuesEnabled = partial.savedQueuesEnabled === true;
+    const playKeepsQueue = partial.playKeepsQueue === true;
+```
+
+and add `savedQueuesEnabled, playKeepsQueue,` to the returned object (after `spotify,`).
+
+- [ ] **Step 4: Run to verify it passes**
+
+Run: `npx vitest run src/data/config.test.ts --no-file-parallelism`
+Expected: PASS.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/data/config.ts src/data/config.test.ts
+git commit -m "feat(config): add savedQueuesEnabled + playKeepsQueue flags (default off) (#119)"
+```
+
+---
+
+### Task 2: Settings API round-trips the two flags
+
+**Files:**
+- Modify: `src/web/api/bot.ts` (GET `/settings`, POST `/settings`)
+- Test: `src/web/api/bot.test.ts`
+
+**Interfaces:**
+- Consumes: `BotConfig.savedQueuesEnabled`, `BotConfig.playKeepsQueue`.
+- Produces: settings GET/POST include `savedQueuesEnabled`, `playKeepsQueue`.
+
+- [ ] **Step 1: Write the failing test**
+
+Add to `src/web/api/bot.test.ts` (follow the existing settings-test setup in that file — reuse its `app`/`request` harness and admin auth). Add a test:
+
+```ts
+it("persists savedQueuesEnabled and playKeepsQueue", async () => {
+  const res = await adminRequest()
+    .post("/api/bot/settings")
+    .send({ savedQueuesEnabled: true, playKeepsQueue: true });
+  expect(res.status).toBe(200);
+  expect(res.body.savedQueuesEnabled).toBe(true);
+  expect(res.body.playKeepsQueue).toBe(true);
+
+  const get = await adminRequest().get("/api/bot/settings");
+  expect(get.body.savedQueuesEnabled).toBe(true);
+  expect(get.body.playKeepsQueue).toBe(true);
+});
+
+it("ignores non-boolean flag values", async () => {
+  const res = await adminRequest()
+    .post("/api/bot/settings")
+    .send({ savedQueuesEnabled: "nope" });
+  expect(res.body.savedQueuesEnabled).toBe(false); // unchanged from default
+});
+```
+
+(If `bot.test.ts` lacks an `adminRequest()` helper, mirror the auth setup already used by the existing `POST /settings` tests in that file.)
+
+- [ ] **Step 2: Run to verify it fails**
+
+Run: `npx vitest run src/web/api/bot.test.ts --no-file-parallelism`
+Expected: FAIL — response lacks the fields.
+
+- [ ] **Step 3: Implement**
+
+In `src/web/api/bot.ts`:
+
+In BOTH the GET `/settings` response and the POST `/settings` response objects, add:
+
+```ts
+      savedQueuesEnabled: config.savedQueuesEnabled,
+      playKeepsQueue: config.playKeepsQueue,
+```
+
+In the POST `/settings` handler, after the `hasLocalAudioEnabled` block, add:
+
+```ts
+    if (typeof req.body.savedQueuesEnabled === "boolean") {
+      config.savedQueuesEnabled = req.body.savedQueuesEnabled;
+    }
+    if (typeof req.body.playKeepsQueue === "boolean") {
+      config.playKeepsQueue = req.body.playKeepsQueue;
+    }
+```
+
+(No per-bot push needed: `BotInstance.this.config` is the same object reference as this `config` — see `instance.ts:171 this.config = options.config`. **Verify** during implementation that the config passed to `createBotRouter` and to each `BotInstance` is the same reference; it is threaded from `index.ts`. Both booleans are read live from `this.config`.)
+
+- [ ] **Step 4: Run to verify it passes**
+
+Run: `npx vitest run src/web/api/bot.test.ts --no-file-parallelism`
+Expected: PASS.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/web/api/bot.ts src/web/api/bot.test.ts
+git commit -m "feat(settings): round-trip savedQueuesEnabled + playKeepsQueue (#119)"
+```
+
+---
+
+### Task 3: Settings.vue toggles
+
+**Files:**
+- Modify: `web/src/views/Settings.vue` (行为设置 section + the settings load/save payload)
+
+**Interfaces:**
+- Consumes: settings API fields `savedQueuesEnabled`, `playKeepsQueue`.
+
+- [ ] **Step 1: Locate the 行为设置 toggles**
+
+Find where `localAudioEnabled` / `autoPauseOnEmpty` are rendered (a labeled toggle bound to a reactive settings object) and where the settings object is loaded from `GET /api/bot/settings` and sent by `POST /api/bot/settings`.
+
+- [ ] **Step 2: Add the reactive fields**
+
+Add `savedQueuesEnabled` and `playKeepsQueue` to the settings reactive object's initial shape (default `false`), to the GET hydration, and to the POST payload — exactly mirroring how `localAudioEnabled` is wired.
+
+- [ ] **Step 3: Add two toggle rows**
+
+In the 行为设置 section, after the local-audio toggle, add two toggle rows mirroring the existing markup:
+
+```html
+<!-- 保存/加载播放清单 + 重启恢复队列（管理员开关，默认关闭） -->
+<label class="setting-row">
+  <span>保存/加载播放清单（含重启后自动恢复队列）</span>
+  <input type="checkbox" v-model="settings.savedQueuesEnabled" />
+</label>
+<!-- 单曲直接播放不清空队列 -->
+<label class="setting-row">
+  <span>直接播放单曲时不清空队列（播完继续原队列）</span>
+  <input type="checkbox" v-model="settings.playKeepsQueue" />
+</label>
+```
+
+(Match the actual class names / toggle component used by neighboring rows.)
+
+- [ ] **Step 4: Build check**
+
+Run: `cd web && npm run build`
+Expected: build succeeds (vue-tsc clean).
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add web/src/views/Settings.vue
+git commit -m "feat(web): saved-queues + play-keeps-queue toggles in 行为设置 (#119)"
+```
+
+---
+
+## Stage 2 — Feature 3: `playKeepsQueue`
+
+### Task 4: `BotInstance.playSingleSong` + route `cmdPlay` through it
+
+**Files:**
+- Modify: `src/bot/instance.ts` (`cmdPlay` at ~909; add `playSingleSong`)
+- Test: `src/bot/instance.test.ts`
+
+**Interfaces:**
+- Consumes: `this.config.playKeepsQueue`, `this.queue` (`PlayQueue`), `this.withRequester`, `this.disableFmMode`, `this.resolveAndPlay`, `this.cleanupQueuedLocalSongs`.
+- Produces: `async playSingleSong(song: QueuedSong, requesterName?: string): Promise<boolean>` — public (called by the web route in Task 5).
+
+- [ ] **Step 1: Write the failing tests**
+
+Add to `src/bot/instance.test.ts` (reuse the file's existing BotInstance harness that stubs the player/queue/providers). Two tests:
+
+```ts
+describe("playSingleSong / playKeepsQueue", () => {
+  it("clears the queue when playKeepsQueue is false (default)", async () => {
+    const bot = makeBot({ playKeepsQueue: false }); // helper sets config flag
+    const q = bot.getQueueManager();
+    q.add({ id: "a", name: "A", artist: "", album: "", platform: "netease", coverUrl: "", duration: 10 });
+    q.play();
+    await bot.playSingleSong(
+      { id: "b", name: "B", artist: "", album: "", platform: "netease", coverUrl: "", duration: 10 },
+      "alice",
+    );
+    expect(q.list().map((s) => s.id)).toEqual(["b"]);
+    expect(q.current()?.id).toBe("b");
+  });
+
+  it("inserts-after-current and keeps the queue when playKeepsQueue is true", async () => {
+    const bot = makeBot({ playKeepsQueue: true });
+    const q = bot.getQueueManager();
+    q.add({ id: "a", name: "A", artist: "", album: "", platform: "netease", coverUrl: "", duration: 10 });
+    q.add({ id: "c", name: "C", artist: "", album: "", platform: "netease", coverUrl: "", duration: 10 });
+    q.play(); // current = a (index 0)
+    await bot.playSingleSong(
+      { id: "b", name: "B", artist: "", album: "", platform: "netease", coverUrl: "", duration: 10 },
+      "alice",
+    );
+    expect(q.list().map((s) => s.id)).toEqual(["a", "b", "c"]);
+    expect(q.current()?.id).toBe("b");
+    expect(q.current()?.requestedBy).toBe("alice");
+  });
+});
+```
+
+(If `instance.test.ts` has no `makeBot` helper, add a minimal factory that constructs a `BotInstance` with a stub player whose `resolveAndPlay` succeeds — mirror the existing construction in that file's other describe blocks. `resolveAndPlay` can be spied to resolve `true` without real resolution.)
+
+- [ ] **Step 2: Run to verify it fails**
+
+Run: `npx vitest run src/bot/instance.test.ts -t "playSingleSong" --no-file-parallelism`
+Expected: FAIL — `playSingleSong` is not a function.
+
+- [ ] **Step 3: Implement `playSingleSong`**
+
+Add to `BotInstance` (public method, near `cmdPlay`):
+
+```ts
+  /**
+   * Play a single resolved song immediately. Honors config.playKeepsQueue:
+   * when true (and the queue isn't empty), insert-after-current + jump so the
+   * rest of the queue survives and continues after this track; otherwise clear
+   * the queue and play only this song (legacy behavior). Shared by chat !play
+   * and the web /play-song route so the toggle lives in one place.
+   */
+  async playSingleSong(song: QueuedSong, requesterName?: string): Promise<boolean> {
+    const s = this.withRequester(song, requesterName);
+    if (this.config.playKeepsQueue && !this.queue.isEmpty()) {
+      // Take manual control (stop FM auto-refill) but KEEP the queued songs.
+      const insertedAt =
+        this.queue.getCurrentIndex() < 0
+          ? this.queue.size()
+          : this.queue.getCurrentIndex() + 1;
+      this.disableFmMode();
+      this.queue.addNext(s);
+      this.queue.playAt(insertedAt);
+    } else {
+      this.queue.clear();
+      this.disableFmMode();
+      this.queue.add(s);
+      this.queue.play();
+      // Only the clear path replaces the queue, so only it sweeps prior local uploads.
+      this.cleanupQueuedLocalSongs?.("queue_replaced");
+    }
+    this.player.resetFailures();
+    return this.resolveAndPlay(this.queue.current()!);
+  }
+```
+
+Then in `cmdPlay`, replace the clear+add+play block:
+
+```ts
+    this.queue.clear();
+    this.disableFmMode();
+    this.queue.add(this.withRequester(song0, requesterName));
+    this.queue.play();
+    // Reset failure counter on user-initiated play
+    ...resolveAndPlay(...)
+```
+
+with:
+
+```ts
+    await this.playSingleSong(song0, requesterName);
+```
+
+(Preserve the surrounding `cmdPlay` return string, e.g. `Now playing: ...`, and any `resetFailures` already inside `playSingleSong`. Remove the now-duplicated `resolveAndPlay` call from `cmdPlay`.)
+
+- [ ] **Step 4: Run to verify it passes**
+
+Run: `npx vitest run src/bot/instance.test.ts -t "playSingleSong" --no-file-parallelism`
+Expected: PASS. Then run the whole file to catch regressions:
+Run: `npx vitest run src/bot/instance.test.ts --no-file-parallelism`
+Expected: PASS.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/bot/instance.ts src/bot/instance.test.ts
+git commit -m "feat(player): playSingleSong seam honoring playKeepsQueue (#119)"
+```
+
+---
+
+### Task 5: Web `/play-song` funnels through `playSingleSong`
+
+**Files:**
+- Modify: `src/web/api/player.ts` (`/:botId/play-song` at ~461)
+- Test: `src/web/api/player.test.ts` (or the existing player-route test file)
+
+**Interfaces:**
+- Consumes: `bot.playSingleSong(song, requesterName)` from Task 4.
+
+- [ ] **Step 1: Write the failing test**
+
+In the player-route test file, add a test that with `playKeepsQueue = true` a `/play-song` call preserves an existing queued song. Mirror the existing route-test harness (a fake `bot` exposing `getQueueManager`, `playSingleSong`, `runExclusive`). Assert the fake `bot.playSingleSong` is invoked with the song + requester and the pre-existing queue entry is retained. If the route tests use a real `BotInstance` stub, assert queue contents as in Task 4.
+
+```ts
+it("/play-song routes through playSingleSong (keeps queue when enabled)", async () => {
+  const bot = makeRouteBot({ playKeepsQueue: true });
+  bot.getQueueManager().add({ id: "a", platform: "netease", name: "A", artist: "", album: "", coverUrl: "", duration: 5 });
+  bot.getQueueManager().play();
+  await request(app).post(`/api/player/${BOT}/play-song`).send({ song: { id: "b", platform: "netease", name: "B" } });
+  expect(bot.getQueueManager().list().map((s) => s.id)).toContain("a");
+  expect(bot.getQueueManager().current()?.id).toBe("b");
+});
+```
+
+- [ ] **Step 2: Run to verify it fails**
+
+Run: `npx vitest run src/web/api/player.test.ts --no-file-parallelism`
+Expected: FAIL (route still clears).
+
+- [ ] **Step 3: Implement**
+
+Replace the body of `/:botId/play-song` (the `queue.clear(); queue.add(...); queue.play(); resolveAndPlay; cleanupQueuedLocalSongs` block) with a single call, wrapped in `runExclusive` for consistency with `/play-now-song`:
+
+```ts
+      const body = await bot.runExclusive(async () => {
+        const ok = await bot.playSingleSong(
+          { ...song },
+          requesterName(req),
+        );
+        return ok
+          ? { ok: true, message: `正在播放：${song.name || "Unknown"} - ${song.artist || "Unknown"}` }
+          : { ok: false, message: `无法播放「${song.name || song.id}」（区域/版权限制）` };
+      });
+      res.json(body);
+```
+
+(The `cleanupQueuedLocalSongs` sweep now lives inside `playSingleSong`'s clear branch — do NOT also call it here, or it would delete retained local uploads in keep-queue mode.)
+
+- [ ] **Step 4: Run to verify it passes**
+
+Run: `npx vitest run src/web/api/player.test.ts --no-file-parallelism`
+Expected: PASS.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/web/api/player.ts src/web/api/player.test.ts
+git commit -m "feat(web): /play-song honors playKeepsQueue via playSingleSong (#119)"
+```
+
+---
+
+## Stage 3 — Feature 1: named save/load
+
+### Task 6: DB — `saved_queues` table + methods
+
+**Files:**
+- Modify: `src/data/database.ts` (interfaces, `migrateSchema`, `initTables`, `createDatabase` body, `BotDatabase`)
+- Test: `src/data/database.test.ts`
+
+**Interfaces:**
+- Produces (exports + `BotDatabase` methods):
+
+```ts
+export const SHARED_QUEUE_OWNER = "__shared__";
+export type StoredSong = Omit<QueuedSong, "url">;           // imported from ../audio/queue.js
+export interface SavedQueueMeta {
+  id: number; ownerId: string; name: string; songCount: number;
+  createdAt: string; updatedAt: string;
+}
+export interface SavedQueue extends SavedQueueMeta { songs: StoredSong[]; }
+
+// on BotDatabase:
+saveQueue(ownerId: string, name: string, songs: StoredSong[]): SavedQueue;   // upsert by (ownerId,name)
+listSavedQueues(ownerId: string, includeShared: boolean): SavedQueueMeta[];
+getSavedQueue(id: number): SavedQueue | null;
+deleteSavedQueue(id: number): boolean;
+```
+
+- [ ] **Step 1: Write the failing tests**
+
+Add to `src/data/database.test.ts`:
+
+```ts
+import { SHARED_QUEUE_OWNER } from "./database.js";
+
+const song = (id: string) => ({ id, name: id, artist: "", album: "", platform: "netease" as const, coverUrl: "", duration: 1 });
+
+describe("saved_queues", () => {
+  it("upserts by (ownerId,name) and returns songs", () => {
+    const db = createDatabase(":memory:");
+    db.saveQueue("u1", "night", [song("a"), song("b")]);
+    const again = db.saveQueue("u1", "night", [song("c")]); // overwrite
+    expect(again.songCount).toBe(1);
+    const list = db.listSavedQueues("u1", false);
+    expect(list).toHaveLength(1);
+    const full = db.getSavedQueue(again.id)!;
+    expect(full.songs.map((s) => s.id)).toEqual(["c"]);
+    db.close();
+  });
+
+  it("lists own + shared when includeShared, own-only otherwise", () => {
+    const db = createDatabase(":memory:");
+    db.saveQueue("u1", "mine", [song("a")]);
+    db.saveQueue(SHARED_QUEUE_OWNER, "party", [song("b")]);
+    expect(db.listSavedQueues("u1", false).map((q) => q.name)).toEqual(["mine"]);
+    expect(db.listSavedQueues("u1", true).map((q) => q.name).sort()).toEqual(["mine", "party"]);
+    db.close();
+  });
+
+  it("caps songs at 1000 and queues at 50", () => {
+    const db = createDatabase(":memory:");
+    expect(() => db.saveQueue("u1", "big", Array.from({ length: 1001 }, (_, i) => song("s" + i)))).toThrow(/1000/);
+    for (let i = 0; i < 50; i++) db.saveQueue("u1", "q" + i, [song("a")]);
+    expect(() => db.saveQueue("u1", "q50", [song("a")])).toThrow(/50/);
+    db.close();
+  });
+
+  it("deletes and degrades a corrupt blob to empty", () => {
+    const db = createDatabase(":memory:");
+    const q = db.saveQueue("u1", "x", [song("a")]);
+    db.db.prepare("UPDATE saved_queues SET songs='not json' WHERE id=?").run(q.id);
+    expect(db.getSavedQueue(q.id)!.songs).toEqual([]);
+    expect(db.deleteSavedQueue(q.id)).toBe(true);
+    expect(db.getSavedQueue(q.id)).toBeNull();
+    db.close();
+  });
+});
+```
+
+- [ ] **Step 2: Run to verify it fails**
+
+Run: `npx vitest run src/data/database.test.ts --no-file-parallelism`
+Expected: FAIL — `saveQueue` undefined / `SHARED_QUEUE_OWNER` undefined.
+
+- [ ] **Step 3: Implement**
+
+At the top of `src/data/database.ts` add the import + exports:
+
+```ts
+import type { QueuedSong } from "../audio/queue.js";
+
+export const SHARED_QUEUE_OWNER = "__shared__";
+export const MAX_SAVED_QUEUES = 50;
+export const MAX_QUEUE_SONGS = 1000;
+export type StoredSong = Omit<QueuedSong, "url">;
+export interface SavedQueueMeta {
+  id: number; ownerId: string; name: string; songCount: number;
+  createdAt: string; updatedAt: string;
+}
+export interface SavedQueue extends SavedQueueMeta { songs: StoredSong[]; }
+```
+
+Add the four methods to the `BotDatabase` interface (signatures above).
+
+In `initTables`, add the table (inside the `db.exec` template):
+
+```sql
+    CREATE TABLE IF NOT EXISTS saved_queues (
+      id        INTEGER PRIMARY KEY AUTOINCREMENT,
+      ownerId   TEXT NOT NULL,
+      name      TEXT NOT NULL,
+      songs     TEXT NOT NULL,
+      songCount INTEGER NOT NULL DEFAULT 0,
+      createdAt TEXT NOT NULL DEFAULT (datetime('now')),
+      updatedAt TEXT NOT NULL DEFAULT (datetime('now')),
+      UNIQUE(ownerId, name)
+    );
+    CREATE INDEX IF NOT EXISTS idx_saved_queues_ownerId ON saved_queues(ownerId);
+```
+
+(No `migrateSchema` entry needed — `CREATE TABLE IF NOT EXISTS` handles fresh + existing DBs.)
+
+In `createDatabase`, implement the methods (add prepared statements + return-object methods). A safe song-parse helper:
+
+```ts
+  const parseSongs = (raw: string): StoredSong[] => {
+    try { const v = JSON.parse(raw); return Array.isArray(v) ? v : []; }
+    catch { return []; }
+  };
+  const rowToMeta = (r: any): SavedQueueMeta => ({
+    id: r.id, ownerId: r.ownerId, name: r.name, songCount: r.songCount,
+    createdAt: r.createdAt, updatedAt: r.updatedAt,
+  });
+```
+
+Methods on the returned object:
+
+```ts
+    saveQueue(ownerId, name, songs) {
+      if (songs.length > MAX_QUEUE_SONGS) throw new Error(`queue exceeds ${MAX_QUEUE_SONGS} songs`);
+      const stripped = songs.map(({ url: _url, ...s }: any) => s);
+      const json = JSON.stringify(stripped);
+      const existing = db.prepare("SELECT id FROM saved_queues WHERE ownerId=? AND name=?").get(ownerId, name) as { id: number } | undefined;
+      if (!existing) {
+        const count = (db.prepare("SELECT COUNT(*) c FROM saved_queues WHERE ownerId=?").get(ownerId) as { c: number }).c;
+        if (count >= MAX_SAVED_QUEUES) throw new Error(`owner exceeds ${MAX_SAVED_QUEUES} saved queues`);
+      }
+      db.prepare(`
+        INSERT INTO saved_queues (ownerId, name, songs, songCount)
+        VALUES (@ownerId, @name, @songs, @songCount)
+        ON CONFLICT(ownerId, name) DO UPDATE SET
+          songs=excluded.songs, songCount=excluded.songCount, updatedAt=datetime('now')
+      `).run({ ownerId, name, songs: json, songCount: stripped.length });
+      const row = db.prepare("SELECT * FROM saved_queues WHERE ownerId=? AND name=?").get(ownerId, name);
+      return { ...rowToMeta(row), songs: stripped };
+    },
+    listSavedQueues(ownerId, includeShared) {
+      const rows = includeShared
+        ? db.prepare("SELECT id,ownerId,name,songCount,createdAt,updatedAt FROM saved_queues WHERE ownerId=? OR ownerId=? ORDER BY updatedAt DESC").all(ownerId, SHARED_QUEUE_OWNER)
+        : db.prepare("SELECT id,ownerId,name,songCount,createdAt,updatedAt FROM saved_queues WHERE ownerId=? ORDER BY updatedAt DESC").all(ownerId);
+      return (rows as any[]).map(rowToMeta);
+    },
+    getSavedQueue(id) {
+      const row = db.prepare("SELECT * FROM saved_queues WHERE id=?").get(id) as any;
+      if (!row) return null;
+      return { ...rowToMeta(row), songs: parseSongs(row.songs) };
+    },
+    deleteSavedQueue(id) {
+      return db.prepare("DELETE FROM saved_queues WHERE id=?").run(id).changes > 0;
+    },
+```
+
+- [ ] **Step 4: Run to verify it passes**
+
+Run: `npx vitest run src/data/database.test.ts --no-file-parallelism`
+Expected: PASS.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/data/database.ts src/data/database.test.ts
+git commit -m "feat(db): saved_queues table + save/list/get/delete with caps (#119)"
+```
+
+---
+
+### Task 7: `/api/saved-queues` router + mount + feature gate
+
+**Files:**
+- Create: `src/web/api/saved-queues.ts`, `src/web/api/saved-queues.test.ts`
+- Modify: `src/web/server.ts` (import + mount at `/api/saved-queues`)
+
+**Interfaces:**
+- Consumes: `BotDatabase` saved-queue methods (Task 6); `BotManager` (`getBot`); a `() => boolean` feature-gate reading `config.savedQueuesEnabled`; `bot.getQueueManager()`, `bot.playSingleSong`/queue load helpers.
+- Produces: `createSavedQueuesRouter(database, botManager, isEnabled, logger): Router`.
+
+- [ ] **Step 1: Write the failing tests**
+
+Create `src/web/api/saved-queues.test.ts`:
+
+```ts
+import { describe, it, expect, beforeEach } from "vitest";
+import express from "express";
+import request from "supertest";
+import { createDatabase } from "../../data/database.js";
+import { createSavedQueuesRouter } from "./saved-queues.js";
+
+function mount(enabled: boolean) {
+  const db = createDatabase(":memory:");
+  const bot = {
+    getQueueManager: () => ({ list: () => [{ id: "a", name: "A", artist: "", album: "", platform: "netease", coverUrl: "", duration: 1 }] }),
+    loadSavedQueue: (_songs: any[], _mode: string, _by?: string) => {},
+  };
+  const botManager = { getBot: (_id: string) => bot } as any;
+  const app = express();
+  app.use(express.json());
+  app.use((req, _res, next) => { (req as any).user = { id: "u1", username: "alice" }; next(); });
+  app.use("/api/saved-queues", createSavedQueuesRouter(db, botManager, () => enabled, console as any));
+  return { app, db };
+}
+
+describe("saved-queues router", () => {
+  it("403s all routes when feature disabled", async () => {
+    const { app } = mount(false);
+    expect((await request(app).get("/api/saved-queues")).status).toBe(403);
+    expect((await request(app).post("/api/saved-queues").send({ botId: "b", name: "x" })).status).toBe(403);
+  });
+
+  it("saves current queue (private) and lists it", async () => {
+    const { app } = mount(true);
+    const save = await request(app).post("/api/saved-queues").send({ botId: "b", name: "night" });
+    expect(save.status).toBe(200);
+    const list = await request(app).get("/api/saved-queues");
+    expect(list.body.queues.map((q: any) => q.name)).toContain("night");
+  });
+
+  it("saves shared when shared:true and rejects loading another user's private queue", async () => {
+    const { app, db } = mount(true);
+    db.saveQueue("someoneElse", "private", [{ id: "z" } as any]);
+    const other = db.listSavedQueues("someoneElse", false)[0];
+    const load = await request(app).post(`/api/saved-queues/${other.id}/load`).send({ botId: "b", mode: "replace" });
+    expect(load.status).toBe(404);
+  });
+});
+```
+
+- [ ] **Step 2: Run to verify it fails**
+
+Run: `npx vitest run src/web/api/saved-queues.test.ts --no-file-parallelism`
+Expected: FAIL — module not found.
+
+- [ ] **Step 3: Implement the router**
+
+Create `src/web/api/saved-queues.ts`:
+
+```ts
+import { Router } from "express";
+import type { BotDatabase } from "../../data/database.js";
+import { SHARED_QUEUE_OWNER } from "../../data/database.js";
+import type { BotManager } from "../../bot/manager.js";
+import type { Logger } from "../../logger.js";
+
+export function createSavedQueuesRouter(
+  database: BotDatabase,
+  botManager: BotManager,
+  isEnabled: () => boolean,
+  logger: Logger,
+): Router {
+  const router = Router();
+
+  // Feature gate — inert when savedQueuesEnabled is false.
+  router.use((_req, res, next) => {
+    if (!isEnabled()) { res.status(403).json({ error: "此功能未启用" }); return; }
+    next();
+  });
+
+  // GET / — own + shared (meta only)
+  router.get("/", (req, res) => {
+    const userId = (req as any).user.id;
+    res.json({ queues: database.listSavedQueues(userId, true) });
+  });
+
+  // POST / — snapshot the bot's current queue, upsert
+  router.post("/", (req, res) => {
+    const userId = (req as any).user.id;
+    const { botId, name, shared } = req.body ?? {};
+    if (typeof name !== "string" || !name.trim() || !botId) {
+      res.status(400).json({ error: "botId and name are required" }); return;
+    }
+    const bot = botManager.getBot(botId);
+    if (!bot) { res.status(404).json({ error: "bot not found" }); return; }
+    const songs = bot.getQueueManager().list();
+    if (songs.length === 0) { res.status(400).json({ error: "队列为空，无法保存" }); return; }
+    const ownerId = shared === true ? SHARED_QUEUE_OWNER : userId;
+    try {
+      const saved = database.saveQueue(ownerId, name.trim(), songs as any);
+      res.json({ queue: { id: saved.id, ownerId, name: saved.name, songCount: saved.songCount } });
+    } catch (err) {
+      res.status(400).json({ error: (err as Error).message });
+    }
+  });
+
+  // POST /:id/load — replace | append into a bot
+  router.post("/:id/load", async (req, res) => {
+    const userId = (req as any).user.id;
+    const username = (req as any).user.username as string | undefined;
+    const id = parseInt(req.params.id, 10);
+    const { botId, mode } = req.body ?? {};
+    if (Number.isNaN(id) || !botId) { res.status(400).json({ error: "invalid id/botId" }); return; }
+    const sq = database.getSavedQueue(id);
+    if (!sq || (sq.ownerId !== userId && sq.ownerId !== SHARED_QUEUE_OWNER)) {
+      res.status(404).json({ error: "not found" }); return;
+    }
+    const bot = botManager.getBot(botId);
+    if (!bot) { res.status(404).json({ error: "bot not found" }); return; }
+    const loadMode = mode === "append" ? "append" : "replace";
+    await bot.loadSavedQueue(sq.songs, loadMode, username || "游客");
+    res.json({ ok: true, loaded: sq.songs.length, mode: loadMode });
+  });
+
+  // DELETE /:id — own or shared only
+  router.delete("/:id", (req, res) => {
+    const userId = (req as any).user.id;
+    const id = parseInt(req.params.id, 10);
+    const sq = database.getSavedQueue(id);
+    if (!sq || (sq.ownerId !== userId && sq.ownerId !== SHARED_QUEUE_OWNER)) {
+      res.status(404).json({ error: "not found" }); return;
+    }
+    database.deleteSavedQueue(id);
+    logger.info({ userId, id }, "saved queue deleted");
+    res.json({ ok: true });
+  });
+
+  return router;
+}
+```
+
+Add `loadSavedQueue` to `BotInstance` (used here + by chat in Task 8):
+
+```ts
+  /** Load a saved list into this bot's queue. replace: clear + play; append: add to end. */
+  async loadSavedQueue(songs: StoredSong[], mode: "replace" | "append", requesterName?: string): Promise<void> {
+    const tagged = songs.map((s) => this.withRequester(s as QueuedSong, requesterName));
+    if (mode === "replace") {
+      this.queue.clear();
+      this.disableFmMode();
+      for (const s of tagged) this.queue.add(s);
+      this.cleanupQueuedLocalSongs?.("queue_replaced");
+      const first = this.queue.play();
+      this.player.resetFailures();
+      if (first) await this.resolveAndPlay(first);
+    } else {
+      const wasIdle = this.player.getState() === "idle";
+      const startAt = this.queue.size();
+      for (const s of tagged) this.queue.add(s);
+      if (wasIdle && this.queue.size() > 0) {
+        this.queue.playAt(startAt);
+        this.player.resetFailures();
+        await this.resolveAndPlay(this.queue.current()!);
+      }
+    }
+    this.emit("stateChange");
+  }
+```
+
+- [ ] **Step 4: Mount in `server.ts`**
+
+Add import near the other API imports:
+
+```ts
+import { createSavedQueuesRouter } from "./api/saved-queues.js";
+```
+
+Mount alongside favorites (both `requireNotGuest`):
+
+```ts
+  app.use("/api/saved-queues", requireNotGuest, createSavedQueuesRouter(
+    options.database,
+    options.botManager,
+    () => options.config.savedQueuesEnabled,
+    logger,
+  ));
+```
+
+(Confirm the exact names `options.botManager` / `options.config` / `options.database` from the surrounding `createPlayerRouter`/`createFavoritesRouter` mounts.)
+
+- [ ] **Step 5: Run + commit**
+
+Run: `npx vitest run src/web/api/saved-queues.test.ts --no-file-parallelism`
+Expected: PASS.
+
+```bash
+git add src/web/api/saved-queues.ts src/web/api/saved-queues.test.ts src/web/server.ts src/bot/instance.ts
+git commit -m "feat(web): /api/saved-queues router + loadSavedQueue (#119)"
+```
+
+---
+
+### Task 8: Chat commands `!save` / `!load` / `!queues`
+
+**Files:**
+- Modify: `src/bot/instance.ts` (`executeCommand` switch ~604-656, add `cmdSave`/`cmdLoad`/`cmdQueues`, `cmdHelp` ~1361)
+- Test: `src/bot/instance.test.ts`
+
+**Interfaces:**
+- Consumes: `this.database` saved-queue methods, `SHARED_QUEUE_OWNER`, `this.config.savedQueuesEnabled`, `this.loadSavedQueue` (Task 7), `cmd.flags.has("a")` for append.
+
+- [ ] **Step 1: Write the failing tests**
+
+Add to `src/bot/instance.test.ts`:
+
+```ts
+describe("chat save/load/queues", () => {
+  it("replies feature-disabled when savedQueuesEnabled is false", async () => {
+    const bot = makeBot({ savedQueuesEnabled: false });
+    expect(await bot.executeCommand(parseCommand("!save night", "!")!)).toBe("此功能未启用");
+  });
+
+  it("saves the current queue to the shared bucket and loads it back", async () => {
+    const bot = makeBot({ savedQueuesEnabled: true });
+    const q = bot.getQueueManager();
+    q.add({ id: "a", name: "A", artist: "", album: "", platform: "netease", coverUrl: "", duration: 1 });
+    await bot.executeCommand(parseCommand("!save night", "!")!);
+    expect(bot.database.listSavedQueues(SHARED_QUEUE_OWNER, false).map((x) => x.name)).toContain("night");
+    const list = await bot.executeCommand(parseCommand("!queues", "!")!);
+    expect(list).toContain("night");
+  });
+});
+```
+
+- [ ] **Step 2: Run to verify it fails**
+
+Run: `npx vitest run src/bot/instance.test.ts -t "chat save/load" --no-file-parallelism`
+Expected: FAIL — Unknown command.
+
+- [ ] **Step 3: Implement**
+
+In the `executeCommand` switch, add cases (before `default`):
+
+```ts
+      case "save":
+        return this.cmdSaveQueue(cmd);
+      case "load":
+        return this.cmdLoadQueue(cmd);
+      case "queues":
+        return this.cmdListQueues();
+```
+
+Add the methods:
+
+```ts
+  private savedQueuesGuard(): string | null {
+    return this.config.savedQueuesEnabled ? null : "此功能未启用";
+  }
+
+  private cmdSaveQueue(cmd: ParsedCommand): string {
+    const off = this.savedQueuesGuard(); if (off) return off;
+    const name = cmd.args.trim();
+    if (!name) return `Usage: ${this.config.commandPrefix}save <名称>`;
+    const songs = this.queue.list();
+    if (songs.length === 0) return "队列为空，无法保存";
+    try {
+      const saved = this.database.saveQueue(SHARED_QUEUE_OWNER, name, songs);
+      return `已保存队列「${name}」（${saved.songCount} 首）`;
+    } catch (err) {
+      return `保存失败：${(err as Error).message}`;
+    }
+  }
+
+  private async cmdLoadQueue(cmd: ParsedCommand): Promise<string> {
+    const off = this.savedQueuesGuard(); if (off) return off;
+    const name = cmd.args.trim();
+    if (!name) return `Usage: ${this.config.commandPrefix}load [-a] <名称>`;
+    const owned = this.database.listSavedQueues(SHARED_QUEUE_OWNER, false).find((q) => q.name === name);
+    if (!owned) return `找不到已保存队列「${name}」`;
+    const full = this.database.getSavedQueue(owned.id);
+    if (!full) return `找不到已保存队列「${name}」`;
+    const mode = cmd.flags.has("a") ? "append" : "replace";
+    await this.loadSavedQueue(full.songs, mode);
+    return mode === "append"
+      ? `已追加「${name}」（${full.songs.length} 首）到队列`
+      : `已加载「${name}」（${full.songs.length} 首）`;
+  }
+
+  private cmdListQueues(): string {
+    const off = this.savedQueuesGuard(); if (off) return off;
+    const list = this.database.listSavedQueues(SHARED_QUEUE_OWNER, false);
+    if (list.length === 0) return "还没有已保存的队列";
+    return ["已保存队列：", ...list.map((q) => `• ${q.name}（${q.songCount} 首）`)].join("\n");
+  }
+```
+
+In `cmdHelp`, add before `${p}help`:
+
+```ts
+      `${p}save <名称>  — Save current queue`,
+      `${p}load [-a] <名称> — Load a saved queue (-a appends)`,
+      `${p}queues       — List saved queues`,
+```
+
+- [ ] **Step 4: Run to verify it passes**
+
+Run: `npx vitest run src/bot/instance.test.ts --no-file-parallelism`
+Expected: PASS.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/bot/instance.ts src/bot/instance.test.ts
+git commit -m "feat(chat): !save / !load [-a] / !queues commands (#119)"
+```
+
+---
+
+### Task 9: WebUI Saved Queues page
+
+**Files:**
+- Create: `web/src/composables/savedQueues.ts` + `savedQueues.test.ts` (pure helper), `web/src/composables/useSavedQueues.ts`, `web/src/views/SavedQueues.vue`
+- Modify: `web/src/router` (route), the nav/menu component (entry, shown only when feature enabled)
+
+**Interfaces:**
+- Consumes: `/api/saved-queues` (Task 7); the settings store/flag `savedQueuesEnabled` for nav gating.
+
+- [ ] **Step 1: Write the failing helper test**
+
+Create `web/src/composables/savedQueues.test.ts`:
+
+```ts
+import { describe, it, expect } from "vitest";
+import { sortQueues, isShared } from "./savedQueues";
+
+describe("savedQueues helper", () => {
+  it("flags shared owner", () => {
+    expect(isShared({ ownerId: "__shared__" } as any)).toBe(true);
+    expect(isShared({ ownerId: "u1" } as any)).toBe(false);
+  });
+  it("sorts by updatedAt desc", () => {
+    const out = sortQueues([
+      { id: 1, updatedAt: "2026-01-01" }, { id: 2, updatedAt: "2026-02-01" },
+    ] as any);
+    expect(out.map((q) => q.id)).toEqual([2, 1]);
+  });
+});
+```
+
+- [ ] **Step 2: Run to verify it fails**
+
+Run: `cd web && npx vitest run src/composables/savedQueues.test.ts`
+Expected: FAIL — module not found.
+
+- [ ] **Step 3: Implement the helper**
+
+Create `web/src/composables/savedQueues.ts`:
+
+```ts
+export interface SavedQueueMeta {
+  id: number; ownerId: string; name: string; songCount: number;
+  createdAt: string; updatedAt: string;
+}
+export const SHARED_OWNER = "__shared__";
+export function isShared(q: SavedQueueMeta): boolean { return q.ownerId === SHARED_OWNER; }
+export function sortQueues(qs: SavedQueueMeta[]): SavedQueueMeta[] {
+  return [...qs].sort((a, b) => (a.updatedAt < b.updatedAt ? 1 : a.updatedAt > b.updatedAt ? -1 : 0));
+}
+```
+
+- [ ] **Step 4: Run helper test**
+
+Run: `cd web && npx vitest run src/composables/savedQueues.test.ts`
+Expected: PASS.
+
+- [ ] **Step 5: Build the composable + page + nav**
+
+Create `web/src/composables/useSavedQueues.ts` (axios calls mirroring `useSpotifySettings`/favorites): `list()`, `save(botId, name, shared)`, `load(id, botId, mode)`, `remove(id)`.
+
+Create `web/src/views/SavedQueues.vue`: a page that on mount calls `list()`, shows a **Save current queue** control (text input + 共享 checkbox + bot selector reusing the app's current-bot scope), and a list of entries (name / song count / shared badge via `isShared`) with **Load** (replace), **Append**, **Delete** buttons. Reuse existing list/`SongCard`-style CSS.
+
+Register the route (path `/saved-queues`, component `SavedQueues.vue`) in the router, and add a nav entry that is rendered only when the settings flag `savedQueuesEnabled` is true (read the same settings the Settings page loads — reuse the existing settings store/composable; if none, fetch `/api/bot/settings` once in the nav or an app-level store).
+
+- [ ] **Step 6: Build check**
+
+Run: `cd web && npm run build`
+Expected: build succeeds.
+
+- [ ] **Step 7: Commit**
+
+```bash
+git add web/src/composables/savedQueues.ts web/src/composables/savedQueues.test.ts web/src/composables/useSavedQueues.ts web/src/views/SavedQueues.vue web/src/router* web/src/**/*Nav* 2>/dev/null; git add -A web/src
+git commit -m "feat(web): Saved Queues page + nav gated on savedQueuesEnabled (#119)"
+```
+
+---
+
+## Stage 4 — Feature 2: auto-restore live queue
+
+### Task 10: `PlayQueue.snapshot()` / `restore()`
+
+**Files:**
+- Modify: `src/audio/queue.ts`
+- Test: `src/audio/queue.test.ts`
+
+**Interfaces:**
+- Produces:
+
+```ts
+export interface QueueSnapshot {
+  songs: Omit<QueuedSong, "url">[];
+  currentIndex: number;
+  mode: PlayMode;
+}
+// on PlayQueue:
+snapshot(): QueueSnapshot;
+restore(s: QueueSnapshot): void;
+```
+
+- [ ] **Step 1: Write the failing test**
+
+Add to `src/audio/queue.test.ts`:
+
+```ts
+it("snapshot/restore round-trips songs, index, and mode", () => {
+  const q = new PlayQueue();
+  q.add({ id: "a", name: "A", artist: "", album: "", platform: "netease", coverUrl: "", duration: 1, url: "http://x" });
+  q.add({ id: "b", name: "B", artist: "", album: "", platform: "qq", coverUrl: "", duration: 2 });
+  q.setMode(PlayMode.Loop);
+  q.play(); q.next(); // current = index 1
+  const snap = q.snapshot();
+  expect(snap.currentIndex).toBe(1);
+  expect(snap.mode).toBe(PlayMode.Loop);
+  expect((snap.songs[0] as any).url).toBeUndefined(); // url stripped
+
+  const q2 = new PlayQueue();
+  q2.restore(snap);
+  expect(q2.list().map((s) => s.id)).toEqual(["a", "b"]);
+  expect(q2.getCurrentIndex()).toBe(1);
+  expect(q2.getMode()).toBe(PlayMode.Loop);
+  expect(q2.current()?.id).toBe("b");
+});
+```
+
+- [ ] **Step 2: Run to verify it fails**
+
+Run: `npx vitest run src/audio/queue.test.ts --no-file-parallelism`
+Expected: FAIL — `snapshot` undefined.
+
+- [ ] **Step 3: Implement**
+
+Add the interface export near `QueuedSong`, and these methods to `PlayQueue`:
+
+```ts
+  snapshot(): QueueSnapshot {
+    return {
+      songs: this.songs.map(({ url: _url, ...s }) => s),
+      currentIndex: this.currentIndex,
+      mode: this.mode,
+    };
+  }
+
+  restore(s: QueueSnapshot): void {
+    this.songs = s.songs.map((song) => ({ ...song }));
+    this.mode = s.mode;
+    this.currentIndex =
+      s.currentIndex >= 0 && s.currentIndex < this.songs.length ? s.currentIndex : -1;
+    // Rebuild derived state consistently for the restored position.
+    this.playedIndices = new Set(this.currentIndex >= 0 ? [this.currentIndex] : []);
+    this.history = [];
+    this.forwardStack = [];
+  }
+```
+
+- [ ] **Step 4: Run to verify it passes**
+
+Run: `npx vitest run src/audio/queue.test.ts --no-file-parallelism`
+Expected: PASS.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/audio/queue.ts src/audio/queue.test.ts
+git commit -m "feat(queue): snapshot/restore for cross-restart persistence (#119)"
+```
+
+---
+
+### Task 11: DB — `queue_state` table + methods
+
+**Files:**
+- Modify: `src/data/database.ts`
+- Test: `src/data/database.test.ts`
+
+**Interfaces:**
+- Produces:
+
+```ts
+export interface QueueStateRow {
+  botId: string; songs: StoredSong[]; currentIndex: number;
+  mode: string; isFmMode: boolean; fmPlatform: string;
+}
+// on BotDatabase:
+saveQueueState(state: QueueStateRow): void;   // upsert by botId
+getQueueState(botId: string): QueueStateRow | null;
+clearQueueState(botId: string): void;
+```
+
+- [ ] **Step 1: Write the failing test**
+
+Add to `src/data/database.test.ts`:
+
+```ts
+describe("queue_state", () => {
+  it("upserts, reads back, and clears per bot", () => {
+    const db = createDatabase(":memory:");
+    db.saveQueueState({ botId: "b1", songs: [{ id: "a" } as any], currentIndex: 0, mode: "loop", isFmMode: true, fmPlatform: "netease" });
+    db.saveQueueState({ botId: "b1", songs: [{ id: "a" } as any, { id: "b" } as any], currentIndex: 1, mode: "seq", isFmMode: false, fmPlatform: "" });
+    const st = db.getQueueState("b1")!;
+    expect(st.songs.map((s) => s.id)).toEqual(["a", "b"]);
+    expect(st.currentIndex).toBe(1);
+    expect(st.isFmMode).toBe(false);
+    db.clearQueueState("b1");
+    expect(db.getQueueState("b1")).toBeNull();
+    db.close();
+  });
+});
+```
+
+- [ ] **Step 2: Run to verify it fails**
+
+Run: `npx vitest run src/data/database.test.ts -t "queue_state" --no-file-parallelism`
+Expected: FAIL.
+
+- [ ] **Step 3: Implement**
+
+Add `QueueStateRow` export + the three `BotDatabase` methods. Add the table to `initTables`:
+
+```sql
+    CREATE TABLE IF NOT EXISTS queue_state (
+      botId        TEXT PRIMARY KEY,
+      songs        TEXT NOT NULL,
+      currentIndex INTEGER NOT NULL,
+      mode         TEXT NOT NULL,
+      isFmMode     INTEGER NOT NULL DEFAULT 0,
+      fmPlatform   TEXT NOT NULL DEFAULT '',
+      updatedAt    TEXT NOT NULL DEFAULT (datetime('now'))
+    );
+```
+
+In `createDatabase`:
+
+```ts
+    saveQueueState(state) {
+      db.prepare(`
+        INSERT INTO queue_state (botId, songs, currentIndex, mode, isFmMode, fmPlatform, updatedAt)
+        VALUES (@botId, @songs, @currentIndex, @mode, @isFmMode, @fmPlatform, datetime('now'))
+        ON CONFLICT(botId) DO UPDATE SET
+          songs=excluded.songs, currentIndex=excluded.currentIndex, mode=excluded.mode,
+          isFmMode=excluded.isFmMode, fmPlatform=excluded.fmPlatform, updatedAt=datetime('now')
+      `).run({
+        botId: state.botId, songs: JSON.stringify(state.songs), currentIndex: state.currentIndex,
+        mode: state.mode, isFmMode: state.isFmMode ? 1 : 0, fmPlatform: state.fmPlatform,
+      });
+    },
+    getQueueState(botId) {
+      const r = db.prepare("SELECT * FROM queue_state WHERE botId=?").get(botId) as any;
+      if (!r) return null;
+      return {
+        botId: r.botId, songs: parseSongs(r.songs), currentIndex: r.currentIndex,
+        mode: r.mode, isFmMode: r.isFmMode === 1, fmPlatform: r.fmPlatform,
+      };
+    },
+    clearQueueState(botId) {
+      db.prepare("DELETE FROM queue_state WHERE botId=?").run(botId);
+    },
+```
+
+(Reuse the `parseSongs` helper from Task 6.)
+
+- [ ] **Step 4: Run to verify it passes**
+
+Run: `npx vitest run src/data/database.test.ts -t "queue_state" --no-file-parallelism`
+Expected: PASS.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/data/database.ts src/data/database.test.ts
+git commit -m "feat(db): queue_state table for live-queue persistence (#119)"
+```
+
+---
+
+### Task 12: BotInstance snapshot-on-change + restore-on-connect
+
+**Files:**
+- Modify: `src/bot/instance.ts` (constructor/emit path, `connect`/`connected` handler)
+- Test: `src/bot/instance.test.ts`
+
+**Interfaces:**
+- Consumes: `this.database.saveQueueState/getQueueState/clearQueueState`, `this.queue.snapshot()/restore()`, `this.config.savedQueuesEnabled`, `this.isFmMode`, `this.fmProvider`, `this.resolveAndPlay`.
+
+- [ ] **Step 1: Write the failing tests**
+
+Add to `src/bot/instance.test.ts`:
+
+```ts
+describe("live-queue persistence", () => {
+  it("persists a snapshot on stateChange when enabled", async () => {
+    const bot = makeBot({ savedQueuesEnabled: true });
+    bot.getQueueManager().add({ id: "a", name: "A", artist: "", album: "", platform: "netease", coverUrl: "", duration: 1 });
+    bot.getQueueManager().play();
+    bot["persistQueueSnapshot"](); // call the (debounced) writer's inner sync fn directly
+    const st = bot.database.getQueueState(bot.id)!;
+    expect(st.songs.map((s: any) => s.id)).toEqual(["a"]);
+  });
+
+  it("does NOT persist when feature disabled", () => {
+    const bot = makeBot({ savedQueuesEnabled: false });
+    bot.getQueueManager().add({ id: "a", name: "A", artist: "", album: "", platform: "netease", coverUrl: "", duration: 1 });
+    bot["persistQueueSnapshot"]();
+    expect(bot.database.getQueueState(bot.id)).toBeNull();
+  });
+
+  it("restores and resumes on restore()", async () => {
+    const src = makeBot({ savedQueuesEnabled: true });
+    src.getQueueManager().add({ id: "a", name: "A", artist: "", album: "", platform: "netease", coverUrl: "", duration: 1 });
+    src.getQueueManager().play();
+    src["persistQueueSnapshot"]();
+
+    const bot = makeBot({ savedQueuesEnabled: true }, src.database); // share DB
+    const spy = vi.spyOn(bot, "resolveAndPlay").mockResolvedValue(true);
+    await bot["restoreQueueFromSnapshot"]();
+    expect(bot.getQueueManager().list().map((s) => s.id)).toEqual(["a"]);
+    expect(spy).toHaveBeenCalled();
+  });
+});
+```
+
+(Extend `makeBot` to accept an optional shared `database`. The two private methods are called via bracket access in tests.)
+
+- [ ] **Step 2: Run to verify it fails**
+
+Run: `npx vitest run src/bot/instance.test.ts -t "live-queue persistence" --no-file-parallelism`
+Expected: FAIL — methods undefined.
+
+- [ ] **Step 3: Implement**
+
+Add a debounced snapshot writer + a restore method to `BotInstance`:
+
+```ts
+  private snapshotTimer: NodeJS.Timeout | null = null;
+
+  /** Synchronous snapshot writer (debounced via scheduleQueueSnapshot). */
+  private persistQueueSnapshot(): void {
+    if (!this.config.savedQueuesEnabled) return;
+    try {
+      const snap = this.queue.snapshot();
+      if (snap.songs.length === 0) {
+        this.database.clearQueueState(this.id);
+        return;
+      }
+      this.database.saveQueueState({
+        botId: this.id,
+        songs: snap.songs,
+        currentIndex: snap.currentIndex,
+        mode: snap.mode,
+        isFmMode: this.isFmMode,
+        fmPlatform: this.isFmMode && this.fmProvider ? this.fmProvider.platform : "",
+      });
+    } catch (err) {
+      this.logger.warn({ err }, "queue snapshot persist failed");
+    }
+  }
+
+  private scheduleQueueSnapshot(): void {
+    if (!this.config.savedQueuesEnabled) return;
+    if (this.snapshotTimer) clearTimeout(this.snapshotTimer);
+    this.snapshotTimer = setTimeout(() => this.persistQueueSnapshot(), 1000);
+  }
+
+  /** Restore + resume the live queue after (re)connect. Best-effort. */
+  private async restoreQueueFromSnapshot(): Promise<void> {
+    if (!this.config.savedQueuesEnabled) return;
+    const st = this.database.getQueueState(this.id);
+    if (!st || st.songs.length === 0) return;
+    this.queue.restore({ songs: st.songs, currentIndex: st.currentIndex, mode: st.mode as PlayMode });
+    if (st.isFmMode && st.fmPlatform) {
+      this.isFmMode = true;
+      this.fmProvider = this.providerForPlatform(st.fmPlatform); // reuse existing platform→provider map
+    }
+    const current = this.queue.current();
+    if (current) {
+      this.player.resetFailures();
+      await this.resolveAndPlay(current); // resumes from track start
+    }
+  }
+```
+
+Wire the debounced writer into the existing `stateChange` emit path. The cleanest single hook: add a listener in the constructor:
+
+```ts
+    this.on("stateChange", () => this.scheduleQueueSnapshot());
+```
+
+Wire the restore into the connect flow — after `this.emit("connected")` in `connect()`:
+
+```ts
+    void this.restoreQueueFromSnapshot();
+```
+
+(Restore runs once per connect. `providerForPlatform` — reuse the existing platform→provider resolution used by `getProvider`/FM; if only a flags-based `getProvider` exists, add a small `providerForPlatform(platform: string): MusicProvider` switch that returns the matching provider, defaulting to netease.)
+
+- [ ] **Step 4: Run to verify it passes**
+
+Run: `npx vitest run src/bot/instance.test.ts --no-file-parallelism`
+Expected: PASS.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/bot/instance.ts src/bot/instance.test.ts
+git commit -m "feat(player): snapshot live queue on change + resume on reconnect (#119)"
+```
+
+---
+
+## Stage 5 — Docs & final verification
+
+### Task 13: README + full verification
+
+**Files:**
+- Modify: `README.md`
+
+- [ ] **Step 1: Update README**
+
+- Commands table: add `!save <名称>`, `!load [-a] <名称>`, `!queues`.
+- 行为设置 / feature docs: document `savedQueuesEnabled` (default off, admin — enables save/load + restart auto-resume) and `playKeepsQueue` (default off — single-song `!play` keeps the queue).
+- Changelog "最新版本 → 功能增强": add `#119 保存/加载播放清单 + 重启恢复队列 + 单曲播放不清空队列（均默认关闭）` with the honest caveats: restart resumes the current track **from its start**; Spotify auto-resume is best-effort.
+
+- [ ] **Step 2: Full verification**
+
+```bash
+npx vitest run --no-file-parallelism
+npx tsc --noEmit
+cd web && npm run build && cd ..
+```
+
+Expected: all tests pass; tsc exit 0; web build clean.
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add README.md
+git commit -m "docs(readme): document save/load queues + playKeepsQueue toggles (#119)"
+```
+
+- [ ] **Step 4: Push + open PR**
+
+```bash
+git push -u origin feat/issue-119-saved-queues
+gh pr create --fill --base main
+```
+
+---
+
+## Self-Review
+
+**Spec coverage:**
+- Feature 1 (named save/load, per-user + shared, chat + web, replace/append) → Tasks 6, 7, 8, 9. ✓
+- Feature 2 (auto-restore + resume) → Tasks 10, 11, 12. ✓
+- Feature 3 (`playKeepsQueue`) → Tasks 4, 5. ✓
+- Config gates (both default off, sanitized) → Task 1; admin settings → Tasks 2, 3. ✓
+- Caps, corrupt-blob degradation, ownership 404 → Task 6/7 tests. ✓
+- Caveats (track-start resume, Spotify best-effort) → Task 13 docs; behavior in Task 12. ✓
+
+**Type consistency:** `StoredSong`, `SavedQueue(Meta)`, `QueueSnapshot`, `QueueStateRow`, `SHARED_QUEUE_OWNER`, `playSingleSong`, `loadSavedQueue`, `saveQueue/listSavedQueues/getSavedQueue/deleteSavedQueue`, `saveQueueState/getQueueState/clearQueueState`, `snapshot/restore`, `persistQueueSnapshot/scheduleQueueSnapshot/restoreQueueFromSnapshot` — names are used identically across the tasks that define and consume them.
+
+**Open verification items for the implementer (flagged inline):**
+- Confirm the `config` object is shared by reference from `index.ts` → `createBotRouter` AND → each `BotInstance` (Task 2), so the toggles take effect without restart.
+- Confirm `WebServerOptions` exposes `botManager`, `config`, `database` under those names at the `server.ts` mount site (Task 7).
+- Confirm/add `providerForPlatform` on `BotInstance` (Task 12).