fix(scripts): refuse to start dev-headless on a port somebody else holds

dev-headless.sh checked the PID in *this* worktree's .dev/app.pid and
nothing else, so an app orphaned by a deleted worktree went on listening
with nothing left to stop it — `make dev-stop` only kills the pid it
wrote. The new app then started, failed to bind, exited, and every
subsequent curl and playwright-cli call went to the other process: the
harness reported facts about an app nobody asked for.

That fails a long way from its cause. It presented as "no such table:
libraries" against a *freshly created* YJ_HOME, which reads exactly like
applySchema or staleshape.go having gone wrong, with a zero-byte app.log
beside it saying nothing.

The startup wait cannot catch this, because its health check is satisfied
by any app on the port — which is precisely the failure — so the check is
before the launch and refuses rather than warns. It names the holder's
pid, cmdline and /proc/<pid>/cwd, which is what identifies the checkout
and says "(deleted)" for the case this exists for. It does not suggest
`make dev-stop`: the PID-file check has already passed, so by
construction dev-stop does not know about this process and would report
success while changing nothing. --port already covers the legitimate
second-app case.

The second, cheaper guard the report asks for goes in after the wait:
"the port answered" is not "the app we started answered", so a dead
APP_PID at that point is now an error with the log tail rather than a
success message about somebody else's process.

Closes #119

frontend/src/components/now-playing/now-playing.ts

@@ -13,7 +13,6 @@ import {
     isQueueSourceNavigable,
     navigateToQueueSource,
 } from '@utils/queue-source-link';
-import { PHONE_QUERY } from '@utils/breakpoints';
 import { PlayerController } from '@store/controllers/player-controller';
 import { creditStore } from '@store/credit-store';
 import { QueueController } from '@store/controllers/queue-controller';
