Skip to content

Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS

63.1 KB
Raw Blame
import { describe, it, expect, vi, beforeEach } from 'vitest';
import express from 'express';
import { request } from '../lib/testHelper.js';
import { ServerError } from '../lib/errorHandler.js';

// Mock the music-gen service's engine registry and readiness probes. Generation
// itself is queued through mediaJobQueue and never runs inside this route.
const gen = vi.hoisted(() => ({
  ready: true,
  readyByEngine: null,
  healthy: null,
  healthyByEngine: null,
  unsupportedPlatform: null,
}));
const mediaQueue = vi.hoisted(() => ({ jobs: [], enqueue: vi.fn() }));
const remoteProvider = vi.hoisted(() => ({ peers: [], resolve: vi.fn() }));
const cuda = vi.hoisted(() => ({ status: 'available', maxVramGb: 40, probe: null }));
vi.mock('../lib/cudaCapability.js', () => ({
  getCudaCapability: vi.fn(async () => cuda.probe ? cuda.probe() : ({ status: cuda.status, gpus: [], maxVramGb: cuda.maxVramGb, error: null })),
}));
vi.mock('../services/pipeline/musicGen.js', async () => {
  const actual = await vi.importActual('../services/pipeline/musicGen.js');
  const ENGINES = {
    musicgen: { id: 'musicgen', name: 'MusicGen', models: [{ id: 'm', name: 'M' }], defaultModelId: 'm', minDurationSec: 1, maxDurationSec: 30, defaultDurationSec: 12, installEnv: 'INSTALL_MUSICGEN', venvDefault: '/v/mg', resolvePython: () => (gen.ready ? '/v/mg/bin/python3' : null), customModels: true },
    acestep: { id: 'acestep', name: 'ACE-Step', models: [{ id: 'a', name: 'A' }], defaultModelId: 'a', minDurationSec: 1, maxDurationSec: 240, defaultDurationSec: 60, installEnv: 'INSTALL_ACESTEP', venvDefault: '/v/ace', resolvePython: () => (gen.ready ? '/v/ace/bin/python3' : null), lyrics: true, customModels: false },
    acestep15: { id: 'acestep15', name: 'ACE-Step 1.5', models: [{ id: 'ace-step-v1.5', repo: 'ACE-Step/Ace-Step1.5', name: 'ACE-Step 1.5' }], defaultModelId: 'ace-step-v1.5', minDurationSec: 1, maxDurationSec: 240, defaultDurationSec: 60, installEnv: 'INSTALL_ACESTEP15', venvDefault: '/v/ace15', resolvePython: () => (gen.ready ? '/v/ace15/bin/python3' : null), lyrics: true, customModels: false, fixedModelInstall: true },
      'minimax-music3': { id: 'minimax-music3', name: 'MiniMax Music 3', models: [{ id: 'minimax-music3', repo: 'MiniMaxAI/MiniMax-Music3', name: 'MiniMax Music 3', downloadIgnore: ['qwen_7B/*', 'flowmatching_vae.pth', 'dav.pth', 'figures/*'], downloadSizeGb: 29 }], defaultModelId: 'minimax-music3', minDurationSec: 1, maxDurationSec: 300, defaultDurationSec: 60, installEnv: 'INSTALL_MINIMAX_MUSIC3', venvDefault: '/v/minimax', resolvePython: () => (gen.ready ? '/v/minimax/bin/python3' : null), lyrics: true, customModels: false, fixedModelInstall: true, cudaRequired: true, autoDuration: true, executionProfile: 'cuda-bf16-auto-experimental', vramProfiles: { 'cuda-bf16-auto-experimental': { label: 'CUDA BF16 (experimental automatic placement)', minVramGb: null, recommendedVramGb: null } } },
    'minimax-music3-mlx': { id: 'minimax-music3-mlx', name: 'MiniMax Music 3 (MLX)', models: [
      { id: 'minimax-music3-mlx-8bit', repo: 'mlx-community/MiniMax-Music3-8bit', revision: '10aa4ca578d04c6f5256c1bc22fc8405a09602b5', downloadSizeGb: 14, name: 'MiniMax Music 3 MLX 8-bit' },
      { id: 'minimax-music3-mlx-bf16', repo: 'mlx-community/MiniMax-Music3-bf16', revision: '83a5f2d365673689df5c8f36e21e108751fd92ea', downloadSizeGb: 29, name: 'MiniMax Music 3 MLX BF16' },
    ], defaultModelId: 'minimax-music3-mlx-8bit', minDurationSec: 1, maxDurationSec: 300, defaultDurationSec: 60, installEnv: 'INSTALL_MINIMAX_MUSIC3_MLX', venvDefault: '/v/minimax-mlx', resolvePython: () => (gen.ready ? '/v/minimax-mlx/bin/python3' : null), lyrics: true, customModels: false, fixedModelInstall: true, autoDuration: true },
      'test-cuda': { id: 'test-cuda', name: 'Test CUDA', models: [{ id: 'test-cuda', name: 'Test CUDA' }], defaultModelId: 'test-cuda', minDurationSec: 1, maxDurationSec: 30, defaultDurationSec: 1, installEnv: 'INSTALL_TEST_CUDA', venvDefault: '/v/test-cuda', resolvePython: () => (gen.ready ? '/v/test-cuda/bin/python3' : null), cudaRequired: true, executionProfile: 'test-cuda', vramProfiles: { 'test-cuda': { label: 'test CUDA', minVramGb: 0, recommendedVramGb: 0 } } },
  };
  return {
    composeMusicLyrics: actual.composeMusicLyrics,
    ENGINES,
    DEFAULT_ENGINE_ID: 'musicgen',
    getEngine: (id) => ENGINES[id] || ENGINES.musicgen,
    getEngineModel: (id, modelId) => (ENGINES[id] || ENGINES.musicgen).models.find((m) => m.id === modelId) || null,
    isEngineReady: (engineId) => (gen.readyByEngine ? gen.readyByEngine[engineId] === true : gen.ready),
    // The route reads readiness through isEngineHealthy (the import probe), so
    // `gen.healthyByEngine` / `gen.healthy` drive it; both default to the same
    // `ready` knobs so existing cases keep their meaning.
    isEnginePlatformSupported: (engineId) => (gen.unsupportedPlatform ? engineId !== gen.unsupportedPlatform : true),
    enginePlatformLabel: () => 'macOS on Apple Silicon (MLX)',
    resolveEngineVramReadiness: (engineId, capability) => {
      const engine = ENGINES[engineId] || ENGINES.musicgen;
      const profile = engine.vramProfiles?.[engine.executionProfile];
      const state = !engine.cudaRequired
        ? 'sufficient'
        : profile?.minVramGb == null || capability.status !== 'available' || !Number.isFinite(capability.maxVramGb)
          ? 'unknown-size'
          : capability.maxVramGb >= profile.minVramGb ? 'sufficient' : 'insufficient';
      return {
        state,
        executionProfile: engine.executionProfile || null,
        profileLabel: profile?.label || null,
        minVramGb: profile?.minVramGb ?? null,
        recommendedVramGb: profile?.recommendedVramGb ?? null,
        maxVramGb: Number.isFinite(capability.maxVramGb) ? capability.maxVramGb : null,
      };
    },
    MUSIC_VRAM_READINESS: { SUFFICIENT: 'sufficient', INSUFFICIENT: 'insufficient', UNKNOWN_SIZE: 'unknown-size' },
    formatEngineVramReadinessMessage: (engineId, readiness, action = 'run') => {
      const engine = ENGINES[engineId] || ENGINES.musicgen;
      if (readiness.state === 'insufficient') return `${engine.name} requires at least ${readiness.minVramGb} GB of VRAM for the ${readiness.profileLabel || 'selected'} profile; this host reports ${readiness.maxVramGb} GB.`;
      if (readiness.state === 'unknown-size') return `${engine.name} cannot be ${action} because the GPU VRAM requirement has not been measured for the ${readiness.profileLabel || 'selected'} execution profile.`;
      return null;
    },
    isEngineHealthy: async (engineId) => {
      if (gen.healthyByEngine) return gen.healthyByEngine[engineId] === true;
      if (gen.healthy !== null) return gen.healthy;
      return gen.readyByEngine ? gen.readyByEngine[engineId] === true : gen.ready;
    },
    invalidateEngineHealth: vi.fn(),
  };
});
vi.mock('../services/mediaJobQueue/index.js', () => ({
  enqueueJob: (...args) => mediaQueue.enqueue(...args),
  listJobs: () => mediaQueue.jobs,
  JOB_KINDS: ['video', 'image', 'training', 'audio'],
  JOB_STATUSES: ['queued', 'running', 'completed', 'failed', 'canceled'],
}));
vi.mock('../services/instances.js', () => ({
  getPeers: vi.fn(async () => remoteProvider.peers),
}));
vi.mock('../services/federatedMediaConsumer.js', () => ({
  resolveFederatedMediaProvider: (...args) => remoteProvider.resolve(...args),
}));

