Expose candidate truth in Spooty workspace inspector

docs/spooty-operations-snapshot.md

@@ -9,16 +9,16 @@ The MVP reports truth Spooty already owns without a schema migration:
 - selected YouTube candidate title, author, score, and reason from `TrackEntity`
 - raw failure evidence from `TrackEntity.error`
 - download retry count from `TrackEntity.downloadAttemptCount`
-- rejected YouTube candidates from `TrackEntity.rejectedYoutubeUrls`
+- rejected YouTube candidate explanations from `TrackEntity.rejectedYoutubeCandidatesJson`
+- legacy rejected YouTube candidate URLs from `TrackEntity.rejectedYoutubeUrls`
 - playlist and single-song counts from `PlaylistEntity.isTrack`
 - queue depth and active jobs from BullMQ queues `track-search-processor` and `track-download-processor`
 - Spotify connection presence from the stored Spotify user token
 
-The endpoint intentionally does not infer candidate scoring history. Selected candidate metadata is persisted when Spooty chooses a candidate. Rejected candidates are still persisted only as URL strings.
+The endpoint intentionally does not infer candidate scoring history. Selected candidate metadata is persisted when Spooty chooses a candidate. Rejected candidate metadata is persisted when a selected candidate is rejected by manual retry or download failure. Older rows and URL-only cases fall back to rejected candidate objects containing only `url`.
 
 Future persistence work is required for:
 
 - full searched candidate history
-- structured rejected candidate metadata beyond URL
 - structured error class fields stored at write time instead of classified from the persisted raw error string
 - operation attempt history across search and download phases

src/backend/src/operations/operations.service.ts

@@ -10,6 +10,7 @@ import {
   ErrorClass,
   FailureTruth,
   OperationsSnapshot,
+  RejectedCandidateTruth,
   SpootyOperation,
   TrackTruth,
 } from './operations.types';
@@ -204,7 +205,15 @@ export class OperationsService {
     };
   }
 
