feat(career): hours-per-genre odometer — honest wall-clock play time (#942)

Career v2, WS2. Nothing measured play time before (the achievements
plugin's final-position shortcut double-counts loops and mis-reads
seeks). Now:

- stats-recorder.js accrues WALL-CLOCK seconds across song:play/resume ↔
  pause/stop/ended spans (single spans clamp at 2h against suspend
  inflation) and piggybacks them as `seconds` on the POSTs it already
  sends; failed POSTs restore the accumulator; a session reset flushes
  first so time can't re-attribute to the next song/arrangement.
- POST /api/stats accepts optional `seconds` (finite, 0 < s ≤ 6h) on the
  scored and position branches, plus a new seconds-only branch for
  unscored plays that ran to the natural end — banks time WITHOUT
  touching the resume position (song:ended must not overwrite Continue)
  and still counts as playing today for the streak.
- song_stats gains additive idempotent `seconds_total`; record_session/
  touch_position accrue, new add_play_seconds() for the seconds-only
  path; the legacy-encoding stats merge sums seconds across duplicates.
- Passports surface it: "14.2 h in Blues" under the badge stamp and on
  the shelf cover sub-line — a true fact that only grows, never a
  target or a meter (Stage 5 post-cap, per the career design).

Tests: seconds accrual/validation/seconds-only branch (stats API),
per-instrument-and-genre summing (career), fmtHours formatting (vm).
Full suites: pytest 2480, JS 1165.

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

plugins/career/assets/career.css

@@ -466,3 +466,12 @@
     text-shadow: 0 2px 8px rgba(0, 0, 0, 0.8);
 }
 .pp-ceremony-sub { font-size: 0.8rem; color: #d1d5db; text-shadow: 0 1px 4px rgba(0, 0, 0, 0.8); }
+
+/* Hours odometer (Stage 5 post-cap — a true fact, never a meter) */
+.pp-hours {
+    font-size: 0.72rem;
+    letter-spacing: 0.08em;
+    color: #8a7a5e;
+    margin-top: 0.75rem;
+    font-variant-numeric: tabular-nums;
+}

plugins/career/routes.py

@@ -203,21 +203,24 @@ def _instrument_of(arrangements, arrangement):
 
 
 def _played_by_instrument_genre():
-    """(instrument, genre_key) → {filename: stub dict}. Best accuracy per
-    (instrument, song); the JOIN keeps the same dead-song filter as _stars()."""
+    """((instrument, genre_key) → {filename: stub dict},
+        (instrument, genre_key) → total played seconds).
+    Best accuracy per (instrument, song); seconds sum across every
+    arrangement row; the JOIN keeps the same dead-song filter as _stars()."""
     db = _state["meta_db"]
     if db is None:
-        return {}
+        return {}, {}
     thresholds = _state["content"]["star_accuracy_thresholds"]
     rows = db.conn.execute(
         "SELECT s.filename, s.arrangement, s.best_accuracy, s.last_played_at, "
-        "       songs.title, songs.artist, songs.arrangements, "
+        "       s.seconds_total, songs.title, songs.artist, songs.arrangements, "
         f"      {_genre_expr(db)} "
         "FROM song_stats s JOIN songs ON songs.filename = s.filename"
     ).fetchall()
     arrs_cache = {}
     out = {}
-    for filename, arrangement, acc, played_at, title, artist, arrs_json, genre in rows:
+    seconds = {}
+    for filename, arrangement, acc, played_at, secs, title, artist, arrs_json, genre in rows:
         gkey = _genre_key(genre)
         if not gkey:
             continue
@@ -227,10 +230,12 @@ def _played_by_instrument_genre():
             except (TypeError, ValueError):
                 arrs_cache[filename] = None
         instrument = _instrument_of(arrs_cache[filename], arrangement)
+        key = (instrument, gkey)
+        seconds[key] = seconds.get(key, 0.0) + (secs or 0.0)
         acc = acc or 0.0
-        stub = out.setdefault((instrument, gkey), {}).get(filename)
+        stub = out.setdefault(key, {}).get(filename)
         if stub is None:
-            out[(instrument, gkey)][filename] = {
+            out[key][filename] = {
                 "filename": filename,
                 "title": title or filename,
                 "artist": artist or "",
@@ -245,7 +250,7 @@ def _played_by_instrument_genre():
             acc = stub["best_accuracy"]
             stub["best_accuracy"] = round(acc, 4)
             stub["stars"] = sum(1 for t in thresholds if acc >= t)
-    return out
+    return out, seconds
 
 
 def _library_genres():
@@ -307,7 +312,7 @@ def _passports_view():
     cfg = _state["passports_content"]
     graded = set(cfg.get("graded_instruments") or [])
     st = _career_state()
-    played = _played_by_instrument_genre()
+    played, played_seconds = _played_by_instrument_genre()
     received_at, by_node = _drill_by_node()
     instruments = {}
     for inst in cfg.get("instruments") or []:
@@ -345,6 +350,9 @@ def _passports_view():
                 "graded": is_graded,
                 "songs": songs,
                 "qualifying_count": qualifying,
+                # Honest hours odometer (Stage 5 post-cap): a true fact that
+                # only grows — never a target, never a meter.
+                "seconds_total": round(played_seconds.get((inst, gkey), 0.0), 1),
                 "drills": {"required": required, "cleared": cleared},
                 "badge": badge,
             })

plugins/career/screen.js

@@ -466,17 +466,27 @@
         }
     }
 