// The install route shells out to scripts/setup-image-video.sh. Stand in a child
// that closes immediately so the SSE stream terminates instead of running a real
// multi-GB bash install under the test.
const setup = vi.hoisted(() => ({ spawn: vi.fn(), exitCode: 0 }));
vi.mock('../lib/setupScriptRunner.js', async () => ({
  // Keep the real SETUP_IMAGE_VIDEO_SCRIPT — the route existsSync-checks it.
  ...(await vi.importActual('../lib/setupScriptRunner.js')),
  stopSetupScript: vi.fn(),
  spawnSetupScript: (env) => {
    setup.spawn(env);
    const listeners = {};
    const child = {
      stdout: { on: () => {} },
      stderr: { on: () => {} },
      on: (event, cb) => { listeners[event] = cb; },
    };
    Promise.resolve().then(() => listeners.close?.(setup.exitCode));
    return child;
  },
}));

vi.mock('../services/tracks/index.js', () => ({
  getTrack: vi.fn(),
  createTrack: vi.fn(async (input) => ({ id: 'track-new', ...input })),
  updateTrack: vi.fn(async (id, patch) => ({ id, ...patch })),
  buildRenderAppend: vi.fn((track, input) => {
    const render = { id: 'render-x', ...input };
    return { render, renders: [...(track?.renders || []), render] };
  }),
}));

const models = vi.hoisted(() => ({ list: vi.fn(), add: vi.fn(), remove: vi.fn() }));
vi.mock('../services/audioModels.js', () => ({
  listEngineModels: (engineId) => models.list(engineId),
  addAudioModel: (args) => models.add(args),
  removeAudioModel: (args) => models.remove(args),
  isValidRepoId: (r) => typeof r === 'string' && /^[\w.-]+\/[\w./-]+$/.test(r) && !r.includes('..'),
}));

// The SSE download driver writes to the response + ends it; stub it to a quick
// 200 so the route test doesn't spawn Python.
const sse = vi.hoisted(() => ({
  run: vi.fn(async ({ res }) => { res.writeHead(200, { 'Content-Type': 'text/event-stream' }); res.end('data: {"type":"complete"}\n\n'); }),
  open: vi.fn((res) => {
    res.writeHead(200, { 'Content-Type': 'text/event-stream' });
    return {
      send: (event) => res.write(`data: ${JSON.stringify(event)}\n\n`),
      safeEnd: () => { if (!res.writableEnded) res.end(); },
    };
  }),
}));
vi.mock('../lib/sseDownload.js', async () => ({
  ...(await vi.importActual('../lib/sseDownload.js')),
  openSseStream: (res) => sse.open(res),
}));
vi.mock('../services/hfDownloadStream.js', () => ({
  startHfDownloadStream: (args) => sse.run(args),
}));

// Register-after-download gates on whether the repo landed in the cache.
const cache = vi.hoisted(() => ({ cached: true, byRevision: null, calls: [] }));
vi.mock('../lib/hfCache.js', () => ({ inspectModelCache: vi.fn(async (repo, options = {}) => {
  cache.calls.push({ repo, ...options });
  return { cached: cache.byRevision?.[options.revision] ?? cache.cached };
}) }));

vi.mock('../services/albums/index.js', () => ({
  getAlbum: vi.fn(async () => null),
  updateAlbum: vi.fn(async (id, patch) => ({ id, ...patch })),
}));

// The stepped designer's two LLM steps (#4305) — stubbed so the route tests pin
// validation + the exact service call args, not a provider round trip.
vi.mock('../services/musicDesigner.js', () => ({
  describeMusic: vi.fn(),
  writeLyrics: vi.fn(),
}));

// The code engine (#8375) runs its one LLM call through the shared runner.
// Stub the runner (not the service) so the route test covers the service's
// prompt, fence stripping, and size check too.
vi.mock('../services/promptRunner.js', async () => ({
  ...(await vi.importActual('../services/promptRunner.js')),
  resolveProviderAndModel: vi.fn(),
  runPromptThroughProvider: vi.fn(),
}));

import * as tracks from '../services/tracks/index.js';
import * as promptRunner from '../services/promptRunner.js';
import * as albums from '../services/albums/index.js';
import * as designer from '../services/musicDesigner.js';
import { errorMiddleware } from '../lib/errorHandler.js';
import musicRoutes from './music.js';

function makeApp() {
  const app = express();
  app.use(express.json());
  app.use('/api/music', musicRoutes);
  app.use(errorMiddleware);
  return app;
}