-  private parseRejectedCandidates(track: TrackEntity): string[] {
+  private parseRejectedCandidates(
+    track: TrackEntity,
+  ): RejectedCandidateTruth[] {
+    const structured = this.parseRejectedCandidateJson(track);
+
+    if (structured.length) {
+      return structured;
+    }
+
     if (!track.rejectedYoutubeUrls) {
       return [];
     }
@@ -212,7 +221,52 @@ export class OperationsService {
     try {
       const parsed = JSON.parse(track.rejectedYoutubeUrls);
       return Array.isArray(parsed)
-        ? parsed.filter((item) => typeof item === 'string')
+        ? parsed
+            .filter((item) => typeof item === 'string')
+            .map((url) => ({ url }))
+        : [];
+    } catch {
+      return [];
+    }
+  }
+
+  private parseRejectedCandidateJson(
+    track: TrackEntity,
+  ): RejectedCandidateTruth[] {
+    if (!track.rejectedYoutubeCandidatesJson) {
+      return [];
+    }
+
+    try {
+      const parsed = JSON.parse(track.rejectedYoutubeCandidatesJson);
+      return Array.isArray(parsed)
+        ? parsed
+            .filter(
+              (item) =>
+                !!item &&
+                typeof item === 'object' &&
+                typeof item.url === 'string',
+            )
+            .map((item) => ({
+              url: item.url,
+              ...(typeof item.title === 'string' ? { title: item.title } : {}),
+              ...(typeof item.author === 'string'
+                ? { author: item.author }
+                : {}),
+              ...(typeof item.score === 'number' ? { score: item.score } : {}),
+              ...(typeof item.reason === 'string'
+                ? { reason: item.reason }
+                : {}),
+              ...(typeof item.rejectionClass === 'string'
+                ? { rejectionClass: item.rejectionClass }
+                : {}),
+              ...(typeof item.rejectionSummary === 'string'
+                ? { rejectionSummary: item.rejectionSummary }
+                : {}),
+              ...(typeof item.rejectedAt === 'string'
+                ? { rejectedAt: item.rejectedAt }
+                : {}),
+            }))
         : [];
     } catch {
       return [];

src/backend/src/operations/operations.types.ts

@@ -16,6 +16,27 @@ export type ErrorClass =
   | 'FILE_WRITE_FAILED'
   | 'UNKNOWN_DOWNLOAD_ERROR';
 
+export type RejectionClass =
+  | 'DOWNLOAD_FAILED'
+  | 'YOUTUBE_VIDEO_UNAVAILABLE'
+  | 'YOUTUBE_AGE_GATED'
+  | 'YOUTUBE_NO_FORMATS'
+  | 'YOUTUBE_PRIVATE_VIDEO'
+  | 'YOUTUBE_EXTRACTION_FAILURE'
+  | 'UNKNOWN_DOWNLOAD_ERROR'
+  | 'MANUAL_RETRY';
+
+export interface RejectedCandidateTruth {
+  url: string;
+  title?: string;
+  author?: string;
+  score?: number;
+  reason?: string;
+  rejectionClass?: RejectionClass;
+  rejectionSummary?: string;
+  rejectedAt?: string;
+}
+
 export interface TrackTruth {
   id: number;
   artist: string;
@@ -35,7 +56,7 @@ export interface TrackTruth {
   errorSummary?: string;
   errorDetail?: string;
   rejectedCandidateCount: number;
-  rejectedCandidates: string[];
+  rejectedCandidates: RejectedCandidateTruth[];
 }
 
 export interface FailureTruth extends TrackTruth {}

src/backend/src/track/track.entity.ts

@@ -42,6 +42,9 @@ export class TrackEntity {
   @Column({ nullable: true, type: 'text' })
   rejectedYoutubeUrls?: string;
 
+  @Column({ nullable: true, type: 'text' })
+  rejectedYoutubeCandidatesJson?: string;
+
   @Column({ default: 0 })
   downloadAttemptCount?: number;
 

src/backend/src/track/track.service.ts

@@ -24,6 +24,32 @@ type ClientTrack = Omit<Partial<TrackEntity>, 'rejectedYoutubeUrls'> & {
   rejectedYoutubeUrls?: string[];
 };
 
+type RejectionClass =
+  | 'DOWNLOAD_FAILED'
+  | 'YOUTUBE_VIDEO_UNAVAILABLE'
+  | 'YOUTUBE_AGE_GATED'
+  | 'YOUTUBE_NO_FORMATS'
+  | 'YOUTUBE_PRIVATE_VIDEO'
+  | 'YOUTUBE_EXTRACTION_FAILURE'
+  | 'UNKNOWN_DOWNLOAD_ERROR'
+  | 'MANUAL_RETRY';
+
+interface RejectedYoutubeCandidate {
+  url: string;
+  title?: string;
+  author?: string;
+  score?: number;
+  reason?: string;
+  rejectionClass?: RejectionClass;
+  rejectionSummary?: string;
+  rejectedAt: string;
+}
+
+interface RejectionReason {
+  rejectionClass: RejectionClass;
+  rejectionSummary: string;
+}
+
 @WebSocketGateway()
 @Injectable()
 export class TrackService {
@@ -110,6 +136,161 @@ export class TrackService {
     return JSON.stringify([...new Set(urls)].slice(0, 20));
   }
 
+  private parseRejectedYoutubeCandidates(
+    track: TrackEntity,
+  ): RejectedYoutubeCandidate[] {
+    if (!track.rejectedYoutubeCandidatesJson) {
+      return [];
+    }
+
+    try {
+      const parsed = JSON.parse(track.rejectedYoutubeCandidatesJson);
+      return Array.isArray(parsed)
+        ? parsed.filter(
+            (item): item is RejectedYoutubeCandidate =>
+              !!item &&
+              typeof item === 'object' &&
+              typeof item.url === 'string' &&
+              typeof item.rejectedAt === 'string',
+          )
+        : [];
+    } catch {
+      return [];
+    }
+  }
+
+  private stringifyRejectedYoutubeCandidates(
+    candidates: RejectedYoutubeCandidate[],
+  ): string {
+    const byUrl = new Map<string, RejectedYoutubeCandidate>();
+
+    for (const candidate of candidates) {
+      if (candidate.url) {
+        byUrl.set(candidate.url, candidate);
+      }
+    }
+
+    return JSON.stringify([...byUrl.values()].slice(-20));
+  }
+
+  private buildRejectedYoutubeCandidate(
+    track: TrackEntity,
+    reason: RejectionReason,
+  ): RejectedYoutubeCandidate | null {
+    if (!track.youtubeUrl) {
+      return null;
+    }
+
+    return {
+      url: track.youtubeUrl,
+      ...(track.selectedYoutubeTitle
+        ? { title: track.selectedYoutubeTitle }
+        : {}),
+      ...(track.selectedYoutubeAuthor
+        ? { author: track.selectedYoutubeAuthor }
+        : {}),
+      ...(typeof track.selectedYoutubeScore === 'number'
+        ? { score: track.selectedYoutubeScore }
+        : {}),
+      ...(track.selectedYoutubeReason
+        ? { reason: track.selectedYoutubeReason }
+        : {}),
+      ...reason,
+      rejectedAt: new Date().toISOString(),
+    };
+  }
+
+  private rejectCurrentYoutubeCandidate(
+    track: TrackEntity,
+    reason: RejectionReason,
+  ): {
+    rejectedYoutubeUrls: string;
+    rejectedYoutubeCandidatesJson: string;
+  } {
+    const rejectedUrls = this.parseRejectedYoutubeUrls(track);
+    const rejectedCandidates = this.parseRejectedYoutubeCandidates(track);
+    const rejectedCandidate = this.buildRejectedYoutubeCandidate(track, reason);
+
+    if (rejectedCandidate) {
+      if (!rejectedUrls.includes(rejectedCandidate.url)) {
+        rejectedUrls.push(rejectedCandidate.url);
+      }
+
+      rejectedCandidates.push(rejectedCandidate);
+    }
+
+    return {
+      rejectedYoutubeUrls: this.stringifyRejectedYoutubeUrls(rejectedUrls),
+      rejectedYoutubeCandidatesJson:
+        this.stringifyRejectedYoutubeCandidates(rejectedCandidates),
+    };
+  }
+
+  private classifyRejection(error?: string): RejectionReason {
+    if (!error) {
+      return {
+        rejectionClass: 'UNKNOWN_DOWNLOAD_ERROR',
+        rejectionSummary: 'Unknown download error',
+      };
+    }
+
+    const normalized = error.toLowerCase();
+
+    if (normalized.includes('sign in to confirm your age')) {
+      return {
+        rejectionClass: 'YOUTUBE_AGE_GATED',
+        rejectionSummary: 'YouTube video is age-gated',
+      };
+    }
+
+    if (normalized.includes('private video')) {
+      return {
+        rejectionClass: 'YOUTUBE_PRIVATE_VIDEO',
+        rejectionSummary: 'YouTube video is private',
+      };
+    }
+
+    if (
+      normalized.includes('only images are available') ||
+      normalized.includes('requested format is not available') ||
+      normalized.includes('no downloadable audio/video formats')
+    ) {
+      return {
+        rejectionClass: 'YOUTUBE_NO_FORMATS',
+        rejectionSummary: 'No downloadable YouTube audio format',
+      };
+    }
+
+    if (
+      normalized.includes('video unavailable') ||
+      normalized.includes('this video is not available') ||
+      normalized.includes('selected video unavailable')
+    ) {
+      return {
+        rejectionClass: 'YOUTUBE_VIDEO_UNAVAILABLE',
+        rejectionSummary: 'YouTube video is unavailable',
+      };
+    }
+
+    if (
+      normalized.includes('failed to parse yt-dlp search output') ||
+      normalized.includes('yt-dlp exited with code') ||
+      normalized.includes('failed to start yt-dlp') ||
+      normalized.includes('yt-dlp exceeded maximum runtime') ||
+      normalized.includes('unable to download webpage')
+    ) {
+      return {
+        rejectionClass: 'YOUTUBE_EXTRACTION_FAILURE',
+        rejectionSummary: 'YouTube extraction failed',
+      };
+    }
+
+    return {
+      rejectionClass: 'DOWNLOAD_FAILED',
+      rejectionSummary: 'Download failed',
+    };
+  }
+
   async retry(id: number): Promise<void> {
     const track = await this.get(id);
 
@@ -118,11 +299,10 @@ export class TrackService {
       return;
     }
 
-    const rejectedUrls = this.parseRejectedYoutubeUrls(track);
-
-    if (track.youtubeUrl && !rejectedUrls.includes(track.youtubeUrl)) {
-      rejectedUrls.push(track.youtubeUrl);
-    }
+    const rejectedCandidateFields = this.rejectCurrentYoutubeCandidate(track, {
+      rejectionClass: 'MANUAL_RETRY',
+      rejectionSummary: 'Rejected by manual retry',
+    });
 
     await this.update(id, {
       ...track,
@@ -131,7 +311,7 @@ export class TrackService {
       selectedYoutubeAuthor: null,
       selectedYoutubeScore: null,
       selectedYoutubeReason: null,
-      rejectedYoutubeUrls: this.stringifyRejectedYoutubeUrls(rejectedUrls),
+      ...rejectedCandidateFields,
       downloadAttemptCount: 0,
       error: null,
       status: TrackStatusEnum.New,
@@ -293,13 +473,17 @@ export class TrackService {
       error = toSafeErrorMessage(err);
     }
 
-    const rejectedUrls = this.parseRejectedYoutubeUrls(track);
     const nextAttemptCount = (track.downloadAttemptCount || 0) + 1;
     const maxAttempts = this.getMaxDownloadAttempts();
-
-    if (error && track.youtubeUrl && !rejectedUrls.includes(track.youtubeUrl)) {
-      rejectedUrls.push(track.youtubeUrl);
-    }
+    const rejectedCandidateFields = error
+      ? this.rejectCurrentYoutubeCandidate(track, this.classifyRejection(error))
+      : {
+          rejectedYoutubeUrls: this.stringifyRejectedYoutubeUrls(
+            this.parseRejectedYoutubeUrls(track),
+          ),
+          rejectedYoutubeCandidatesJson:
+            track.rejectedYoutubeCandidatesJson || JSON.stringify([]),
+        };
 
     if (error && nextAttemptCount < maxAttempts) {
       this.logger.warn(
@@ -314,7 +498,7 @@ export class TrackService {
         selectedYoutubeAuthor: null,
         selectedYoutubeScore: null,
         selectedYoutubeReason: null,
-        rejectedYoutubeUrls: this.stringifyRejectedYoutubeUrls(rejectedUrls),
+        ...rejectedCandidateFields,
         downloadAttemptCount: nextAttemptCount,
         error: null,
         status: TrackStatusEnum.New,
@@ -327,7 +511,7 @@ export class TrackService {
     const updatedTrack = {
       ...track,
       status: error ? TrackStatusEnum.Error : TrackStatusEnum.Completed,
-      rejectedYoutubeUrls: this.stringifyRejectedYoutubeUrls(rejectedUrls),
+      ...rejectedCandidateFields,
       downloadAttemptCount: error ? nextAttemptCount : 0,
       ...(error ? { error } : { error: null }),
     };

src/frontend/src/app/app.component.html

@@ -11,8 +11,11 @@
 
     <div class="truth-strip">
       <span class="truth-pill" [class.connected]="spotifyConnected">
-        <i class="fa-solid" [ngClass]="spotifyConnected ? 'fa-circle-check' : 'fa-plug'"></i>
-        {{ spotifyConnected ? 'Spotify connected' : 'Spotify disconnected' }}
+        <i
+          class="fa-solid"
+          [ngClass]="spotifyConnected ? 'fa-circle-check' : 'fa-plug'"
+        ></i>
+        {{ spotifyConnected ? "Spotify connected" : "Spotify disconnected" }}
       </span>
     </div>
   </header>
@@ -49,7 +52,11 @@
         <i class="fa-solid fa-rotate-left"></i>
         Reset Current Tab
       </button>
-      <button class="button reset-button" type="button" (click)="resetAllLayouts()">
+      <button
+        class="button reset-button"
+        type="button"
+        (click)="resetAllLayouts()"
+      >
         <i class="fa-solid fa-rotate"></i>
         Reset All Tabs
       </button>
@@ -88,8 +95,11 @@
             [class.connected]="spotifyConnected"
             (click)="connectSpotify()"
           >
-            <i class="fa-solid" [ngClass]="spotifyConnected ? 'fa-circle-check' : 'fa-plug'"></i>
-            {{ spotifyConnected ? 'Spotify connected' : 'Connect Spotify' }}
+            <i
+              class="fa-solid"
+              [ngClass]="spotifyConnected ? 'fa-circle-check' : 'fa-plug'"
+            ></i>
+            {{ spotifyConnected ? "Spotify connected" : "Connect Spotify" }}
           </button>
 
           <div class="intake-form">
@@ -121,7 +131,10 @@
           />
 
           <div class="truth-note">
-            <p>Runtime download root: {{ archiveListing?.root || archiveDestination || 'loading...' }}</p>
+            <p>
+              Runtime download root:
+              {{ archiveListing?.root || archiveDestination || "loading..." }}
+            </p>
             <p>Per-run destination routing: pending backend support</p>
           </div>
 
@@ -135,7 +148,9 @@
             <ng-container *ngIf="songs$ | async as songs">
               <div class="metric-card">
                 <span>Spotify</span>
-                <strong [class.online]="spotifyConnected">{{ spotifyConnected ? 'Connected' : 'Disconnected' }}</strong>
+                <strong [class.online]="spotifyConnected">{{
+                  spotifyConnected ? "Connected" : "Disconnected"
+                }}</strong>
               </div>
               <div class="metric-card">
                 <span>Playlists</span>
@@ -160,18 +175,31 @@
               <p>One collapsed row per playlist run.</p>
             </div>
             <div class="buttons has-addons">
-              <button class="button is-outlined is-success" title="Remove completed from list" (click)="deleteCompleted()">
+              <button
+                class="button is-outlined is-success"
+                title="Remove completed from list"
+                (click)="deleteCompleted()"
+              >
                 <i class="fa-solid fa-check"></i>
               </button>
-              <button class="button is-outlined is-danger" title="Remove failed from list" (click)="deleteFailed()">
+              <button
+                class="button is-outlined is-danger"
+                title="Remove failed from list"
+                (click)="deleteFailed()"
+              >
                 <i class="fa-solid fa-xmark"></i>
               </button>
             </div>
           </div>
 
           <ng-container *ngIf="playlists$ | async as playlists">
-            <app-playlist-box *ngFor="let playlist of playlists" [playlist]="playlist"></app-playlist-box>
-            <p *ngIf="playlists?.length === 0" class="empty-state">No playlists</p>
+            <app-playlist-box
+              *ngFor="let playlist of playlists"
+              [playlist]="playlist"
+            ></app-playlist-box>
+            <p *ngIf="playlists?.length === 0" class="empty-state">
+              No playlists
+            </p>
           </ng-container>
         </section>
 
@@ -184,7 +212,10 @@
           </div>
 
           <ng-container *ngIf="songs$ | async as songs">
-            <app-playlist-box *ngFor="let playlist of songs" [playlist]="playlist"></app-playlist-box>
+            <app-playlist-box
+              *ngFor="let playlist of songs"
+              [playlist]="playlist"
+            ></app-playlist-box>
             <p *ngIf="songs?.length === 0" class="empty-state">No songs</p>
           </ng-container>
         </section>
@@ -193,9 +224,14 @@
           <div class="section-toolbar">
             <div>
               <h2>Archive Browser</h2>
-              <p>Root: {{ archiveListing?.root || 'loading...' }}</p>
+              <p>Root: {{ archiveListing?.root || "loading..." }}</p>
             </div>
-            <button class="button is-small reset-button" type="button" [class.is-loading]="archiveLoading" (click)="refreshArchive()">
+            <button
+              class="button is-small reset-button"
+              type="button"
+              [class.is-loading]="archiveLoading"
+              (click)="refreshArchive()"
+            >
               <i class="fa-solid fa-rotate"></i>
               Refresh
             </button>
@@ -226,24 +262,40 @@
                 placeholder="Search archive"
               />
               <div class="select is-small">
-                <select [(ngModel)]="archiveSort" aria-label="Sort archive files">
-                  <option *ngFor="let sortMode of archiveSortModes" [ngValue]="sortMode">
+                <select
+                  [(ngModel)]="archiveSort"
+                  aria-label="Sort archive files"
+                >
+                  <option
+                    *ngFor="let sortMode of archiveSortModes"
+                    [ngValue]="sortMode"
+                  >
                     {{ sortMode }}
                   </option>
                 </select>
               </div>
             </div>
 
-            <p *ngIf="archiveFileCount() === 0" class="empty-state">No downloaded files found.</p>
+            <p *ngIf="archiveFileCount() === 0" class="empty-state">
+              No downloaded files found.
+            </p>
 
-            <section *ngFor="let group of archiveGroups()" class="archive-group">
+            <section
+              *ngFor="let group of archiveGroups()"
+              class="archive-group"
+            >
               <h3>
                 <i class="fa-solid fa-folder"></i>
                 {{ group.folder }}
               </h3>
 
               <div *ngFor="let file of group.files" class="archive-file-card">
-                <i class="fa-solid" [ngClass]="hasFolder(file) ? 'fa-folder-tree' : 'fa-file-audio'"></i>
+                <i
+                  class="fa-solid"
+                  [ngClass]="
+                    hasFolder(file) ? 'fa-folder-tree' : 'fa-file-audio'
+                  "
+                ></i>
                 <div>
                   <strong>{{ file.name }}</strong>
                   <span>{{ folderPath(file) }}</span>
@@ -256,47 +308,157 @@
         </section>
 
         <section *ngSwitchCase="'candidate-inspector'" class="history-panel">
-          <ng-container *ngIf="selectedTrack$ | async as selectedTrack; else noTrackSelected">
+          <ng-container
+            *ngIf="
+              selectedTrack$ | async as selectedTrack;
+              else noTrackSelected
+            "
+          >
             <div class="section-toolbar">
               <div>
                 <h2>{{ selectedTrack.artist }} - {{ selectedTrack.name }}</h2>
                 <p>Status: {{ trackStatusLabel(selectedTrack.status) }}</p>
               </div>
-              <button class="button is-small reset-button" type="button" (click)="clearSelectedTrack()">
+              <button
+                class="button is-small reset-button"
+                type="button"
+                (click)="clearSelectedTrack()"
+              >
                 <i class="fa-solid fa-arrow-left"></i>
                 Back
               </button>
             </div>
 
+            <ng-container
+              *ngIf="
+                selectedTrackTruth(selectedTrack) as trackTruth;
+                else noTrackTruth
+              "
+            >
               <dl class="inspector-list">
                 <dt>Spotify URL</dt>
-              <dd><a [href]="selectedTrack.spotifyUrl" target="_blank">{{ selectedTrack.spotifyUrl || 'none' }}</a></dd>
+                <dd>
+                  <a [href]="selectedTrack.spotifyUrl" target="_blank">{{
+                    selectedTrack.spotifyUrl || "none"
+                  }}</a>
+                </dd>
                 <dt>Status</dt>
                 <dd>{{ trackStatusLabel(selectedTrack.status) }}</dd>
                 <dt>Download attempts</dt>
                 <dd>{{ selectedTrack.downloadAttemptCount || 0 }}</dd>
-              <dt>Error</dt>
-              <dd>{{ selectedTrack.error || 'none' }}</dd>
+                <dt>Error class</dt>
+                <dd>{{ errorClass(trackTruth) }}</dd>
+                <dt>Error summary</dt>
+                <dd>{{ errorSummary(trackTruth) }}</dd>
+                <dt>Error detail</dt>
+                <dd>
+                  <details
+                    *ngIf="errorDetail(trackTruth); else noErrorDetail"
+                    class="truth-detail"
+                  >
+                    <summary>Show backend evidence</summary>
+                    <pre>{{ errorDetail(trackTruth) }}</pre>
+                  </details>
+                  <ng-template #noErrorDetail>none</ng-template>
+                </dd>
               </dl>
 
               <div class="candidate-options">
-              <strong>Other options</strong>
-              <p *ngIf="selectedTrack.youtubeUrl">
-                Selected candidate:
-                <a [href]="selectedTrack.youtubeUrl" target="_blank">{{ selectedTrack.youtubeUrl }}</a>
-              </p>
-              <p>Rejected candidates: {{ rejectedUrls(selectedTrack).length }}</p>
-              <a *ngFor="let url of rejectedUrls(selectedTrack)" [href]="url" target="_blank">{{ url }}</a>
-              <p *ngIf="!selectedTrack.youtubeUrl && rejectedUrls(selectedTrack).length === 0" class="empty-state">
-                Candidate alternatives are not persisted yet. Future scoring history will appear here.
+                <strong>Selected candidate</strong>
+                <ng-container
+                  *ngIf="
+                    selectedCandidate(trackTruth) as candidate;
+                    else noSelectedCandidate
+                  "
+                >
+                  <dl class="candidate-card">
+                    <dt>URL</dt>
+                    <dd>
+                      <a [href]="candidate.url" target="_blank">{{
+                        candidate.url
+                      }}</a>
+                    </dd>
+                    <dt>Title</dt>
+                    <dd>{{ candidate.title || "unknown" }}</dd>
+                    <dt>Author</dt>
+                    <dd>{{ candidate.author || "unknown" }}</dd>
+                    <dt>Score</dt>
+                    <dd>{{ candidate.score ?? "unknown" }}</dd>
+                    <dt>Reason</dt>
+                    <dd>{{ candidate.reason || "unknown" }}</dd>
+                  </dl>
+                </ng-container>
+                <ng-template #noSelectedCandidate>
+                  <p class="empty-state compact">No selected candidate.</p>
+                </ng-template>
+
+                <strong
+                  >Rejected candidates:
+                  {{ rejectedCandidateCount(trackTruth) }}</strong
+                >
+                <div
+                  *ngFor="let candidate of rejectedCandidates(trackTruth)"
+                  class="candidate-card rejected-candidate-card"
+                >
+                  <dl>
+                    <dt>URL</dt>
+                    <dd>
+                      <a [href]="candidate.url" target="_blank">{{
+                        candidate.url
+                      }}</a>
+                    </dd>
+                    <dt>Title</dt>
+                    <dd>{{ candidate.title || "unknown" }}</dd>
+                    <dt>Author</dt>
+                    <dd>{{ candidate.author || "unknown" }}</dd>
+                    <dt>Score</dt>
+                    <dd>{{ candidate.score ?? "unknown" }}</dd>
+                    <dt>Reason</dt>
+                    <dd>{{ candidate.reason || "unknown" }}</dd>
+                    <dt>Rejection class</dt>
+                    <dd>{{ candidate.rejectionClass || "unknown" }}</dd>
+                    <dt>Rejection summary</dt>
+                    <dd>{{ candidate.rejectionSummary || "unknown" }}</dd>
+                    <dt>Rejected at</dt>
+                    <dd>{{ candidate.rejectedAt || "unknown" }}</dd>
+                  </dl>
+                </div>
+                <p
+                  *ngIf="rejectedCandidateCount(trackTruth) === 0"
+                  class="empty-state compact"
+                >
+                  No rejected candidates.
                 </p>
               </div>
             </ng-container>
 
+            <ng-template #noTrackTruth>
+              <div class="placeholder-panel">
+                <i class="fa-solid fa-database"></i>
+                <p>
+                  {{
+                    operationsSnapshotError ||
+                      "Waiting for backend operations truth."
+                  }}
+                </p>
+                <button
+                  class="button is-small reset-button"
+                  type="button"
+                  (click)="refreshOperationsSnapshot()"
+                >
+                  Refresh truth
+                </button>
+              </div>
+            </ng-template>
+          </ng-container>
+
           <ng-template #noTrackSelected>
             <div class="placeholder-panel">
               <i class="fa-solid fa-magnifying-glass-chart"></i>
-              <p>Select a track row inside an expanded playlist to inspect Spotify, YouTube, retry, and error details.</p>
+              <p>
+                Select a track row inside an expanded playlist to inspect
+                Spotify, YouTube, retry, and error details.
+              </p>
             </div>
             <ng-container *ngIf="allTracks$ | async as allTracks">
               <button

src/frontend/src/app/app.component.ts

@@ -1,18 +1,27 @@
 import { Component, OnDestroy } from '@angular/core';
-import {FormsModule} from "@angular/forms";
-import {CommonModule, NgFor} from "@angular/common";
-import {PlaylistService, PlaylistStatusEnum} from "./services/playlist.service";
-import {PlaylistBoxComponent} from "./components/playlist-box/playlist-box.component";
-import {VersionService} from "./services/version.service";
-import {map} from "rxjs";
-import {HttpClient} from "@angular/common/http";
-import {ArchiveService} from "./services/archive.service";
-import {ArchiveFile, ArchiveListing} from "./models/archive";
-import {Track, TrackStatusEnum} from "./models/track";
-import {TrackService} from "./services/track.service";
+import { FormsModule } from '@angular/forms';
+import { CommonModule, NgFor } from '@angular/common';
+import {
+  PlaylistService,
+  PlaylistStatusEnum,
+} from './services/playlist.service';
+import { PlaylistBoxComponent } from './components/playlist-box/playlist-box.component';
+import { VersionService } from './services/version.service';
+import { map } from 'rxjs';
+import { HttpClient } from '@angular/common/http';
+import { ArchiveService } from './services/archive.service';
+import { ArchiveFile, ArchiveListing } from './models/archive';
+import { Track, TrackStatusEnum } from './models/track';
+import { TrackService } from './services/track.service';
+import {
+  OperationsSnapshot,
+  RejectedCandidateTruth,
+  SelectedCandidateTruth,
+  TrackTruth,
+} from './models/operations-snapshot';
 
 export type SpootyPanelType =
-  'source-intake'
+  | 'source-intake'
   | 'queue-observatory'
   | 'playlist-history'
   | 'single-songs'
@@ -66,20 +75,62 @@ const WORKSPACE_TAB_LABELS: Record<SpootyWorkspaceTab, string> = {
 const DEFAULT_TAB_PANELS: Record<SpootyWorkspaceTab, SpootyPanelInstance[]> = {
   intake: [
     makePanel('source-intake', 24, 24, 520, 336, 'intake-source-intake'),
-    makePanel('queue-observatory', 568, 24, 520, 260, 'intake-queue-observatory'),
+    makePanel(
+      'queue-observatory',
+      568,
+      24,
+      520,
+      260,
+      'intake-queue-observatory',
+    ),
     makePanel('playlist-history', 24, 392, 760, 448, 'intake-playlist-history'),
     makePanel('single-songs', 820, 392, 520, 448, 'intake-single-songs'),
   ],
   archive: [
     makePanel('archive-browser', 24, 24, 900, 720, 'archive-archive-browser'),
     makePanel('source-intake', 960, 24, 420, 336, 'archive-source-intake'),
-    makePanel('queue-observatory', 960, 396, 420, 260, 'archive-queue-observatory'),
+    makePanel(
+      'queue-observatory',
+      960,
+      396,
+      420,
+      260,
+      'archive-queue-observatory',
+    ),
   ],
   diagnostics: [
-    makePanel('candidate-inspector', 24, 24, 620, 720, 'diagnostics-candidate-inspector'),
-    makePanel('playlist-history', 680, 24, 620, 520, 'diagnostics-playlist-history'),
-    makePanel('queue-observatory', 1320, 24, 420, 260, 'diagnostics-queue-observatory'),
-    makePanel('archive-browser', 1320, 320, 420, 420, 'diagnostics-archive-browser'),
+    makePanel(
+      'candidate-inspector',
+      24,
+      24,
+      620,
+      720,
+      'diagnostics-candidate-inspector',
+    ),
+    makePanel(
+      'playlist-history',
+      680,
+      24,
+      620,
+      520,
+      'diagnostics-playlist-history',
+    ),
+    makePanel(
+      'queue-observatory',
+      1320,
+      24,
+      420,
+      260,
+      'diagnostics-queue-observatory',
+    ),
+    makePanel(
+      'archive-browser',
+      1320,
+      320,
+      420,
+      420,
+      'diagnostics-archive-browser',
+    ),
   ],
 };
 
@@ -106,9 +157,11 @@ export function defaultWorkspaceState(): SpootyWorkspaceState {
   return defaultWorkspaceStateForTab('intake');
 }
 
-export function defaultWorkspaceStateForTab(tab: SpootyWorkspaceTab): SpootyWorkspaceState {
+export function defaultWorkspaceStateForTab(
+  tab: SpootyWorkspaceTab,
+): SpootyWorkspaceState {
   return {
-    panels: DEFAULT_TAB_PANELS[tab].map(panel => ({...panel})),
+    panels: DEFAULT_TAB_PANELS[tab].map((panel) => ({ ...panel })),
   };
 }
 
@@ -133,8 +186,8 @@ export function loadWorkspaceState(): SpootyWorkspaceState {
 
     const parsed = JSON.parse(raw) as SpootyWorkspaceState;
     const panels = parsed.panels
-      ?.filter(panel => panel?.id && panel?.type && PANEL_TITLES[panel.type])
-      .map(panel => ({
+      ?.filter((panel) => panel?.id && panel?.type && PANEL_TITLES[panel.type])
+      .map((panel) => ({
         ...panel,
         title: PANEL_TITLES[panel.type],
         x: snap(panel.x),
@@ -156,11 +209,23 @@ export function loadWorkspaceTabsState(): SpootyWorkspaceTabsState {
     if (raw) {
       const parsed = JSON.parse(raw) as SpootyWorkspaceTabsState;
       return {
-        activeTab: parsed.activeTab && WORKSPACE_TAB_LABELS[parsed.activeTab] ? parsed.activeTab : 'intake',
+        activeTab:
+          parsed.activeTab && WORKSPACE_TAB_LABELS[parsed.activeTab]
+            ? parsed.activeTab
+            : 'intake',
         tabs: {
-          intake: sanitizeWorkspaceState(parsed.tabs?.intake, defaultWorkspaceStateForTab('intake')),
-          archive: sanitizeWorkspaceState(parsed.tabs?.archive, defaultWorkspaceStateForTab('archive')),
-          diagnostics: sanitizeWorkspaceState(parsed.tabs?.diagnostics, defaultWorkspaceStateForTab('diagnostics')),
+          intake: sanitizeWorkspaceState(
+            parsed.tabs?.intake,
+            defaultWorkspaceStateForTab('intake'),
+          ),
+          archive: sanitizeWorkspaceState(
+            parsed.tabs?.archive,
+            defaultWorkspaceStateForTab('archive'),
+          ),
+          diagnostics: sanitizeWorkspaceState(
+            parsed.tabs?.diagnostics,
+            defaultWorkspaceStateForTab('diagnostics'),
+          ),
         },
       };
     }
@@ -182,8 +247,8 @@ function sanitizeWorkspaceState(
   fallback: SpootyWorkspaceState,
 ): SpootyWorkspaceState {
   const panels = state?.panels
-    ?.filter(panel => panel?.id && panel?.type && PANEL_TITLES[panel.type])
-    .map(panel => ({
+    ?.filter((panel) => panel?.id && panel?.type && PANEL_TITLES[panel.type])
+    .map((panel) => ({
       ...panel,
       title: PANEL_TITLES[panel.type],
       x: snap(panel.x),
@@ -207,9 +272,9 @@ function snap(value: number): number {
   standalone: true,
 })
 export class AppComponent implements OnDestroy {
-
-  url = ''
-  private readonly spotifyUrlPattern = /^https:\/\/open\.spotify\.com\/(track|playlist|album|artist)\/[a-zA-Z0-9]+/;
+  url = '';
+  private readonly spotifyUrlPattern =
+    /^https:\/\/open\.spotify\.com\/(track|playlist|album|artist)\/[a-zA-Z0-9]+/;
   private interaction?: {
     mode: 'drag' | 'resize';
     panelId: string;
@@ -220,6 +285,8 @@ export class AppComponent implements OnDestroy {
     startPanelW: number;
     startPanelH: number;
   };
+  private readonly operationsRefreshMs = 5000;
+  private operationsRefreshTimer?: number;
   readonly panelTypes: SpootyPanelType[] = [
     'source-intake',
     'queue-observatory',
@@ -228,7 +295,11 @@ export class AppComponent implements OnDestroy {
     'archive-browser',
     'candidate-inspector',
   ];
-  readonly workspaceTabs: SpootyWorkspaceTab[] = ['intake', 'archive', 'diagnostics'];
+  readonly workspaceTabs: SpootyWorkspaceTab[] = [
+    'intake',
+    'archive',
+    'diagnostics',
+  ];
   readonly archiveSortModes: ArchiveSortMode[] = ['newest', 'name', 'size'];
   selectedPanelType: SpootyPanelType = 'source-intake';
   workspaceTabsState: SpootyWorkspaceTabsState = loadWorkspaceTabsState();
@@ -237,8 +308,12 @@ export class AppComponent implements OnDestroy {
     return this.spotifyUrlPattern.test(this.url);
   }
   createLoading$ = this.playlistService.createLoading$;
-  playlists$ = this.playlistService.all$.pipe(map(items => items.filter(item => !item.isTrack)));
-  songs$ = this.playlistService.all$.pipe(map(items => items.filter(item => item.isTrack)));
+  playlists$ = this.playlistService.all$.pipe(
+    map((items) => items.filter((item) => !item.isTrack)),
+  );
+  songs$ = this.playlistService.all$.pipe(
+    map((items) => items.filter((item) => item.isTrack)),
+  );
   allTracks$ = this.trackService.all$;
   selectedTrack$ = this.trackService.selectedTrack$;
   version = this.versionService.getVersion();
@@ -250,6 +325,8 @@ export class AppComponent implements OnDestroy {
   archiveSearch = '';
   archiveSort: ArchiveSortMode = 'newest';
   trackStatuses = TrackStatusEnum;
+  operationsSnapshot?: OperationsSnapshot;
+  operationsSnapshotError = '';
 
   get activeWorkspaceTab(): SpootyWorkspaceTab {
     return this.workspaceTabsState.activeTab;
@@ -270,10 +347,18 @@ export class AppComponent implements OnDestroy {
     this.checkSpotifyStatus();
     this.fetchPlaylists();
     this.refreshArchive();
+    this.refreshOperationsSnapshot();
+    this.operationsRefreshTimer = window.setInterval(
+      () => this.refreshOperationsSnapshot(),
+      this.operationsRefreshMs,
+    );
   }
 
   ngOnDestroy(): void {
     this.stopWorkspaceInteraction();
+    if (this.operationsRefreshTimer) {
+      window.clearInterval(this.operationsRefreshTimer);
+    }
   }
 
   private bootstrapAuthTokenFromUrl(): void {
@@ -337,6 +422,18 @@ export class AppComponent implements OnDestroy {
     });
   }
 
+  refreshOperationsSnapshot(): void {
+    this.http.get<OperationsSnapshot>('/api/operations/snapshot').subscribe({
+      next: (snapshot) => {
+        this.operationsSnapshot = snapshot;
+        this.operationsSnapshotError = '';
+      },
+      error: () => {
+        this.operationsSnapshotError = 'Operations snapshot is unavailable.';
+      },
+    });
+  }
+
   formatBytes(sizeBytes: number): string {
     if (sizeBytes < 1024) {
       return `${sizeBytes} B`;
@@ -372,31 +469,56 @@ export class AppComponent implements OnDestroy {
     }
   }
 
-  rejectedUrls(track: Track): string[] {
-    if (Array.isArray(track.rejectedYoutubeUrls)) {
-      return track.rejectedYoutubeUrls;
-    }
-
-    if (!track.rejectedYoutubeUrls) {
-      return [];
-    }
-
-    try {
-      const parsed = JSON.parse(track.rejectedYoutubeUrls);
-      return Array.isArray(parsed) ? parsed.filter(item => typeof item === 'string') : [];
-    } catch {
-      return [];
-    }
-  }
-
   selectTrack(track: Track): void {
     this.trackService.select(track);
+    this.refreshOperationsSnapshot();
   }
 
   clearSelectedTrack(): void {
     this.trackService.clearSelection();
   }
 
+  selectedTrackTruth(track: Track): TrackTruth | undefined {
+    return this.findTrackTruth(track.id);
+  }
+
+  selectedCandidate(truth?: TrackTruth): SelectedCandidateTruth | undefined {
+    return truth?.selectedCandidate;
+  }
+
+  rejectedCandidates(truth?: TrackTruth): RejectedCandidateTruth[] {
+    return truth?.rejectedCandidates || [];
+  }
+
+  rejectedCandidateCount(truth?: TrackTruth): number {
+    return truth?.rejectedCandidateCount || 0;
+  }
+
+  errorClass(truth?: TrackTruth): string {
+    return truth?.errorClass || 'none';
+  }
+
+  errorSummary(truth?: TrackTruth): string {
+    return truth?.errorSummary || 'none';
+  }
+
+  errorDetail(truth?: TrackTruth): string {
+    return truth?.errorDetail || '';
+  }
+
+  private findTrackTruth(id: number): TrackTruth | undefined {
+    if (!this.operationsSnapshot) {
+      return undefined;
+    }
+
+    return [
+      ...this.operationsSnapshot.active.searching,
+      ...this.operationsSnapshot.active.downloading,
+      ...this.operationsSnapshot.recentFailures,
+      ...this.operationsSnapshot.recentTracks,
+    ].find((track) => track.id === id);
+  }
+
   getWorkspaceTabLabel(tab: SpootyWorkspaceTab): string {
     return WORKSPACE_TAB_LABELS[tab];
   }
@@ -410,7 +532,9 @@ export class AppComponent implements OnDestroy {
   }
 
   resetLayout(): void {
-    this.setActiveWorkspace(defaultWorkspaceStateForTab(this.activeWorkspaceTab));
+    this.setActiveWorkspace(
+      defaultWorkspaceStateForTab(this.activeWorkspaceTab),
+    );
   }
 
   resetAllLayouts(): void {
@@ -422,7 +546,9 @@ export class AppComponent implements OnDestroy {
     const files = this.archiveListing?.files || [];
     const query = this.archiveSearch.trim().toLowerCase();
     const filtered = query
-      ? files.filter(file => `${file.name} ${file.path}`.toLowerCase().includes(query))
+      ? files.filter((file) =>
+          `${file.name} ${file.path}`.toLowerCase().includes(query),
+        )
       : [...files];
 
     return filtered.sort((a, b) => {
@@ -441,7 +567,7 @@ export class AppComponent implements OnDestroy {
   archiveGroups(): { folder: string; files: ArchiveFile[] }[] {
     const groups = new Map<string, ArchiveFile[]>();
 
-    this.filteredArchiveFiles().forEach(file => {
+    this.filteredArchiveFiles().forEach((file) => {
       const folder = this.topLevelFolder(file);
       groups.set(folder, [...(groups.get(folder) || []), file]);
     });
@@ -454,7 +580,10 @@ export class AppComponent implements OnDestroy {
   }
 
   archiveTotalBytes(): number {
-    return this.filteredArchiveFiles().reduce((total, file) => total + file.sizeBytes, 0);
+    return this.filteredArchiveFiles().reduce(
+      (total, file) => total + file.sizeBytes,
+      0,
+    );
   }
 
   topLevelFolder(file: ArchiveFile): string {
@@ -490,7 +619,7 @@ export class AppComponent implements OnDestroy {
     }
 
     this.setActiveWorkspace({
-      panels: this.workspace.panels.filter(panel => panel.id !== panelId),
+      panels: this.workspace.panels.filter((panel) => panel.id !== panelId),
     });
   }
 
@@ -583,7 +712,9 @@ export class AppComponent implements OnDestroy {
 
   private startWorkspaceInteraction(): void {
     document.addEventListener('pointermove', this.handlePointerMove);
-    document.addEventListener('pointerup', this.handlePointerUp, {once: true});
+    document.addEventListener('pointerup', this.handlePointerUp, {
+      once: true,
+    });
   }
 
   private stopWorkspaceInteraction(): void {
@@ -593,7 +724,7 @@ export class AppComponent implements OnDestroy {
   }
 
   private bringPanelToFront(panelId: string): void {
-    const panel = this.workspace.panels.find(item => item.id === panelId);
+    const panel = this.workspace.panels.find((item) => item.id === panelId);
 
     if (!panel) {
       return;
@@ -601,16 +732,19 @@ export class AppComponent implements OnDestroy {
 
     this.setActiveWorkspace({
       panels: [
-        ...this.workspace.panels.filter(item => item.id !== panelId),
+        ...this.workspace.panels.filter((item) => item.id !== panelId),
         panel,
       ],
     });
   }
 
-  private updatePanel(panelId: string, changes: Partial<SpootyPanelInstance>): void {
+  private updatePanel(
+    panelId: string,
+    changes: Partial<SpootyPanelInstance>,
+  ): void {
     this.setActiveWorkspace({
-      panels: this.workspace.panels.map(panel =>
-        panel.id === panelId ? {...panel, ...changes} : panel
+      panels: this.workspace.panels.map((panel) =>
+        panel.id === panelId ? { ...panel, ...changes } : panel,
       ),
     });
   }
@@ -627,6 +761,9 @@ export class AppComponent implements OnDestroy {
   }
 
   private saveWorkspaceState(): void {
-    localStorage.setItem(WORKSPACE_TABS_STORAGE_KEY, JSON.stringify(this.workspaceTabsState));
+    localStorage.setItem(
+      WORKSPACE_TABS_STORAGE_KEY,
+      JSON.stringify(this.workspaceTabsState),
+    );
   }
 }

src/frontend/src/app/models/operations-snapshot.ts

@@ -0,0 +1,61 @@
+export interface SelectedCandidateTruth {
+  url: string;
+  title?: string;
+  author?: string;
+  score?: number;
+  reason?: string;
+}
+
+export interface RejectedCandidateTruth {
+  url: string;
+  title?: string;
+  author?: string;
+  score?: number;
+  reason?: string;
+  rejectionClass?: string;
+  rejectionSummary?: string;
+  rejectedAt?: string;
+}
+
+export interface TrackTruth {
+  id: number;
+  artist: string;
+  name: string;
+  status: string;
+  spotifyUrl?: string;
+  youtubeUrl?: string;
+  selectedCandidate?: SelectedCandidateTruth;
+  downloadAttemptCount?: number;
+  errorClass?: string;
+  errorSummary?: string;
+  errorDetail?: string;
+  rejectedCandidateCount: number;
+  rejectedCandidates: RejectedCandidateTruth[];
+}
+
+export interface OperationsSnapshot {
+  generatedAt: string;
+  runtime: {
+    operation: string;
+    spotifyConnected: boolean;
+    searchQueueDepth: number;
+    downloadQueueDepth: number;
+    activeSearches: number;
+    activeDownloads: number;
+  };
+  counters: {
+    playlists: number;
+    singleSongs: number;
+    tracks: number;
+    active: number;
+    completed: number;
+    failed: number;
+    retries: number;
+  };
+  active: {
+    searching: TrackTruth[];
+    downloading: TrackTruth[];
+  };
+  recentFailures: TrackTruth[];
+  recentTracks: TrackTruth[];
+}

src/frontend/src/styles.scss

@@ -112,6 +112,62 @@ body {
   overflow-wrap: anywhere;
 }
 
+.candidate-card {
+  display: block;
+  padding: 10px;
+  border: 1px solid rgba(126, 255, 180, 0.14);
+  border-radius: 8px;
+  background: rgba(255, 255, 255, 0.05);
+}
+
+.candidate-card,
+.candidate-card dl {
+  margin: 0;
+}
+
+.candidate-card dt {
+  color: #f1fff5;
+  font-size: 0.76rem;
+  font-weight: 900;
+  text-transform: uppercase;
+}
+
+.candidate-card dd {
+  margin: 0 0 8px;
+  color: #bcd1c4;
+  overflow-wrap: anywhere;
+}
+
+.candidate-card dd:last-child {
+  margin-bottom: 0;
+}
+
+.rejected-candidate-card {
+  border-color: rgba(255, 214, 102, 0.18);
+}
+
+.truth-detail summary {
+  color: #9fffc3;
+  cursor: pointer;
+  font-weight: 800;
+}
+
+.truth-detail pre {
+  margin-top: 8px;
+  padding: 10px;
+  border: 1px solid rgba(126, 255, 180, 0.14);
+  border-radius: 8px;
+  background: rgba(0, 0, 0, 0.22);
+  color: #dceee4;
+  font-size: 0.78rem;
+  overflow: auto;
+  white-space: pre-wrap;
+}
+
+.empty-state.compact {
+  padding: 10px;
+}
+
 @media (max-width: 900px) {
   .workspace-tabs {
     position: static;