+    // Honest hours odometer (Stage 5 post-cap). Below a minute of history
+    // there is nothing meaningful to show.
+    function fmtHours(seconds) {
+        const s = Number(seconds) || 0;
+        if (s < 60) return '';
+        if (s < 3600) return `${Math.round(s / 60)} min`;
+        return `${(s / 3600).toFixed(1).replace(/\.0$/, '')} h`;
+    }
+
     function ppCoverHTML(inst, p) {
         const rot = ppJitter(inst + p.genre_key, 1.6).toFixed(2);
         const stamp = p.badge === 'earned'
             ? `<span class="pp-stamp pp-stamp-mini" style="--pp-rot:${ppJitter(p.genre_key, 8).toFixed(1)}deg">BRONZE</span>`
             : '';
         const stubs = p.qualifying_count === 1 ? '1 stub' : `${p.qualifying_count} stubs`;
+        const hours = fmtHours(p.seconds_total);
         return `<button class="pp-cover pp-leather-${esc(inst)}" data-pp-open="${esc(p.genre_key)}" style="transform:rotate(${rot}deg)">
             <span class="pp-cover-title">${esc(p.genre.toUpperCase())}</span>
             <span class="pp-cover-inst">${esc(ppLabel(inst))} passport</span>
             ${stamp}
-            <span class="pp-cover-sub">${stubs}</span>
+            <span class="pp-cover-sub">${stubs}${hours ? ` · ${hours}` : ''}</span>
         </button>`;
     }
 
@@ -568,6 +578,9 @@
             </div>
             <div class="pp-invite">${need === 1 ? `One more ${starGl} song mints this stamp.` : `${need} more ${starGl} songs mint this stamp.`}</div>`;
         }
+        const hours = fmtHours(p.seconds_total);
+        const odometer = hours
+            ? `<div class="pp-hours">${hours} in ${esc(p.genre)}</div>` : '';
         let drills = '';
         const reqNodes = (p.drills || {}).required || [];
         if (reqNodes.length) {
@@ -589,7 +602,7 @@
             <div class="pp-book">
                 <div class="pp-page pp-page-left">
                     <div class="pp-page-head">${esc(p.genre)} — ${esc(ppLabel(inst))}</div>
-                    ${badgeArea}${drills}
+                    ${badgeArea}${odometer}${drills}
                 </div>
                 <div class="pp-page pp-page-right">
                     <div class="pp-page-head">Ticket stubs</div>
@@ -792,6 +805,7 @@
     // the badge-diff logic; nothing here touches the DOM.
     window.__careerPassportTest = {
         ppKey, ppJitter, ppLabel, detectNewBadges, seenBadges, markBadgeSeen,
+        fmtHours,
     };
 
     if (document.readyState === 'loading') {

plugins/career/tests/passports.test.js

@@ -126,3 +126,15 @@ test('seenBadges tolerates corrupt stored values', () => {
         assert.equal(w.notifications.length, 1, `stored ${bad}`);
     }
 });
+
+test('fmtHours: silent under a minute, minutes under an hour, tenths after', () => {
+    const { fmtHours } = load().__careerPassportTest;
+    assert.equal(fmtHours(0), '');
+    assert.equal(fmtHours(59), '');
+    assert.equal(fmtHours(60), '1 min');
+    assert.equal(fmtHours(1800), '30 min');
+    assert.equal(fmtHours(3600), '1 h');
+    assert.equal(fmtHours(51120), '14.2 h');
+    assert.equal(fmtHours(null), '');
+    assert.equal(fmtHours('junk'), '');
+});