fix(headphones): recover from stalled check with Try Again + two-strike fail (#1241)

* fix(headphones): recover from stalled check instead of looping

If the user picks "I did not hear anything" the troubleshooting panel
now includes a Try Again button that resets the radio selection so
they can replay. A second "none" fails the check with
"Could not hear test sound." so the equipment flow restarts rather
than stalling indefinitely (seen on Firefox where the audio `playing`
event sometimes doesn't fire).

Also drop the `soundPlayed &&` gate on the pass branch — Firefox
occasionally misses the `playing` event, which was blocking legitimate
passes. Add `[HeadphonesCheck]` console logs on play/end/pause and a
`noneSelectedCount` field in the setupSteps debug payload for future
diagnosis.

Covered by HC-005 (retry button appears, no fail on first "none") and
new HC-005b (second "none" fails with error message).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* address Copilot review: fix off-by-one, reset counter, poll in tests

Component:
- Increment noneSelectedCountRef *before* logging so the setupSteps
  debug payload matches the strike number that caused it (first "none"
  logs 1, second logs 2 and fails). Previously the log was off by one.
- Reset the counter inside resetProgress() so that switching output
  device via "Choose a different device" starts a fresh two-strike
  window (prevents the next "none" from being mistakenly counted as
  strike #2).
- Troubleshooting heading: h2 → h3 to preserve heading hierarchy
  under the existing step h2, and fix "Lets" → "Let's".

Tests:
- HC-005 / HC-005b: replace synchronous asserts on the statuses/errors
  arrays with expect.poll. setHeadphonesStatus fires from a useEffect
  (async to the radio click), so the prior asserts could race.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: JamesPHoughton

client/src/intro-exit/setup/HeadphonesCheck.jsx

@@ -29,6 +29,7 @@ export function HeadphonesCheck({ setHeadphonesStatus, setErrorMessage }) {
   const [speakerIteration, setSpeakerIteration] = useState(0);
   const [noDevicesTimeout, setNoDevicesTimeout] = useState(false);
   const [isPlaying, setIsPlaying] = useState(false);
+  const noneSelectedCountRef = useRef(0);
   const audioRef = useRef(null);
 
   useEffect(() => {
@@ -46,22 +47,30 @@ export function HeadphonesCheck({ setHeadphonesStatus, setErrorMessage }) {
 
   useEffect(() => {
     if (soundPlayed && soundSelected) {
+      if (soundSelected === "none") {
+        noneSelectedCountRef.current += 1;
+      }
       const logEntry = {
         step: "headphonesCheck",
         event: "soundSelected",
         value: soundSelected,
         errors: [],
-        debug: {},
+        debug: { noneSelectedCount: noneSelectedCountRef.current },
         timestamp: new Date().toISOString(),
       };
 
       player.append("setupSteps", logEntry);
-      console.log("Sound played successfully", logEntry);
-      if (soundPlayed && soundSelected === "clock") {
+      console.log("[HeadphonesCheck] Sound selected", logEntry);
+      if (soundSelected === "clock") {
         setHeadphonesStatus("pass");
+      } else if (soundSelected === "none" && noneSelectedCountRef.current >= 2) {
+        // User said "I did not hear anything" twice — fail so the equipment
+        // check restarts rather than stalling indefinitely.
+        if (setErrorMessage) setErrorMessage("Could not hear test sound.");
+        setHeadphonesStatus("fail");
       }
     }
-  }, [soundPlayed, soundSelected, setHeadphonesStatus, player]);
+  }, [soundPlayed, soundSelected, setHeadphonesStatus, setErrorMessage, player]);
 
   const devices = useDevices();
 
@@ -102,6 +111,8 @@ export function HeadphonesCheck({ setHeadphonesStatus, setErrorMessage }) {
     setSoundPlayed(false);
     setSoundSelected("");
     setHeadphonesStatus("waiting");
+    // Fresh attempt after a device switch — don't let earlier strikes carry over.
+    noneSelectedCountRef.current = 0;
   };
 
   const handleSpeakerSelected = async (speaker) => {
@@ -139,6 +150,7 @@ export function HeadphonesCheck({ setHeadphonesStatus, setErrorMessage }) {
     const audio = audioRef.current;
     if (!audio) return undefined;
     const onPlaying = () => {
+      console.log("[HeadphonesCheck] Audio playing event fired");
       setIsPlaying(true);
       player.append("setupSteps", {
         step: "headphonesCheck",
@@ -148,8 +160,14 @@ export function HeadphonesCheck({ setHeadphonesStatus, setErrorMessage }) {
         timestamp: new Date().toISOString(),
       });
     };
-    const onEnded = () => setIsPlaying(false);
-    const onPause = () => setIsPlaying(false);
+    const onEnded = () => {
+      console.log("[HeadphonesCheck] Audio ended");
+      setIsPlaying(false);
+    };
+    const onPause = () => {
+      console.log("[HeadphonesCheck] Audio paused");
+      setIsPlaying(false);
+    };
     audio.addEventListener("playing", onPlaying);
     audio.addEventListener("ended", onEnded);
     audio.addEventListener("pause", onPause);
@@ -275,17 +293,27 @@ export function HeadphonesCheck({ setHeadphonesStatus, setErrorMessage }) {
             )}
 
             {soundSelected === "none" && (
-              <>
-                <h2>🤔 Lets troubleshoot:</h2>
+              <div className="mt-4 p-4 bg-yellow-50 border border-yellow-200 rounded-lg">
+                <h3>🤔 Let&apos;s troubleshoot:</h3>
                 <ul>
                   <li>Are your headphones connected or paired?</li>
                   <li>Is the volume turned up?</li>
                   {canSelectSpeaker && (
                     <li>Is this device selected as the output above?</li>
                   )}
                 </ul>
-                <p>After checking these, please play the sound again.</p>
-              </>
+                <p className="mt-2">After checking these, try again:</p>
+                <Button
+                  className="mt-2"
+                  testId="retrySound"
+                  handleClick={() => {
+                    setSoundSelected("");
+                    setSoundPlayed(false);
+                  }}
+                >
+                  Try Again
+                </Button>
+              </div>
             )}
           </section>
         )}

playwright/component-tests/equipment-check/HeadphonesCheck.ct.jsx

@@ -220,13 +220,14 @@ test('HC-004: wrong sound identification does not pass', async ({ mount, page })
   expect(latestStatus).not.toBe('pass');
 });
 
-/** HC-005: "I did not hear anything" shows troubleshooting */
+/** HC-005: "I did not hear anything" shows troubleshooting and Try Again button */
 test('HC-005: no-sound option shows troubleshooting', async ({ mount, page }) => {
   await installAudioMocks(page);
 
+  const statuses = [];
   await mount(
     <HeadphonesCheck
-      setHeadphonesStatus={() => {}}
+      setHeadphonesStatus={(s) => statuses.push(s)}
       setErrorMessage={() => {}}
     />,
     { hooksConfig: hooksConfig() },
@@ -236,10 +237,52 @@ test('HC-005: no-sound option shows troubleshooting', async ({ mount, page }) =>
   await page.locator('[data-test="playSound"]').click();
   await expect(page.locator('[data-test="soundSelect"]')).toBeVisible();
 
+  // First "none" — shows troubleshooting + Try Again, does NOT fail
   await page.locator('[data-test="soundSelect"] input[value="none"]').check();
 
   await expect(page.locator('text=Are your headphones connected')).toBeVisible();
   await expect(page.locator('text=Is the volume turned up')).toBeVisible();
+  await expect(page.locator('[data-test="retrySound"]')).toBeVisible();
+  // `setHeadphonesStatus` fires from a useEffect (async to the click), so a
+  // sync assertion could miss a late "fail" update. Poll briefly to confirm
+  // fail never arrives.
+  await expect.poll(() => statuses.includes('fail'), { timeout: 300 }).toBe(false);
+});
+
+/** HC-005b: second "none" selection fails the check */
+test('HC-005b: second no-sound fails the check', async ({ mount, page }) => {
+  await installAudioMocks(page);
+
+  const statuses = [];
+  const errors = [];
+  await mount(
+    <HeadphonesCheck
+      setHeadphonesStatus={(s) => statuses.push(s)}
+      setErrorMessage={(m) => errors.push(m)}
+    />,
+    { hooksConfig: hooksConfig() },
+  );
+
+  await advanceToStep3(page);
+
+  // First attempt: play, select "none", see troubleshooting
+  await page.locator('[data-test="playSound"]').click();
+  await page.locator('[data-test="soundSelect"] input[value="none"]').check();
+  await expect(page.locator('[data-test="retrySound"]')).toBeVisible();
+
+  // Click Try Again — resets radio selection
+  await page.locator('[data-test="retrySound"]').click();
+  await expect(page.locator('[data-test="soundSelect"]')).not.toBeVisible();
+
+  // Second attempt: play again, select "none" again
+  await page.locator('[data-test="playSound"]').click();
+  await expect(page.locator('[data-test="soundSelect"]')).toBeVisible();
+  await page.locator('[data-test="soundSelect"] input[value="none"]').check();
+
+  // Should now fail. `setHeadphonesStatus` / `setErrorMessage` fire from a
+  // useEffect, so poll rather than asserting synchronously.
+  await expect.poll(() => statuses).toContain('fail');
+  await expect.poll(() => errors).toContain('Could not hear test sound.');
 });
 
 /** HC-006: "Choose a different device" resets to speaker selection */