describe('music routes', () => {
  let app;
  beforeEach(() => {
    app = makeApp();
    mediaQueue.enqueue.mockReset().mockImplementation(() => ({ jobId: 'job-1', position: 1, status: 'queued' }));
    mediaQueue.jobs = [];
    remoteProvider.peers = [];
    remoteProvider.resolve.mockReset();
    models.list.mockReset();
    // add/remove return promises by default so the route's `.catch()` chains
    // don't throw on an undefined return (mockReset clears the impl).
    models.add.mockReset().mockResolvedValue({});
    models.remove.mockReset().mockResolvedValue(true);
    tracks.getTrack.mockReset();
    tracks.createTrack.mockReset().mockImplementation(async (input) => ({ id: 'track-new', ...input }));
    tracks.updateTrack.mockReset().mockImplementation(async (id, patch) => ({ id, ...patch }));
    albums.getAlbum.mockReset().mockResolvedValue(null);
    albums.updateAlbum.mockReset().mockImplementation(async (id, patch) => ({ id, ...patch }));
    sse.run.mockReset().mockImplementation(async ({ res }) => { res.writeHead(200, { 'Content-Type': 'text/event-stream' }); res.end('data: {"type":"complete"}\n\n'); });
    gen.ready = true;
    gen.readyByEngine = null;
    gen.healthy = null;
    gen.healthyByEngine = null;
    gen.unsupportedPlatform = null;
    setup.spawn.mockReset();
    setup.exitCode = 0;
    cache.cached = true;
    cache.byRevision = null;
    cache.calls.length = 0;
    cuda.status = 'available';
    cuda.maxVramGb = 40;
    cuda.probe = null;
    models.list.mockResolvedValue([{ id: 'm', name: 'M', userAdded: false }]);
    designer.describeMusic.mockReset().mockResolvedValue({ description: 'Lush pads over a broken beat.', llm: { provider: 'fake-provider', model: 'fake-model' } });
    designer.writeLyrics.mockReset().mockResolvedValue({ lyrics: '[verse]\nrain on the window', llm: { provider: 'fake-provider', model: 'fake-model' } });
  });

  // Uniquely catches route/schema or composer rewrites of authored text, and
  // ensures generated overflow is refused by the real workflow at its HTTP boundary.
  it('preserves authored designer fields through routes and provider composition', async () => {
    const real = await vi.importActual('../services/musicDesigner.js');
    designer.describeMusic.mockImplementation(real.describeMusic);
    designer.writeLyrics.mockImplementation(real.writeLyrics);
    promptRunner.resolveProviderAndModel.mockResolvedValue({ provider: { id: 'p', type: 'api' }, selectedModel: 'm' });
    promptRunner.runPromptThroughProvider.mockResolvedValue({ text: 'Valid generated text', model: 'm' });
    const concept = '  A fictional twilight loop\n\t';
    const guidance = '  Keep the pulse soft\t ';
    const template = ' \nMy authored instruction.\n  ';
    const described = await request(app).post('/api/music/describe').send({ concept, guidance, template });
    expect(described.status).toBe(200);
    expect(described.body.sentPrompt).toBe(promptRunner.runPromptThroughProvider.mock.calls.at(-1)[0].prompt);
    expect(described.body.sentPrompt).toContain(`${template}\n\nMUSICAL REFERENCE / VIBE:\n${concept}\n\nADDITIONAL GUIDANCE FROM THE USER:\n${guidance}`);
    const description = '  An airy fictional arrangement.\n ';
    const requestText = '  Chorus about paper moons\n  ';
    const written = await request(app).post('/api/music/lyrics').send({ description, guidance, template, request: requestText });
    expect(written.status).toBe(200);
    expect(written.body.sentPrompt).toContain(`:\n${requestText}\n\nMUSICAL DESCRIPTION:\n${description}\n\nADDITIONAL GUIDANCE FROM THE USER:\n${guidance}`);
    expect(written.body.sentPrompt).toContain(template);
    const reset = await request(app).post('/api/music/describe').send({ concept, template: ' \n\t' });
    expect(reset.body.sentPrompt).toContain(real.DEFAULT_DESCRIBE_TEMPLATE);
    expect(reset.body.promptAdditions.map((item) => item.label)).toContain('Describe instructions');
  });

  it.each([
    ['/describe', { concept: 'x' }, 'description', 8000],
    ['/lyrics', { description: 'x' }, 'lyrics', 20000],
  ])('rejects oversized generated output from %s without another provider call', async (path, body, field, limit) => {
    const real = await vi.importActual('../services/musicDesigner.js');
    designer.describeMusic.mockImplementation(real.describeMusic);
    designer.writeLyrics.mockImplementation(real.writeLyrics);
    promptRunner.resolveProviderAndModel.mockResolvedValue({ provider: { id: 'p', type: 'api' }, selectedModel: 'm' });
    promptRunner.runPromptThroughProvider.mockReset().mockResolvedValue({ text: 'x'.repeat(limit + 1), model: 'm' });
    const response = await request(app).post(`/api/music${path}`).send(body);
    expect(response.status).toBe(502);
    expect(response.body.code).toBe('LLM_OUTPUT_TOO_LONG');
    expect(response.body.error).toContain(`${limit + 1} characters; limit is ${limit}`);
    expect(response.body).not.toHaveProperty(field);
    expect(promptRunner.runPromptThroughProvider).toHaveBeenCalledTimes(1);
  });

  it.each([
    ['/describe', { concept: 'x' + ' '.repeat(8000) }, 8001, 8000],
    ['/lyrics', { description: 'x', guidance: ' '.repeat(4001) }, 4001, 4000],
    ['/lyrics', { description: 'x', template: ' '.repeat(8001) }, 8001, 8000],
    ['/lyrics', { description: 'x', request: ' '.repeat(4001) }, 4001, 4000],
  ])('counts authored whitespace before rejecting %s', async (path, body, count, limit) => {
    const response = await request(app).post(`/api/music${path}`).send(body);
    expect(response.status).toBe(400);
    expect(response.body.error).toContain(`${count} characters; limit is ${limit}`);
    expect(designer.describeMusic).not.toHaveBeenCalled();
    expect(designer.writeLyrics).not.toHaveBeenCalled();
  });

  describe('POST /describe', () => {
    it('passes every designer field through to describeMusic and returns text + attribution', async () => {
      const r = await request(app).post('/api/music/describe').send({
        concept: 'a rainy downtempo loop',
        guidance: 'under 100 BPM',
        template: 'Be terse.',
        providerId: 'fake-provider',
        model: 'fake-model',
        effort: 'high',
      });
      expect(r.status).toBe(200);
      expect(r.body).toEqual({ description: 'Lush pads over a broken beat.', llm: { provider: 'fake-provider', model: 'fake-model' } });
      expect(designer.describeMusic).toHaveBeenCalledWith({
        concept: 'a rainy downtempo loop',
        guidance: 'under 100 BPM',
        template: 'Be terse.',
        providerId: 'fake-provider',
        model: 'fake-model',
        effort: 'high',
      });
    });

    it('normalizes empty picker values to undefined so the service falls back to its defaults', async () => {
      const r = await request(app).post('/api/music/describe').send({
        concept: 'a rainy downtempo loop', providerId: '', model: '   ', effort: '',
      });
      expect(r.status).toBe(200);
      expect(designer.describeMusic).toHaveBeenCalledWith({
        concept: 'a rainy downtempo loop',
        guidance: undefined,
        template: undefined,
        providerId: undefined,
        model: undefined,
        effort: undefined,
      });
    });

    it('rejects a missing/blank concept', async () => {
      const missing = await request(app).post('/api/music/describe').send({});
      expect(missing.status).toBe(400);
      const blank = await request(app).post('/api/music/describe').send({ concept: '   ' });
      expect(blank.status).toBe(400);
      expect(designer.describeMusic).not.toHaveBeenCalled();
    });

    it('rejects a concept past the prompt-field cap', async () => {
      const r = await request(app).post('/api/music/describe').send({ concept: 'x'.repeat(8001) });
      expect(r.status).toBe(400);
      expect(designer.describeMusic).not.toHaveBeenCalled();
    });

    it('surfaces the service NO_PROVIDER error through the error middleware', async () => {
      designer.describeMusic.mockRejectedValue(new ServerError('No AI provider available to describe the music', { status: 503, code: 'NO_PROVIDER' }));
      const r = await request(app).post('/api/music/describe').send({ concept: 'x' });
      expect(r.status).toBe(503);
      expect(r.body.code).toBe('NO_PROVIDER');
    });
  });

  describe('POST /lyrics', () => {
    it('passes every designer field through to writeLyrics and returns lyrics + attribution', async () => {
      const r = await request(app).post('/api/music/lyrics').send({
        description: 'warm rhodes soul',
        request: undefined,
        targetSeconds: undefined,
        guidance: 'about leaving at dawn',
        template: 'Two verses only.',
        providerId: 'fake-provider',
        model: 'fake-model',
        effort: 'low',
      });
      expect(r.status).toBe(200);
      expect(r.body).toEqual({ lyrics: '[verse]\nrain on the window', llm: { provider: 'fake-provider', model: 'fake-model' } });
      expect(designer.writeLyrics).toHaveBeenCalledWith({
        description: 'warm rhodes soul',
        request: undefined,
        targetSeconds: undefined,
        guidance: 'about leaving at dawn',
        template: 'Two verses only.',
        providerId: 'fake-provider',
        model: 'fake-model',
        effort: 'low',
      });
    });

    it('rejects a missing description', async () => {
      const r = await request(app).post('/api/music/lyrics').send({ guidance: 'about leaving at dawn' });
      expect(r.status).toBe(400);
      expect(designer.writeLyrics).not.toHaveBeenCalled();
    });

    it('surfaces the service LLM_EMPTY error through the error middleware', async () => {
      designer.writeLyrics.mockRejectedValue(new ServerError('The AI returned empty lyrics.', { status: 502, code: 'LLM_EMPTY' }));
      const r = await request(app).post('/api/music/lyrics').send({ description: 'warm rhodes soul' });
      expect(r.status).toBe(502);
      expect(r.body.code).toBe('LLM_EMPTY');
    });
  });

  describe('POST /code', () => {
    beforeEach(() => {
      promptRunner.resolveProviderAndModel.mockReset().mockResolvedValue({ provider: { id: 'fake-provider', type: 'api' }, selectedModel: 'fake-model' });
      promptRunner.runPromptThroughProvider.mockReset();
    });

    it('returns the fence-stripped Strudel code with attribution', async () => {
      promptRunner.runPromptThroughProvider.mockResolvedValue({
        text: 'Here is your track:\n\n```javascript\nsetcps(0.5)\nnote("c3 e3 g3").s("sawtooth")\n```\nEnjoy!',
        model: 'fake-model',
      });
      const r = await request(app).post('/api/music/code').send({
        description: 'neon synthwave drive', guidance: '124 BPM', providerId: 'fake-provider', effort: 'high',
      });
      expect(r.status).toBe(200);
      expect(r.body).toEqual({
        language: 'strudel',
        code: 'setcps(0.5)\nnote("c3 e3 g3").s("sawtooth")',
        llm: { provider: 'fake-provider', model: 'fake-model' },
      });
      const args = promptRunner.runPromptThroughProvider.mock.calls[0][0];
      expect(args).toMatchObject({ source: 'music-code', model: 'fake-model', effort: 'high' });
      expect(args.prompt).toContain('neon synthwave drive');
      expect(args.prompt).toContain('124 BPM');
    });

    it('scores an animation script at its length, and previews the exact prompt with labeled additions', async () => {
      promptRunner.runPromptThroughProvider.mockResolvedValue({ text: 'silence', model: 'fake-model' });
      const brief = { scene: 'A space station boots up', durationSec: 20, providerId: 'fake-provider' };
      const r = await request(app).post('/api/music/code').send(brief);
      expect(r.status).toBe(200);
      const sent = promptRunner.runPromptThroughProvider.mock.calls[0][0].prompt;
      expect(sent).toContain('A space station boots up');
      expect(sent).toContain('exactly 20 seconds');

      const preview = await request(app).post('/api/music/code/preview').send(brief);
      expect(preview.status).toBe(200);
      expect(preview.body.sentPrompt).toBe(sent);
      expect(preview.body.promptAdditions.map((item) => item.label)).toEqual(['Strudel writing rules', 'Animation script', 'Length']);
      expect(promptRunner.runPromptThroughProvider).toHaveBeenCalledTimes(1);

      expect((await request(app).post('/api/music/code').send({ providerId: 'fake-provider' })).status).toBe(400);
    });

    it('writes Tone.js code with its own prompt contract when language is tonejs', async () => {
      promptRunner.runPromptThroughProvider.mockResolvedValue({
        text: 'const synth = new Tone.Synth().toDestination();\nTone.getTransport().start();',
        model: 'fake-model',
      });
      const r = await request(app).post('/api/music/code').send({
        description: 'ambient pad drone', language: 'tonejs', providerId: 'fake-provider',
      });
      expect(r.status).toBe(200);
      expect(r.body).toEqual({
        language: 'tonejs',
        code: 'const synth = new Tone.Synth().toDestination();\nTone.getTransport().start();',
        llm: { provider: 'fake-provider', model: 'fake-model' },
      });
      const prompt = promptRunner.runPromptThroughProvider.mock.calls[0][0].prompt;
      expect(prompt).toContain('Tone.js');
      expect(prompt).toContain('ambient pad drone');
      expect(prompt).toContain('Tone.Transport.start()');
      expect(prompt).not.toContain('Strudel');
    });

    it('writes SuperCollider code with its own prompt contract and rejects unknown languages', async () => {
      promptRunner.runPromptThroughProvider.mockResolvedValue({ text: '```supercollider\nSynthDef(\\\\pad, { Out.ar(0, SinOsc.ar(220)!2) }).add;\n```', model: 'fake-model' });
      const r = await request(app).post('/api/music/code').send({
        description: 'slow ambient drone', language: 'supercollider', providerId: 'fake-provider',
      });
      expect(r.status).toBe(200);
      expect(r.body.language).toBe('supercollider');
      expect(r.body.code).toContain('SynthDef');
      const prompt = promptRunner.runPromptThroughProvider.mock.calls[0][0].prompt;
      expect(prompt).toContain('SuperCollider');
      expect(prompt).toContain('slow ambient drone');
      expect(prompt).toContain('unixCmd');
      expect(prompt).not.toContain('Strudel');
      const bad = await request(app).post('/api/music/code').send({ description: 'x', language: 'csound' });
      expect(bad.status).toBe(400);
    });

    it('sends the editor code back as the revision target', async () => {
      promptRunner.runPromptThroughProvider.mockResolvedValue({ text: 'note("c3").s("sine")' });
      const r = await request(app).post('/api/music/code').send({
        description: 'ambient', current: 'note("a2 e3").s("triangle")',
      });
      expect(r.status).toBe(200);
      expect(r.body.code).toBe('note("c3").s("sine")');
      expect(promptRunner.runPromptThroughProvider.mock.calls[0][0].prompt).toContain('note("a2 e3").s("triangle")');
    });

    it('rejects a missing description, oversize editor code, or an unknown language', async () => {
      const missing = await request(app).post('/api/music/code').send({});
      const oversize = await request(app).post('/api/music/code').send({ description: 'x', current: 'x'.repeat(20001) });
      const language = await request(app).post('/api/music/code').send({ description: 'x', language: 'python' });
      expect([missing.status, oversize.status, language.status]).toEqual([400, 400, 400]);
      expect(promptRunner.runPromptThroughProvider).not.toHaveBeenCalled();
    });

    it('refuses an empty or oversize LLM reply with a 502', async () => {
      promptRunner.runPromptThroughProvider.mockResolvedValueOnce({ text: '```js\n\n```' });
      const empty = await request(app).post('/api/music/code').send({ description: 'x' });
      expect(empty.status).toBe(502);
      expect(empty.body.code).toBe('MUSIC_CODE_EMPTY');

      promptRunner.runPromptThroughProvider.mockResolvedValueOnce({ text: 'x'.repeat(20001) });
      const long = await request(app).post('/api/music/code').send({ description: 'x' });
      expect(long.status).toBe(502);
      expect(long.body.code).toBe('MUSIC_CODE_TOO_LONG');
    });
  });

  it('GET /engines lists engines with readiness + lyric capability + merged models', async () => {
    const r = await request(app).get('/api/music/engines');
    expect(r.status).toBe(200);
    expect(r.body.defaultEngine).toBe('musicgen');
    const ace = r.body.engines.find((e) => e.id === 'acestep');
    expect(ace.lyrics).toBe(true);
    expect(ace.ready).toBe(true);
    expect(ace.customModels).toBe(false); // fixed checkpoint — no custom install
    expect(ace.models).toEqual([{ id: 'm', name: 'M', userAdded: false }]);
    const mg = r.body.engines.find((e) => e.id === 'musicgen');
    expect(mg.lyrics).toBe(false);
    expect(mg.customModels).toBe(true);
    expect(r.body.engines.find((e) => e.id === 'minimax-music3').autoDuration).toBe(true);
  });

  it('GET /engines reports readiness per engine', async () => {
    gen.readyByEngine = { musicgen: true, acestep: false };
    const r = await request(app).get('/api/music/engines');
    expect(r.status).toBe(200);
    expect(r.body.engines.find((e) => e.id === 'musicgen').ready).toBe(true);
    expect(r.body.engines.find((e) => e.id === 'acestep').ready).toBe(false);
  });

  it('GET /engines keeps the experimental CUDA profile blocked pending a full measurement', async () => {
    cache.cached = false;
    const supported = await request(app).get('/api/music/engines');
    expect(supported.body.engines.find((e) => e.id === 'minimax-music3')).toMatchObject({
      cudaState: 'available', vramState: 'unknown-size', fixedModelInstall: true, modelReady: false, runtimeReady: true, ready: false,
      executionProfile: 'cuda-bf16-auto-experimental', minVramGb: null, recommendedVramGb: null, maxVramGb: 40,
      // The UI puts this on the install button so the user knows the size of the
      // pull before starting it.
      modelSizeGb: 29,
    });

    cuda.status = 'absent';
    const unsupported = await request(app).get('/api/music/engines');
    expect(unsupported.body.engines.find((e) => e.id === 'minimax-music3')).toMatchObject({
      cudaState: 'absent', vramState: 'unknown-size', ready: false,
    });
  });

  it('refuses MiniMax runtime installation while profile VRAM is unknown', async () => {
    const r = await request(app).post('/api/music/setup/runtime-install?runtime=minimax-music3');
    expect(r.status).toBe(200);
    expect(r.text).toContain('VRAM requirement has not been measured');
    expect(setup.spawn).not.toHaveBeenCalled();
  });

  it('GET /engines reports MLX readiness separately for the 8-bit and BF16 snapshots', async () => {
    cache.byRevision = {
      '10aa4ca578d04c6f5256c1bc22fc8405a09602b5': true,
      '83a5f2d365673689df5c8f36e21e108751fd92ea': false,
    };
    const r = await request(app).get('/api/music/engines');
    expect(r.status).toBe(200);
    expect(r.body.engines.find((e) => e.id === 'minimax-music3-mlx')).toMatchObject({
      modelReady: true,
      modelReadyById: {
        'minimax-music3-mlx-8bit': true,
        'minimax-music3-mlx-bf16': false,
      },
      ready: true,
      platformSupported: true,
      installEnv: 'INSTALL_MINIMAX_MUSIC3_MLX',
    });
    expect(cache.calls).toEqual(expect.arrayContaining([
      { repo: 'mlx-community/MiniMax-Music3-8bit', revision: '10aa4ca578d04c6f5256c1bc22fc8405a09602b5' },
      { repo: 'mlx-community/MiniMax-Music3-bf16', revision: '83a5f2d365673689df5c8f36e21e108751fd92ea' },
    ]));
  });

  it('GET /engines exposes ACE-Step 1.5 as a fixed model install distinct from v1', async () => {
    cache.cached = false;
    const r = await request(app).get('/api/music/engines');
    expect(r.status).toBe(200);
    expect(r.body.engines.find((e) => e.id === 'acestep15')).toMatchObject({
      lyrics: true, customModels: false, fixedModelInstall: true,
      modelReady: false, runtimeReady: true, ready: false,
      installEnv: 'INSTALL_ACESTEP15',
    });
  });

  it('POST /models rejects an engine that does not support custom models (acestep)', async () => {
    const r = await request(app).post('/api/music/models').send({ engine: 'acestep', repo: 'someorg/ace-variant' });
    expect(r.status).toBe(400);
    expect(r.body.code).toBe('AUDIO_MODEL_ENGINE_FIXED');
    expect(models.add).not.toHaveBeenCalled();
    expect(sse.run).not.toHaveBeenCalled();
  });

  it('GET /setup/runtime-status reports music runtime readiness', async () => {
    gen.ready = false;
    const missing = await request(app).get('/api/music/setup/runtime-status?runtime=acestep');
    expect(missing.status).toBe(200);
    expect(missing.body).toMatchObject({
      runtime: 'acestep',
      label: 'ACE-Step',
      installed: false,
      venvPath: null,
      expectedVenvPath: '/v/ace',
      installEnvVar: 'INSTALL_ACESTEP',
    });

    gen.ready = true;
    const ready = await request(app).get('/api/music/setup/runtime-status?runtime=acestep');
    expect(ready.status).toBe(200);
    expect(ready.body.installed).toBe(true);
    expect(ready.body.venvPath).toBe('/v/ace/bin/python3');
  });

  it('GET /setup/runtime-install reports status without spawning', async () => {
    gen.ready = true;
    const r = await request(app).get('/api/music/setup/runtime-install?runtime=acestep');
    expect(r.status).toBe(200);
    expect(r.body).toMatchObject({ runtime: 'acestep', installed: true });
    expect(setup.spawn).not.toHaveBeenCalled();
  });

  it('POST /setup/runtime-install completes without spawning when already installed', async () => {
    gen.ready = true;
    gen.healthy = true;
    const r = await request(app).post('/api/music/setup/runtime-install?runtime=acestep');
    expect(r.status).toBe(200);
    expect(r.text).toContain('"type":"complete"');
    expect(r.text).toContain('Already installed');
    expect(setup.spawn).not.toHaveBeenCalled();
  });

  it('GET /setup/runtime-install rejects an unknown runtime before opening SSE', async () => {
    const r = await request(app).get('/api/music/setup/runtime-install?runtime=unknown');
    expect(r.status).toBe(400);
    expect(r.body).toMatchObject({ code: 'UNKNOWN_MUSIC_RUNTIME' });
    expect(r.body.timestamp).toEqual(expect.any(Number));
    expect(setup.spawn).not.toHaveBeenCalled();
  });

  it('POST /setup/runtime-install proceeds when the interpreter exists but the venv is broken', async () => {
    // Regression: a failed install leaves the venv's interpreter behind, so the
    // old interpreter-exists check short-circuited with "already installed" and
    // the engine could never be repaired from the UI.
    gen.ready = true;          // resolvePython() finds the leftover interpreter
    gen.healthy = false;       // ...but the import probe fails
    const r = await request(app).post('/api/music/setup/runtime-install?runtime=acestep');
    expect(r.status).toBe(200);
    expect(r.text).not.toContain('Already installed');
    expect(r.text).toContain('Starting ACE-Step install.');
    expect(setup.spawn).toHaveBeenCalled();
  });

  it('GET /engines reports a broken venv as not ready so the install hint shows', async () => {
    gen.ready = true;
    gen.healthy = false;
    const r = await request(app).get('/api/music/engines');
    expect(r.status).toBe(200);
    const acestep = r.body.engines.find((e) => e.id === 'acestep');
    expect(acestep.runtimeReady).toBe(false);
    expect(acestep.ready).toBe(false);
  });

  it('POST /setup/runtime-install refuses on a host that can never run the engine', async () => {
    // Previously the route spawned the setup script, whose own platform guard
    // printed "Skipping." and exited 0 — surfaced to the user as "installer
    // exited 0 but the engine is still not available".
    gen.unsupportedPlatform = 'musicgen';
    gen.healthy = false;
    const r = await request(app).post('/api/music/setup/runtime-install?runtime=musicgen');
    expect(r.status).toBe(200);
    expect(r.text).toContain('cannot be installed on this host');
    expect(setup.spawn).not.toHaveBeenCalled();
  });

  it('POST /setup/runtime-install claims a CUDA engine while its capability probe is pending', async () => {
    let finishProbe;
    cuda.probe = () => new Promise((resolve) => { finishProbe = resolve; });
    gen.healthy = false;

    const first = request(app).post('/api/music/setup/runtime-install?runtime=test-cuda').then((response) => response);
    await vi.waitFor(() => expect(finishProbe).toEqual(expect.any(Function)));
    const second = await request(app).post('/api/music/setup/runtime-install?runtime=test-cuda');
    expect(second.status).toBe(200);
    expect(second.text).toContain('Another Test CUDA install is already running');
    expect(setup.spawn).not.toHaveBeenCalled();

    finishProbe({ status: 'available', gpus: [], maxVramGb: 40, error: null });
    const firstResponse = await first;
    expect(firstResponse.status).toBe(200);
    expect(firstResponse.text).toContain('Starting Test CUDA install.');
    expect(setup.spawn).toHaveBeenCalledTimes(1);
  });

  it('POST /setup/runtime-install releases its CUDA claim when the probe rejects', async () => {
    cuda.probe = vi.fn().mockRejectedValueOnce(new Error('CUDA probe failed'));
    gen.healthy = false;

    await expect(request(app).post('/api/music/setup/runtime-install?runtime=minimax-music3'))
      .rejects.toThrow('fetch failed');
    expect(setup.spawn).not.toHaveBeenCalled();

    cuda.probe = null;
    const retry = await request(app).post('/api/music/setup/runtime-install?runtime=minimax-music3');
    expect(retry.status).toBe(200);
    expect(retry.text).toContain('VRAM requirement has not been measured');
    expect(retry.text).not.toContain('already running');
    expect(setup.spawn).not.toHaveBeenCalled();
  });

  it('GET /engines flags a host-incompatible engine so the UI can hide Install', async () => {
    gen.unsupportedPlatform = 'musicgen';
    const r = await request(app).get('/api/music/engines');
    const musicgen = r.body.engines.find((e) => e.id === 'musicgen');
    expect(musicgen.platformSupported).toBe(false);
    expect(musicgen.platformLabel).toContain('Apple Silicon');
    expect(r.body.engines.find((e) => e.id === 'acestep').platformSupported).toBe(true);
  });

  it('GET /models/:engine returns the merged model list; 404s for an unknown engine', async () => {
    const r = await request(app).get('/api/music/models/acestep');
    expect(r.status).toBe(200);
    expect(r.body.models).toEqual([{ id: 'm', name: 'M', userAdded: false }]);
    expect((await request(app).get('/api/music/models/nope')).status).toBe(404);
  });

  it('POST /models registers the model then streams the download (SSE)', async () => {
    models.add.mockResolvedValueOnce({ id: 'facebook/musicgen-large', repo: 'facebook/musicgen-large', name: 'musicgen-large' });
    const r = await request(app).post('/api/music/models').send({ engine: 'musicgen', repo: 'facebook/musicgen-large' });
    expect(r.status).toBe(200);
    // A user-added repo has no shipped contract about which paths matter, so it
    // gets the full snapshot (no ignore patterns).
    expect(sse.run).toHaveBeenCalledWith(expect.objectContaining({
      repos: [{ repo: 'facebook/musicgen-large', ignore: [] }],
    }));
    // Registered only AFTER the download landed in the cache.
    expect(models.add).toHaveBeenCalledWith({ engine: 'musicgen', repo: 'facebook/musicgen-large', name: undefined });
  });

  it('POST /models pins a fixed MLX download to the shipped revision', async () => {
    const r = await request(app).post('/api/music/models').send({
      engine: 'minimax-music3-mlx', repo: 'mlx-community/MiniMax-Music3-8bit',
    });
    expect(r.status).toBe(200);
    expect(models.add).not.toHaveBeenCalled();
    expect(sse.run).toHaveBeenCalledWith(expect.objectContaining({
      repos: [{
        repo: 'mlx-community/MiniMax-Music3-8bit',
        ignore: [],
        revision: '10aa4ca578d04c6f5256c1bc22fc8405a09602b5',
      }],
    }));
    expect(cache.calls).toContainEqual({
      repo: 'mlx-community/MiniMax-Music3-8bit',
      revision: '10aa4ca578d04c6f5256c1bc22fc8405a09602b5',
    });
  });

  it('POST /models forwards a shipped fixed model\'s downloadIgnore to the download stream', async () => {
    const r = await request(app).post('/api/music/models').send({ engine: 'minimax-music3', repo: 'MiniMaxAI/MiniMax-Music3' });
    expect(r.status).toBe(200);
    // Skipping the bundled captioner and original-format checkpoints keeps the
    // roughly 29 GB the diffusers pipeline actually loads on the user's disk.
    expect(sse.run).toHaveBeenCalledWith(expect.objectContaining({
      repos: [{
        repo: 'MiniMaxAI/MiniMax-Music3',
        ignore: ['qwen_7B/*', 'flowmatching_vae.pth', 'dav.pth', 'figures/*'],
      }],
    }));
    // A shipped model is already in the engine's list — nothing to register.
    expect(models.add).not.toHaveBeenCalled();
  });

  it('POST /models rolls back the registration when the download did not land', async () => {
    cache.cached = false; // download failed/cancelled → repo not in cache
    const r = await request(app).post('/api/music/models').send({ engine: 'musicgen', repo: 'someorg/typo-repo' });
    expect(r.status).toBe(200); // the SSE stream still completes (with its error frames)
    expect(sse.run).toHaveBeenCalled();
    // Registered up front (durable before the client's refresh), then rolled back
    // because the weights never landed — net: not persisted.
    expect(models.add).toHaveBeenCalled();
    expect(models.remove).toHaveBeenCalledWith({ engine: 'musicgen', id: 'someorg/typo-repo' });
  });

  it('POST /models rejects an unknown engine / invalid repo before downloading', async () => {
    expect((await request(app).post('/api/music/models').send({ engine: 'nope', repo: 'a/b' })).status).toBe(400);
    expect((await request(app).post('/api/music/models').send({ engine: 'musicgen', repo: 'bad' })).status).toBe(400);
    expect(models.add).not.toHaveBeenCalled();
    expect(sse.run).not.toHaveBeenCalled();
  });

  it('DELETE /models/:engine/* de-registers a slash-containing repo id', async () => {
    models.remove.mockResolvedValueOnce(true);
    const r = await request(app).delete('/api/music/models/musicgen/facebook/musicgen-large');
    expect(r.status).toBe(200);
    expect(r.body.removed).toBe(true);
    expect(models.remove).toHaveBeenCalledWith({ engine: 'musicgen', id: 'facebook/musicgen-large' });
  });

  it('previews the instrumental caption without queueing and records exactly that caption on submit', async () => {
    const prompt = '  **warm** `analog` folk\n';
    const body = { prompt, instrumentalOnly: true };
    const preview = await request(app).post('/api/music/prompt-preview').send(body);
    expect(preview.status).toBe(200);
    expect(mediaQueue.enqueue).not.toHaveBeenCalled();
    expect(preview.body).toEqual({
      sentPrompt: `${prompt}\n\nInstrumental only. Do not include sung, spoken, chanted, choir, or background vocals. Carry the lead melody with the described instruments or textures.`,
      promptAdditions: [{
        id: 'instrumental-only', label: 'Instrumental only',
        text: 'Instrumental only. Do not include sung, spoken, chanted, choir, or background vocals. Carry the lead melody with the described instruments or textures.',
      }],
    });
    const submitted = await request(app).post('/api/music/generate').send(body);
    expect(submitted.status).toBe(202);
    const params = mediaQueue.enqueue.mock.calls[0][0].params;
    expect(params.prompt).toBe(preview.body.sentPrompt);
    expect(params.musicStudio).toMatchObject({ authoredPrompt: prompt, ...preview.body });
    const { buildSidecarArgs } = await vi.importActual('../services/pipeline/musicGen.js');
    const { args } = buildSidecarArgs({ engineId: 'musicgen', prompt: params.prompt });
    expect(args[args.indexOf('--text') + 1]).toBe(preview.body.sentPrompt);
  });

  it('previews exact lyric bytes and additions that the sidecar sends, without changing the authored sheet', async () => {
    const actual = await vi.importActual('../services/pipeline/musicGen.js');
    for (const body of [
      { prompt: 'folk', engine: 'minimax-music3', lyrics: '  [verse]\nKeep these words\n \t', durationMode: 'auto' },
      { prompt: 'folk', engine: 'minimax-music3-mlx', lyrics: '', durationSec: 180, instrumentalOnly: true },
      { prompt: 'folk', engine: 'acestep15', lyrics: '  [verse]\nKeep the ending \n', durationSec: 60 },
      { prompt: 'folk', engine: 'acestep15', lyrics: '  \n', durationSec: 60 },
    ]) {
      mediaQueue.enqueue.mockClear();
      const preview = await request(app).post('/api/music/prompt-preview').send(body);
      expect(preview.status).toBe(200);
      expect(mediaQueue.enqueue).not.toHaveBeenCalled();
      const submitted = await request(app).post('/api/music/generate').send(body);
      expect(submitted.status).toBe(202);
      const params = mediaQueue.enqueue.mock.calls[0][0].params;
      expect(params.musicStudio.authoredLyrics).toBe(body.lyrics);
      expect(params.musicStudio.sentLyrics).toBe(preview.body.sentLyrics);
      expect(params.musicStudio.lyricAdditions).toEqual(preview.body.lyricAdditions);
      const { args } = actual.buildSidecarArgs({
        engineId: params.engine, prompt: params.prompt, lyrics: params.lyrics,
        durationSec: body.durationSec ?? 60,
      });
      expect(args[args.indexOf('--lyrics') + 1]).toBe(preview.body.sentLyrics);
      if (!body.instrumentalOnly) expect(preview.body.sentLyrics.startsWith(body.lyrics)).toBe(true);
    }
  });

  it('refuses lyrics beyond the authored cap before preview or queueing', async () => {
    const body = { prompt: 'folk', engine: 'minimax-music3', lyrics: ' '.repeat(20001) };
    expect((await request(app).post('/api/music/prompt-preview').send(body)).status).toBe(400);
    expect((await request(app).post('/api/music/generate').send(body)).status).toBe(400);
    expect(mediaQueue.enqueue).not.toHaveBeenCalled();
  });

  it('refuses over-limit caption previews instead of returning a shortened caption', async () => {
    const preview = await request(app).post('/api/music/prompt-preview').send({ prompt: 'x'.repeat(8001) });
    expect(preview.status).toBe(400);
    expect(mediaQueue.enqueue).not.toHaveBeenCalled();
  });

  it('POST /generate queues a new track render', async () => {
    const r = await request(app).post('/api/music/generate').send({
      prompt: 'warm folk', lyrics: '[verse] hi', engine: 'acestep', title: 'My Song',
    });
    expect(r.status).toBe(202);
    expect(mediaQueue.enqueue).toHaveBeenCalledWith(expect.objectContaining({
      kind: 'audio', params: expect.objectContaining({ prompt: 'warm folk', lyrics: '[verse] hi', engine: 'acestep' }),
    }));
  });

  it('POST /generate queues an explicitly selected remote model without resolving it locally', async () => {
    const peer = { id: '00000000-0000-4000-8000-000000000001', enabled: true };
    remoteProvider.peers = [peer];
    remoteProvider.resolve.mockResolvedValueOnce({
      peer,
      capability: {
        kind: 'audio',
        engine: 'remote-audio',
        engineName: 'Remote Audio',
        modelId: 'example/model',
        lyrics: true,
        autoDuration: false,
        minDurationSec: 10,
        maxDurationSec: 120,
      },
    });

    const r = await request(app).post('/api/music/generate').send({
      prompt: 'private idea for [email protected]',
      engine: 'remote-audio',
      modelId: 'example/model',
      durationSec: 30,
      mediaProviderPeerId: peer.id,
      remoteMusicProfile: {
        style: 'cinematic',
        mood: 'dreamy',
        tempo: 'slow',
        energy: 'medium',
        instruments: ['strings', 'synthesizer'],
      },
    });

    expect(r.status).toBe(202);
    expect(remoteProvider.resolve).toHaveBeenCalledWith(peer, {
      kind: 'audio', engine: 'remote-audio', modelId: 'example/model',
    });
    expect(models.list).not.toHaveBeenCalled();
    expect(mediaQueue.enqueue).toHaveBeenCalledWith(expect.objectContaining({
      kind: 'audio',
      params: expect.objectContaining({
        engine: 'remote-audio',
        modelId: 'example/model',
        prompt: '',
        lyrics: '',
        remoteMedia: {
          wireVersion: 1,
          peerId: peer.id,
          reconcile: false,
          cancelRequested: false,
          profile: {
            style: 'cinematic',
            mood: 'dreamy',
            tempo: 'slow',
            energy: 'medium',
            instruments: ['strings', 'synthesizer'],
          },
          request: {
            engine: 'remote-audio',
            modelId: 'example/model',
            durationSec: 30,
          },
        },
        musicStudio: expect.objectContaining({ lyricsEnabled: true }),
      }),
    }));
    const remoteMarker = mediaQueue.enqueue.mock.calls[0][0].params.remoteMedia;
    expect(JSON.stringify(remoteMarker)).not.toContain('[email protected]');
  });

  it('POST /generate fails before queueing when remote routing is incomplete or unavailable', async () => {
    const peer = { id: '00000000-0000-4000-8000-000000000001', enabled: true };
    remoteProvider.peers = [peer];

    const incomplete = await request(app).post('/api/music/generate').send({
      prompt: 'pulse', engine: 'remote-audio', mediaProviderPeerId: peer.id,
    });
    expect(incomplete.status).toBe(400);

    remoteProvider.resolve.mockRejectedValueOnce(new ServerError('Provider busy', {
      status: 429,
      code: 'MEDIA_PROVIDER_BUSY',
    }));
    const busy = await request(app).post('/api/music/generate').send({
      prompt: 'pulse',
      engine: 'remote-audio',
      modelId: 'example/model',
      mediaProviderPeerId: peer.id,
      remoteMusicProfile: { style: 'ambient', mood: 'calm' },
    });
    expect(busy.status).toBe(429);
    expect(busy.body.code).toBe('MEDIA_PROVIDER_BUSY');
    expect(mediaQueue.enqueue).not.toHaveBeenCalled();
  });

  // Lyrics reach an allowlisted peer since ADR
  // docs/decisions/2026-08-22-federated-media-input-assets.md rule 2 — but only
  // when the resolved capability advertises BOTH that the model sings and that
  // the peer's build carries the words.
  const remoteLyricRequest = (peer, overrides = {}) => ({
    prompt: 'private concept',
    lyrics: '[verse]\nCall [email protected]',
    engine: 'remote-audio',
    modelId: 'example/model',
    mediaProviderPeerId: peer.id,
    remoteMusicProfile: { style: 'ambient', mood: 'calm' },
    ...overrides,
  });
  const remoteLyricCapability = (overrides) => ({
    kind: 'audio',
    engine: 'remote-audio',
    engineName: 'Remote Audio',
    modelId: 'example/model',
    autoDuration: false,
    minDurationSec: 10,
    maxDurationSec: 120,
    ...overrides,
  });

  it('POST /generate refuses lyrics when the peer does not advertise them, rather than rendering instrumental', async () => {
    const peer = { id: '00000000-0000-4000-8000-000000000001', enabled: true };
    remoteProvider.peers = [peer];
    // A peer that does not publish a feature list cannot establish that its
    // build accepts lyrics. Absent must read as false or every such render is a
    // hard 400 the user cannot act on.
    remoteProvider.resolve.mockResolvedValueOnce({
      peer, capability: remoteLyricCapability({ lyrics: true }),
    });

    const r = await request(app).post('/api/music/generate').send(remoteLyricRequest(peer));

    expect(r.status).toBe(400);
    expect(r.body.code).toBe('MEDIA_PROVIDER_LYRICS_UNSUPPORTED');
    expect(r.body.error).toContain('not reporting');
    expect(mediaQueue.enqueue).not.toHaveBeenCalled();
  });

  it('POST /generate identifies a peer build that omits the lyrics feature', async () => {
    const peer = { id: '00000000-0000-4000-8000-000000000001', enabled: true };
    remoteProvider.peers = [peer];
    remoteProvider.resolve.mockResolvedValueOnce({
      peer,
      capability: remoteLyricCapability({ lyrics: true }),
      status: { features: ['inputAssets'] },
    });

    const r = await request(app).post('/api/music/generate').send(remoteLyricRequest(peer));

    expect(r.status).toBe(400);
    expect(r.body.code).toBe('MEDIA_PROVIDER_LYRICS_UNSUPPORTED');
    expect(r.body.error).toContain('Update the peer');
    expect(mediaQueue.enqueue).not.toHaveBeenCalled();
  });

  it('POST /generate accepts lyrics from a peer that advertises only the status-root feature', async () => {
    const peer = { id: '00000000-0000-4000-8000-000000000001', enabled: true };
    remoteProvider.peers = [peer];
    // The provider advertises the build-level feature at the status root.
    remoteProvider.resolve.mockResolvedValueOnce({
      peer,
      capability: remoteLyricCapability({ lyrics: true }),
      status: { features: ['lyrics', 'inputAssets'] },
    });

    const r = await request(app).post('/api/music/generate').send(remoteLyricRequest(peer));

    expect(r.status).toBe(202);
    expect(mediaQueue.enqueue.mock.calls[0][0].params.remoteMedia.lyrics)
      .toContain('Call [email protected]');
  });

  it('POST /generate still refuses an instrumental-only model on a build that speaks the lyrics feature', async () => {
    const peer = { id: '00000000-0000-4000-8000-000000000001', enabled: true };
    remoteProvider.peers = [peer];
    // The two facts are independent, and the root feature answers only one of
    // them: this build carries lyrics, but the model picked cannot sing. A
    // gate that collapsed to the feature alone would queue a render that comes
    // back wordless, which is the failure the per-capability field prevented.
    remoteProvider.resolve.mockResolvedValueOnce({
      peer,
      capability: remoteLyricCapability({ lyrics: false }),
      status: { features: ['lyrics'] },
    });

    const r = await request(app).post('/api/music/generate').send(remoteLyricRequest(peer));

    expect(r.status).toBe(400);
    expect(r.body.error).toContain('instrumental audio only');
    expect(mediaQueue.enqueue).not.toHaveBeenCalled();
  });

  it('POST /generate carries lyrics on the remote marker while the style prompt stays fixed-vocabulary', async () => {
    const peer = { id: '00000000-0000-4000-8000-000000000001', enabled: true };
    remoteProvider.peers = [peer];
    remoteProvider.resolve.mockResolvedValueOnce({
      peer,
      capability: remoteLyricCapability({ lyrics: true }),
      status: { features: ['lyrics', 'inputAssets'] },
    });

    const r = await request(app).post('/api/music/generate').send(remoteLyricRequest(peer));

    expect(r.status).toBe(202);
    const params = mediaQueue.enqueue.mock.calls[0][0].params;
    expect(params.remoteMedia.lyrics).toContain('Call [email protected]');
    // The style prompt is still rendered from the fixed profile, so the
    // free-form concept text never leaves this machine — only the words the
    // user asked to be sung do.
    expect(params.remoteMedia.profile).toMatchObject({ style: 'ambient', mood: 'calm' });
    expect(params.remoteMedia.request.prompt).toBeUndefined();
    expect(params.prompt).toBe('');
    expect(params.lyrics).toBe('');
    expect(JSON.stringify(params.remoteMedia)).not.toContain('private concept');
  });

  it('POST /generate omits lyrics from the remote marker for an instrumental-only take', async () => {
    const peer = { id: '00000000-0000-4000-8000-000000000001', enabled: true };
    remoteProvider.peers = [peer];
    remoteProvider.resolve.mockResolvedValueOnce({
      peer,
      capability: remoteLyricCapability({ lyrics: true }),
      status: { features: ['lyrics', 'inputAssets'] },
    });

    const r = await request(app).post('/api/music/generate')
      .send(remoteLyricRequest(peer, { instrumentalOnly: true }));

    // `instrumentalOnly` wins over supplied lyrics on every lane. Omitted (not
    // empty-stringed) so this submits — and idempotency-hashes — exactly the
    // body a pre-lyrics build sent for the same job.
    expect(r.status).toBe(202);
    expect(mediaQueue.enqueue.mock.calls[0][0].params.remoteMedia)
      .not.toHaveProperty('lyrics');
  });

  it('POST /generate forwards MiniMax auto duration mode to the queue', async () => {
    const r = await request(app).post('/api/music/generate').send({
      prompt: 'warm folk',
      lyrics: `[verse]\n${'word '.repeat(180)}\n[outro]`,
      engine: 'minimax-music3',
      durationMode: 'auto',
    });

    expect(r.status).toBe(202);
    expect(mediaQueue.enqueue).toHaveBeenCalledWith(expect.objectContaining({
      params: expect.objectContaining({
      engine: 'minimax-music3',
      lyrics: expect.stringContaining('[verse]'),
      durationMode: 'auto',
      }),
    }));
  });

  it('POST /generate queues an existing-track render', async () => {
    tracks.getTrack.mockResolvedValueOnce({ id: 'track-1', title: 'Existing' });
    const r = await request(app).post('/api/music/generate').send({ prompt: 'beat', trackId: 'track-1' });
    expect(r.status).toBe(202);
    expect(mediaQueue.enqueue).toHaveBeenCalledWith(expect.objectContaining({ params: expect.objectContaining({ musicStudio: expect.objectContaining({ trackId: 'track-1' }) }) }));
  });

  it('POST /generate marks non-lyric jobs as not lyric-enabled', async () => {
    tracks.getTrack.mockResolvedValueOnce({ id: 'track-1', title: 'Has Lyrics', lyrics: 'keep me' });
    // MusicGen is not lyric-aware; even if the client sends lyrics:'' the update must omit lyrics.
    await request(app).post('/api/music/generate').send({ prompt: 'bed', lyrics: '', engine: 'musicgen', trackId: 'track-1' });
    expect(mediaQueue.enqueue).toHaveBeenCalledWith(expect.objectContaining({ params: expect.objectContaining({ musicStudio: expect.objectContaining({ lyricsEnabled: false }) }) }));
  });

  it('POST /generate records the empty conditioning snapshot when lyrics are absent', async () => {
    tracks.getTrack.mockResolvedValueOnce({ id: 'track-1', title: 'Song', lyrics: 'old words' });
    await request(app).post('/api/music/generate').send({ prompt: 'folk', engine: 'acestep', trackId: 'track-1' }); // no lyrics field
    expect(mediaQueue.enqueue).toHaveBeenCalledWith(expect.objectContaining({ params: expect.objectContaining({ lyrics: '', musicStudio: expect.objectContaining({ lyricsEnabled: true }) }) }));
  });

  it('POST /generate separates authored text from instrumental engine conditioning', async () => {
    tracks.getTrack.mockResolvedValueOnce({ id: 'track-1', title: 'Song', lyrics: 'keep these words' });
    const r = await request(app).post('/api/music/generate').send({
      prompt: 'warm folk',
      lyrics: '[verse] do not condition with this',
      instrumentalOnly: true,
      engine: 'acestep',
      trackId: 'track-1',
    });

    expect(r.status).toBe(202);
    expect(mediaQueue.enqueue).toHaveBeenCalledWith(expect.objectContaining({
      params: expect.objectContaining({
        prompt: expect.stringContaining('Instrumental only.'),
        lyrics: '',
        musicStudio: expect.objectContaining({
          authoredPrompt: 'warm folk',
          authoredLyrics: '[verse] do not condition with this',
          lyricsEnabled: true,
          lyricsProvided: true,
          instrumentalOnly: true,
        }),
      }),
    }));
    const queuedPrompt = mediaQueue.enqueue.mock.calls[0][0].params.prompt;
    expect(queuedPrompt).toContain('Do not include sung, spoken, chanted, choir, or background vocals.');
    expect(queuedPrompt).not.toBe('warm folk');
  });

  it('POST /generate keeps the track destination in the job snapshot', async () => {
    tracks.getTrack.mockResolvedValueOnce({ id: 'track-1' });
    await request(app).post('/api/music/generate').send({ prompt: 'beat', engine: 'musicgen', trackId: 'track-1' });
    expect(mediaQueue.enqueue).toHaveBeenCalledWith(expect.objectContaining({ params: expect.objectContaining({ musicStudio: expect.objectContaining({ trackId: 'track-1' }) }) }));
  });

  it('POST /generate preserves an explicit lyric clear in the job snapshot', async () => {
    tracks.getTrack.mockResolvedValueOnce({ id: 'track-1', title: 'Song', lyrics: 'old words' });
    await request(app).post('/api/music/generate').send({ prompt: 'instrumental', lyrics: '', engine: 'acestep', trackId: 'track-1' });
    expect(mediaQueue.enqueue).toHaveBeenCalledWith(expect.objectContaining({ params: expect.objectContaining({ lyrics: '', musicStudio: expect.objectContaining({ lyricsEnabled: true }) }) }));
  });

  it('POST /generate validates trackId BEFORE rendering (no wasted render)', async () => {
    tracks.getTrack.mockResolvedValueOnce(null);
    const r = await request(app).post('/api/music/generate').send({ prompt: 'x', trackId: 'gone' });
    expect(r.status).toBe(404);
    expect(mediaQueue.enqueue).not.toHaveBeenCalled();
  });

  it('POST /generate resolves a USER-INSTALLED model id to the queued job', async () => {
    models.list.mockResolvedValueOnce([
      { id: 'm', name: 'M', userAdded: false },
      { id: 'someorg/big-musicgen', name: 'Big', repo: 'someorg/big-musicgen', userAdded: true },
    ]);
    await request(app).post('/api/music/generate').send({ prompt: 'x', engine: 'musicgen', modelId: 'someorg/big-musicgen' });
    expect(mediaQueue.enqueue).toHaveBeenCalledWith(expect.objectContaining({ params: expect.objectContaining({ repo: 'someorg/big-musicgen', modelId: 'someorg/big-musicgen' }) }));
  });

  it('POST /generate rejects an unknown modelId BEFORE rendering', async () => {
    models.list.mockResolvedValueOnce([{ id: 'm', name: 'M', userAdded: false }]);
    const r = await request(app).post('/api/music/generate').send({ prompt: 'x', engine: 'musicgen', modelId: 'gone/removed' });
    expect(r.status).toBe(400);
    expect(r.body.code).toBe('PIPELINE_MUSIC_UNKNOWN_MODEL');
    expect(mediaQueue.enqueue).not.toHaveBeenCalled();
  });

  it('POST /generate carries album metadata to the queued job', async () => {
    await request(app).post('/api/music/generate').send({ prompt: 'x', engine: 'musicgen', albumId: 'album-1' });
    expect(mediaQueue.enqueue).toHaveBeenCalledWith(expect.objectContaining({ params: expect.objectContaining({ musicStudio: expect.objectContaining({ albumId: 'album-1' }) }) }));
  });

  it('POST /generate with an unknown trackId 404s and does not queue', async () => {
    tracks.getTrack.mockResolvedValueOnce(null);
    const r = await request(app).post('/api/music/generate').send({ prompt: 'x', trackId: 'track-missing' });
    expect(r.status).toBe(404);
    expect(tracks.updateTrack).not.toHaveBeenCalled();
    expect(mediaQueue.enqueue).not.toHaveBeenCalled();
  });

  it('POST /generate rejects an unknown engine before queueing (no wrong-backend output)', async () => {
    const r = await request(app).post('/api/music/generate').send({ prompt: 'x', engine: 'acestep-v2' });
    expect(r.status).toBe(400);
    expect(r.body.code).toBe('PIPELINE_MUSIC_UNKNOWN_ENGINE');
    expect(mediaQueue.enqueue).not.toHaveBeenCalled();
  });

  it('POST /generate rejects a missing prompt', async () => {
    const r = await request(app).post('/api/music/generate').send({ engine: 'acestep' });
    expect(r.status).toBe(400);
    expect(mediaQueue.enqueue).not.toHaveBeenCalled();
  });

  it('POST /generate acknowledges even when rendering will later report a runtime failure', async () => {
    const r = await request(app).post('/api/music/generate').send({ prompt: 'x', engine: 'acestep' });
    expect(r.status).toBe(202);
    expect(mediaQueue.enqueue).toHaveBeenCalled();
  });

  it('POST /generate returns a queued audio job with the Music Studio destination tag', async () => {
    const r = await request(app).post('/api/music/generate').send({
      prompt: 'warm folk', lyrics: '[verse] hi', engine: 'acestep', title: 'My Song', albumId: 'album-1',
    });
    expect(r.status).toBe(202);
    expect(r.body).toEqual({ jobId: 'job-1', position: 1, status: 'queued' });
    expect(mediaQueue.enqueue).toHaveBeenCalledWith(expect.objectContaining({
      kind: 'audio',
      params: expect.objectContaining({
        prompt: 'warm folk', lyrics: '[verse] hi', engine: 'acestep',
        musicStudio: expect.objectContaining({ trackId: null, title: 'My Song', albumId: 'album-1', lyricsEnabled: true }),
      }),
    }));
  });

  it('POST /generate rejects a duplicate live render for the same track', async () => {
    mediaQueue.jobs = [{ id: 'existing-job', kind: 'audio', status: 'running', params: { musicStudio: { trackId: 'track-1' } } }];
    tracks.getTrack.mockResolvedValueOnce({ id: 'track-1' });
    const r = await request(app).post('/api/music/generate').send({ prompt: 'beat', trackId: 'track-1' });
    expect(r.status).toBe(409);
    expect(r.body.code).toBe('PIPELINE_MUSIC_BUSY');
    expect(r.body.context.jobId).toBe('existing-job');
    expect(mediaQueue.enqueue).not.toHaveBeenCalled();
  });
});