Get Jaguar CD BIOS through auth and into CD Player UI

The retail CD BIOS now passes the session-2 pregap audio authentication
and reaches its built-in CD Player interface (verified via headless
screenshot at 326x240).

Boot flow now requires five hooks in JaguarExecuteNew (gated by
vjs.useCDBIOS):

  $050A9C - JaguarInstallCDAuthBypass (BNE.W $0504EC -> 2x NOP)
  $050AB2 - DSPWriteLong $F1B4C8 = $80010000 (DSP-result fake)
  $050B0C - JaguarWriteLong $FB000  = $0A      (post-BSR success)
  $0505FA - JaguarWriteLong $1AE00C = $20010001 (CD response magic)
  $192E46 - JaguarWriteWord $1A6800 = $0001     (BIOS GPU mailbox)

The TryReadAuthRedirect path in cdintf.c serves real TAIRTAIR audio
from track 30 BIN for the auth window (LBA 139668-139816). cdintf.c
needs `#undef fprintf` after streams/file_stream_transforms.h to
prevent fprintf->rfprintf macro substitution from silently eating
debug logs.

Adds test/headless.py - libretro.py-based local test harness so we
can drive the core without round-tripping logs through iOS. Includes
optional --screenshot flag to dump the framebuffer as PPM.

Game-specific boot (jumping from BIOS CD Player into Primal Rage's
own boot.abs) is the next milestone.

Co-Authored-By: Claude Opus 4.7 <[email protected]>

Author: JoeMatt

docs/spike-jaguar-cd-support.md

@@ -457,3 +457,29 @@ Phase 1 only: disc image loading and CDIntf implementation, with no behavioral c
 - `libretro.c` -- Content detection, BIOS loading, disc control interface
 - `src/jaguar.c` -- BIOS loading path in JaguarReset()
 - `src/settings.h` -- CD-related settings
+
+---
+
+## Disc Image Format Support (2026-04-17)
+
+| Format     | Status        | Notes |
+|------------|---------------|-------|
+| BIN/CUE    | **Supported** | Multi-file (redump-style) and single-file. Multi-session CUEs get an 11400-frame inter-session gap (MAME/CHD convention). Verified booting Primal Rage past BIOS handoff. |
+| CDI        | **Supported** | DiscJuggler V2/V3/V3.5. Per-track absolute `start_lba` from CDI metadata is authoritative (preserves Jaguar-specific session 2 placement). |
+| CHD        | Best-effort   | Reads, but virtual pregaps in CHD strip the audio data the BIOS authenticates against. Not recommended for Jaguar CD. Use BIN/CUE or CDI. |
+| ISO        | Not supported | No multi-session, no audio tracks, no pregap — incompatible with Jaguar CD layout. |
+
+### Why CHD is unreliable for Jaguar CD
+
+The Jaguar CD BIOS authenticates session 2 by reading the 149-frame pregap that
+precedes the first data track and DSP-decoding the audio data found there.
+CHD encodes audio pregaps as `VAUDIO` (virtual) and does not store the actual
+samples — so the BIOS reads silence and authentication fails. CDI and BIN/CUE
+preserve the original sectors inline.
+
+### Auth-bypass hooks
+
+Earlier development pre-stuffed BIOS auth-result memory locations to force
+authentication to "pass" so we could test downstream code paths. With the
+BIN/CUE inter-session-gap fix and the addition of CDI support, those hooks
+are no longer required and have been removed (`src/jaguar.c`).

libretro.c

@@ -26,6 +26,7 @@ int64_t rfread(void* buffer, size_t elem_size, size_t elem_count, RFILE* stream)
 #include "dsp.h"
 #include "joystick.h"
 #include "settings.h"
+#include "gpu.h"
 #include "tom.h"
 #include "state.h"
 #include "m68000/m68kinterface.h"
@@ -240,7 +241,7 @@ static bool update_option_visibility(void)
          strlcpy(key, base, sizeof(key));
          strlcat(key, "_retropad_start", sizeof(key));
          environ_cb(RETRO_ENVIRONMENT_SET_CORE_OPTIONS_DISPLAY, &option_display);
-         
+
          strlcpy(key, base, sizeof(key));
          strlcat(key, "_retropad_l1", sizeof(key));
          environ_cb(RETRO_ENVIRONMENT_SET_CORE_OPTIONS_DISPLAY, &option_display);
@@ -806,7 +807,7 @@ void retro_get_system_info(struct retro_system_info *info)
 #endif
    info->library_version  = "v2.1.0" GIT_VERSION;
    info->need_fullpath    = true;
-   info->valid_extensions = "j64|jag|cue|chd";
+   info->valid_extensions = "j64|jag|cue|cdi|chd";
 }
 
 void retro_get_system_av_info(struct retro_system_av_info *info)
@@ -959,6 +960,7 @@ static bool load_external_cd_bios(void)
       "jaguarcd.bin",
       "jagcd.bin",
       "[BIOS] Atari Jaguar CD (World).j64",
+      "[BIOS] Atari Jaguar Developer CD (World).j64",
       NULL
    };
 
@@ -1177,6 +1179,18 @@ bool retro_load_game(const struct retro_game_info *info)
       jaguarRunAddress = GET32(jagMemSpace, 0x800404);
       jaguarCartInserted = true;
       jaguarROMSize = cdBiosSize;
+
+      /* The boot ROM runs a GPU-based cart authentication check that loops
+       * forever in emulation (the GPU security code at $F032EC never
+       * converges). The boot ROM checks:
+       *   1. bit 0 of $800408 → if set, wait for GPU to finish
+       *   2. GPU RAM $F03000 → if == $03D0DEAD, jump to cart entry
+       * We skip the GPU wait by clearing bit 0 here (survives JaguarReset
+       * since jagMemSpace is not randomized). The GPU magic is written
+       * after JaguarReset() below since GPUReset() randomizes GPU RAM. */
+      jagMemSpace[0x80040B] &= 0xFE;
+      fprintf(stderr, "[CD-TRACE] Boot ROM wait bypass applied at $80040B (value now $%02X)\n",
+              jagMemSpace[0x80040B]);
    }
    else
    {