@@ -81,19 +80,6 @@ export class NowPlaying extends LitElement {
 
     private reduceMotionQuery?: MediaQueryList;
 
-    /**
-     * Phone width, from the shell's own breakpoint.
-     *
-     * This is in JS rather than in the stylesheet because what changes
-     * is the *content*, not its appearance: the title, artist and
-     * source render as plain text instead of as links, and no CSS rule
-     * can take a click handler off an element.
-     */
-    @state()
-    private phone = false;
-
-    private phoneQuery?: MediaQueryList;
-
     /** Whether each field is actively mid-scroll (class toggle). */
     @state()
     private titleScrolling = false;
@@ -355,12 +341,6 @@ export class NowPlaying extends LitElement {
         this.reduceMotion = this.reduceMotionQuery?.matches ?? false;
         this.reduceMotionQuery?.addEventListener('change', this.handleReduceMotionChange);
 
-        // Same reasoning as above: looked up here, not at module load,
-        // so a test can install its own matchMedia first.
-        this.phoneQuery = window.matchMedia?.(PHONE_QUERY);
-        this.phone = this.phoneQuery?.matches ?? false;
-        this.phoneQuery?.addEventListener('change', this.handlePhoneChange);
-
         this.resizeObserver = new ResizeObserver(() => {
             this.geometryDirty = true;
             this.requestUpdate();
@@ -384,7 +364,6 @@ export class NowPlaying extends LitElement {
         this.attachDragListeners(false);
         window.removeEventListener(SCROLL_CHANGE_EVENT, this.handleScrollModeEvent);
         this.reduceMotionQuery?.removeEventListener('change', this.handleReduceMotionChange);
-        this.phoneQuery?.removeEventListener('change', this.handlePhoneChange);
         this.resizeObserver?.disconnect();
         this.stopScrollCycle('title');
         this.stopScrollCycle('artist');
@@ -509,7 +488,7 @@ export class NowPlaying extends LitElement {
               @mouseleave=${this.handleTitleMouseLeave}
               @transitionend=${() => this.onScrollCycleEnd('title')}
             >
-              <span class="scroll-content">${this.phone ? track.title : trackLink(track.title, track.album, track.releaseGroupMbid, track.recordingMbid) || track.title}</span>
+              <span class="scroll-content">${trackLink(track.title, track.album, track.releaseGroupMbid, track.recordingMbid) || track.title}</span>
             </span>
             <span
               class="track-artist ${artistScrolling ? 'will-scroll' : ''} ${this.artistScrolling ? 'scrolling' : ''}"
@@ -519,15 +498,14 @@ export class NowPlaying extends LitElement {
               @mouseleave=${this.handleArtistMouseLeave}
               @transitionend=${() => this.onScrollCycleEnd('artist')}
             >
-              <span class="scroll-content">${this.phone ? track.artist || 'Unknown Artist' : creditLink(creditStore.credits(track.recordingMbid), track.artist, track.artistMbid) || 'Unknown Artist'}</span>
+              <span class="scroll-content">${creditLink(creditStore.credits(track.recordingMbid), track.artist, track.artistMbid) || 'Unknown Artist'}</span>
             </span>
             ${describeQueueSource(this.queue.source)
                 ? html`
                   <span
-                    class="track-source ${!this.phone && isQueueSourceNavigable(this.queue.source) ? 'navigable' : ''}"
+                    class="track-source ${isQueueSourceNavigable(this.queue.source) ? 'navigable' : ''}"
                     data-testid="now-playing-source"
                     @click=${(e: MouseEvent) => {
-                        if (this.phone) return;
                         if (!isQueueSourceNavigable(this.queue.source)) return;
                         navigateToQueueSource(
                             e.currentTarget as EventTarget,
@@ -593,10 +571,6 @@ export class NowPlaying extends LitElement {
         this.reduceMotion = e.matches;
     };
 
-    private handlePhoneChange = (e: MediaQueryListEvent): void => {
-        this.phone = e.matches;
-    };
-
     private shouldScroll(field: 'title' | 'artist'): boolean {
         const overflows = field === 'title' ? this.titleOverflows : this.artistOverflows;
 
@@ -632,12 +606,6 @@ export class NowPlaying extends LitElement {
             track?.artist ?? '',
             this.shouldScroll('title') ? '1' : '0',
             this.shouldScroll('artist') ? '1' : '0',
-            // Crossing the breakpoint swaps a link for a bare string,
-            // and a link is not guaranteed to measure the same as the
-            // text inside it. The marquee travels a distance read from
-            // that measurement, so this belongs in the key even though
-            // the words are identical either side.
-            this.phone ? '1' : '0',
         ].join('\u0000');
     }
 

frontend/src/components/track-list/track-list.ts

@@ -11,7 +11,6 @@ import {
 import { SelectionController } from '@utils/selection-controller';
 import type { SelectionHost } from '@utils/selection-controller';
 import { ViewLifecycleMixin } from '@utils/view-lifecycle';
-import { PHONE_QUERY } from '@utils/breakpoints';
 import {
     ContextMenuController,
     contextMenuStyles,
@@ -106,6 +105,9 @@ const ROW_CHROME_WIDTH =
 const ROW_HEIGHT = 33;
 const PHONE_ROW_HEIGHT = 52;
 
+/** The shell's phone breakpoint, as `index.css` and every component
+ *  stylesheet spells it. */
+const PHONE_QUERY = '(max-width: 599px)';
 
 // Inline SVG paths for favorite icons — eliminates wa-icon shadow DOM
 // overhead (30-50 shadow roots during scroll).  Font Awesome 6 paths.

frontend/src/utils/breakpoints.ts

@@ -1,23 +0,0 @@
-/**
- * The shell's breakpoints, where JavaScript has to agree with CSS.
- *
- * A media query inside a shadow root is answered by the viewport, so a
- * component normally states what it drops at phone width in its own
- * stylesheet and needs nothing from here. This exists for the cases
- * where the decision is not a style: `track-list` computes its grid in
- * JS from the host width, and `now-playing` renders *different content*
- * on a phone — a plain string instead of a link — which no stylesheet
- * can express.
- *
- * One breakpoint, several expressions of it. It was a private const in
- * track-list.ts when there was one; a second reader is where a copy
- * would start drifting from index.css.
- */
-
-/**
- * Phone width. 600px rather than the sidebar's 900px because 900 is a
- * laptop: the answer there is a narrower sidebar, which is still a
- * sidebar. Below this the shell drops the sidebar column entirely and
- * bottom-nav takes over.
- */
-export const PHONE_QUERY = '(max-width: 599px)';

frontend/test/components/now-playing-phone.test.ts

@@ -1,166 +0,0 @@
-/**
- * The mini player's links are a desktop affordance.
- *
- * `utils/explore-link.ts` makes every track and artist name navigate,
- * and `utils/queue-source-link.ts` makes "Playing from X" navigate — in
- * the bottom bar those are a few characters of text at a font size
- * chosen for a bar, which is not a touch target. Worse, explore-link
- * holds the navigation for one double-click interval and drops it if a
- * second click arrives: a gesture that exists so double-clicking a row
- * can play it, and which means nothing at all on touch.
- *
- * So below the shell's phone breakpoint the three render as plain text
- * and the whole bar's cover art opens the full-screen Now Playing view,
- * which is where the links live.
- *
- * The breakpoint is stubbed rather than emulated for the reason
- * track-list-phone.test.ts states: this tier's viewport is fixed at
- * 1280x800 by the runner, and the component reads matchMedia in
- * connectedCallback precisely so a test can answer it first.
- */
-import { describe, expect, it, beforeEach } from 'vitest';
-
-import '@components/now-playing/now-playing';
-import { Events } from '../../src/events';
-import { emit, flush } from '@test/support/harness';
-import { fixture, shadow, shadowAll, text } from '@test/support/render';
-import type { TrackInfo } from '@store/player-store';
-import type { QueueTrack } from '@store/queue-store';
-
-const TRACK: TrackInfo = {
-  fileName: 'ashes.mp3',
-  filePath: '/music/ashes.mp3',
-  trackLength: 215,
-  seekPosition: 0,
-  state: 'playing',
-  title: 'Ashes to Ashes',
-  artist: 'David Bowie',
-  album: 'Scary Monsters',
-  coverArt: '',
-  coverArtSmall: '',
-  coverArtMedium: '',
-  coverArtLarge: '',
-  trackChangeId: 1,
-  artistMbid: '',
-  releaseGroupMbid: '',
-  recordingMbid: '',
-};
-
-function queueTrack(n: number, title: string): QueueTrack {
-  return {
-    id: n,
-    audioFileId: n,
-    filePath: `/music/${n}.mp3`,
-    position: n,
-    title,
-    artist: 'David Bowie',
-    album: 'Scary Monsters',
-    coverArtPath: '',
-    artistMbid: '',
-    releaseGroupMbid: '',
-    recordingMbid: '',
-  };
-}
-
-/** Mount the bar with the phone breakpoint answering `matches`. */
-async function mountAt(phone: boolean) {
-  const real = window.matchMedia.bind(window);
-
-  window.matchMedia = ((q: string) =>
-    q.includes('max-width: 599px')
-      ? {
-          matches: phone,
-          media: q,
-          addEventListener() {},
-          removeEventListener() {},
-        }
-      : real(q)) as typeof window.matchMedia;
-
-  try {
-    const el = await fixture('now-playing');
-
-    emit(Events.TrackChanged, { ...TRACK, trackChangeId: 20 });
-    emit(Events.QueueChanged, {
-      tracks: [queueTrack(1, 'Ashes to Ashes')],
-      currentIndex: 0,
-      source: { type: 'album', id: 7, label: 'Scary Monsters' },
-    });
-    await flush();
-    await el.updateComplete;
-
-    return el;
-  } finally {
-    window.matchMedia = real;
-  }
-}
-
-describe('the mini player on a phone', () => {
-  beforeEach(() => {
-    emit(Events.TrackChanged, { ...TRACK, trackChangeId: 1 });
-  });
-
-  it('renders the title and artist as plain text', async () => {
-    const el = await mountAt(true);
-
-    expect(shadowAll(el, '.explore-link').length).toBe(0);
-
-    // The words are unchanged — this is about what they are, not about
-    // hiding them. A fix that dropped the text would pass an assertion
-    // about links alone.
-    expect(text(el, '[data-testid="now-playing-title"]')).toContain(
-      'Ashes to Ashes',
-    );
-    expect(text(el, '[data-testid="now-playing-artist"]')).toContain(
-      'David Bowie',
-    );
-  });
-
-  it('does not navigate from the source line', async () => {
-    const el = await mountAt(true);
-    const source = shadow<HTMLElement>(el, '[data-testid="now-playing-source"]');
-
-    expect(source?.classList.contains('navigable')).toBe(false);
-
-    let navigated = false;
-    el.addEventListener('navigate', () => {
-      navigated = true;
-    });
-
-    source?.click();
-
-    expect(navigated).toBe(false);
-  });
-
-  it('still says where the queue came from', async () => {
-    const el = await mountAt(true);
-
-    // Dropping the *link* is the change; dropping the information would
-    // be a different and worse one.
-    expect(text(el, '[data-testid="now-playing-source"]')).toBe(
-      'Playing from Scary Monsters',
-    );
-  });
-
-  it('leaves the desktop bar exactly as it was', async () => {
-    const el = await mountAt(false);
-
-    expect(shadowAll(el, '.explore-link').length).toBeGreaterThan(0);
-
-    const source = shadow<HTMLElement>(el, '[data-testid="now-playing-source"]');
-
-    expect(source?.classList.contains('navigable')).toBe(true);
-
-    let detail: unknown;
-    el.addEventListener('navigate', (e) => {
-      detail = (e as CustomEvent).detail;
-    });
-
-    source?.click();
-
-    expect(detail).toEqual({
-      view: 'explore-album-details',
-      localAlbumId: 7,
-      albumName: 'Scary Monsters',
-    });
-  });
-});

scripts/dev-headless.sh

@@ -97,6 +97,55 @@ if [ -f "$PID_FILE" ] && kill -0 "$(cat "$PID_FILE")" 2>/dev/null; then
 fi
 rm -f "$PID_FILE"
 
+# ── Refuse to inherit somebody else's port ───────────────────────────
+# The PID check above only knows about *this* worktree: `make dev-stop`
+# kills the pid in this .dev/app.pid and nothing else.  Several worktrees
+# of this repo share the default port, so an app orphaned by a deleted
+# worktree goes on listening with nothing left to stop it.
+#
+# Without this check the new app starts, fails to bind, exits — and every
+# curl and playwright-cli call afterwards goes to the *other* process, so
+# the harness reports facts about an app nobody asked for.  That is not a
+# quiet wrongness either: it presented as
+# "no such table: libraries" against a freshly created YJ_HOME, which
+# reads exactly like applySchema or staleshape.go having gone wrong and
+# is a frightening place to start looking.
+#
+# The startup wait below cannot catch it, because the health check is
+# satisfied by *any* app on the port — which is precisely the failure.
+# So it is refused here, before anything is launched, rather than warned
+# about.  --port already exists for the legitimate second-app case.
+port_holder() {
+	command -v ss >/dev/null || return 0
+	ss -lptn "sport = :$PORT" 2>/dev/null | grep -oP 'pid=\K[0-9]+' | head -n 1
+}
+
+if curl -sf -o /dev/null --max-time 2 "http://localhost:$PORT/" ||
+	[ -n "$(port_holder)" ]; then
+	holder="$(port_holder)"
+	echo "dev-headless: :$PORT is already in use; refusing to start" >&2
+	if [ -n "$holder" ]; then
+		# /proc/<pid>/cwd names the checkout it belongs to, and says
+		# "(deleted)" for the orphaned-worktree case that is the whole
+		# reason this is worth a check.
+		cwd="$(readlink "/proc/$holder/cwd" 2>/dev/null || echo unknown)"
+		cmd="$(tr '\0' ' ' <"/proc/$holder/cmdline" 2>/dev/null || echo unknown)"
+		echo "  pid  $holder  ($cmd)" >&2
+		echo "  cwd  $cwd" >&2
+		# The PID-file check above has already passed, so whatever this
+		# is, `make dev-stop` does not know about it — saying otherwise
+		# sends you to a command that will report success and change
+		# nothing.  Never `pkill -f` here either: the pattern would
+		# match this script's own command line.
+		echo "  'make dev-stop' will not touch it (it is not in" >&2
+		echo "  ${PID_FILE#"$REPO_ROOT"/}): kill $holder, or pass --port." >&2
+	else
+		echo "  The holder could not be identified (no ss, or it belongs" >&2
+		echo "  to another user). Try: ss -lptn 'sport = :$PORT'" >&2
+	fi
+	exit 1
+fi
+
 # ── Choose the YJ_HOME ───────────────────────────────────────────────
 # A seed is a YJ_HOME that a previous run of the app produced, tarred
 # up (see scripts/seed-sandbox.sh).  Restoring it means starting *in*
@@ -200,6 +249,20 @@ until curl -sf -o /dev/null "http://localhost:$PORT/"; do
 	sleep 0.25
 done
 
+# The loop above exits on the first answer from the port, and "something
+# answered" is not "the app we started answered".  The pre-launch guard
+# makes that unlikely rather than impossible — a race, or a listener
+# started in between — and the check is one signal, so it is worth making
+# here too.  An empty log beside a dead pid is the "it exited immediately
+# and nothing said so" case that the original report spent its time on.
+if ! kill -0 "$APP_PID" 2>/dev/null; then
+	echo "dev-headless: :$PORT answered, but the app we started (pid" >&2
+	echo "  $APP_PID) is gone — something else holds the port." >&2
+	tail -n 30 "$LOG_FILE" >&2
+	rm -f "$PID_FILE"
+	exit 1
+fi
+
 cat <<EOF
 dev-headless: up
   url      http://localhost:$PORT