@williamzujkowski/live-coding-music-mcp 4.0.0 → 4.1.0

package/dist/StrudelController.js

@@ -3,8 +3,25 @@ import * as path from 'path';
 import { promises as fs } from 'fs';
 import { AudioAnalyzer } from './AudioAnalyzer.js';
 import { PatternValidator } from './utils/PatternValidator.js';
+import { DEFAULT_BLOCK_RESOURCES, DEFAULT_STRUDEL_URL, DEFAULT_VIEWPORT, } from './utils/ServerConfig.js';
+import { resolveSafeOutputPath } from './utils/SafePath.js';
 import { ErrorRecovery } from './utils/ErrorRecovery.js';
 import { Logger } from './utils/Logger.js';
+export async function waitForStrudelReady(page, timeoutMs = 5000) {
+    await page.waitForSelector('.cm-content', { timeout: 8000 });
+    try {
+        await page.waitForFunction(
+        /* istanbul ignore next */ () => Boolean(window.strudelMirror?.editor?.dispatch), { timeout: timeoutMs });
+    }
+    catch {
+        throw new Error(`Strudel editor did not become ready within ${timeoutMs}ms. ` +
+            'The page may have failed to load or strudel.cc may have changed its API.');
+    }
+}
+export const DEFAULT_PLAYBACK_BUDGET = {
+    firstPlayMs: 15_000,
+    subsequentPlayMs: 3_000,
+};
 export class StrudelController {
     browser = null;
     _page = null;
@@ -13,6 +30,12 @@ export class StrudelController {
     errorRecovery;
     logger;
     isHeadless;
+    /** Strudel REPL URL; `strudel_url` in config.json (#227). */
+    strudelUrl;
+    /** Playwright viewport; null lets the page track the OS window (#514). */
+    viewport;
+    /** Resource types the init route aborts (#514). */
+    blockResources;
     editorCache = '';
     cacheTimestamp = 0;
     CACHE_TTL = 100; // milliseconds
@@ -22,24 +45,65 @@ export class StrudelController {
     // (first play-button click per session). Subsequent plays can use the
     // keyboard shortcut cleanly because AudioContext is already resumed.
     hasEstablishedGesture = false;
+    playbackBudget;
     consoleErrors = [];
     consoleWarnings = [];
-    constructor(headless = false) {
+    constructor(headless = false, audioAnalysisConfig, strudelUrl = DEFAULT_STRUDEL_URL, 
+    // Injectable so a test asserting a start FAILURE does not have to
+    // wait out a budget sized for a real cold start.
+    playbackBudget = DEFAULT_PLAYBACK_BUDGET, 
+    // Page-setup overrides from config.json `viewport` / `block_resources` (#514).
+    fidelity = {}) {
+        this.playbackBudget = playbackBudget;
         this.isHeadless = headless;
-        this.analyzer = new AudioAnalyzer();
+        this.strudelUrl = strudelUrl;
+        this.viewport = fidelity.viewport !== undefined ? fidelity.viewport : DEFAULT_VIEWPORT;
+        this.blockResources = fidelity.blockResources ?? DEFAULT_BLOCK_RESOURCES;
+        this.analyzer = new AudioAnalyzer(audioAnalysisConfig);
         this.validator = new PatternValidator();
         this.errorRecovery = new ErrorRecovery();
         this.logger = new Logger();
     }
     /**
-     * Initializes the browser and navigates to Strudel.cc
+     * Returns true iff both the browser and its page are still alive.
+     * Used by `initialize()` to detect a stale session where the user
+     * (or a crash) closed the page out from under us, and by callers
+     * that want to verify before issuing a tool call (#202).
+     */
+    /** The page whose console this controller is already listening to. */
+    consoleMonitoredPage = null;
+    isAlive() {
+        return this.browser !== null && this._page !== null && !this._page.isClosed();
+    }
+    /**
+     * Initializes the browser and navigates to Strudel.cc.
+     *
+     * Idempotent and self-healing (#202): if a previous init succeeded but
+     * the page has since been closed (manual user close, crash, navigation
+     * error), the next call tears down the dead browser and re-initializes
+     * rather than returning "Already initialized" and leaving callers to
+     * fail with `Target page, context or browser has been closed`.
+     *
      * @returns Success message when initialization is complete
      * @throws {Error} When browser launch or page navigation fails
      */
     async initialize() {
-        if (this.browser) {
+        if (this.isAlive()) {
             return 'Already initialized';
         }
+        // Browser handle exists but page is dead — clean up before re-init so
+        // we don't leak a dangling Chromium process.
+        if (this.browser !== null) {
+            this.logger.warn('Stale browser detected (page closed); recreating');
+            try {
+                await this.cleanup();
+            }
+            catch (e) {
+                // cleanup failures shouldn't block re-init; the next launch is
+                // what matters. The stale process becomes the OS's problem.
+                this.logger.warn(`Cleanup during recovery failed: ${e?.message ?? e}`);
+            }
+        }
         this.browser = await chromium.launch({
             headless: this.isHeadless,
             args: [
@@ -54,33 +118,69 @@ export class StrudelController {
         });
         const context = await this.browser.newContext({
             permissions: ['microphone'],
-            viewport: { width: 1280, height: 720 },
+            // null is meaningful: Playwright tracks the real window size, so
+            // resizes reach the page and canvases re-measure (#514).
+            viewport: this.viewport,
             reducedMotion: 'reduce',
         });
         this._page = await context.newPage();
         // Optimize page loading
         await this._page.route('**/*', (route) => {
             const resourceType = route.request().resourceType();
-            // Block unnecessary resources
-            if (['image', 'font', 'media'].includes(resourceType)) {
+            // Abort the configured resource classes; an empty
+            // block_resources blocks nothing (#514).
+            if (this.blockResources.includes(resourceType)) {
                 route.abort();
             }
             else {
                 route.continue();
             }
         });
-        await this._page.goto('https://strudel.cc/', {
-            waitUntil: 'domcontentloaded', // Changed from networkidle for faster load
-            timeout: 15000,
-        });
-        // Wait for editor element to appear
-        await this._page.waitForSelector('.cm-content', { timeout: 8000 });
-        // Wait for strudelMirror API to be available
-        // This is the correct API exposed by strudel.cc (not __view on DOM elements)
-        await this._page.waitForFunction(() => window.strudelMirror?.editor?.dispatch, { timeout: 5000 });
-        // Set up console monitoring for runtime errors
-        this.setupConsoleMonitoring();
-        await this.analyzer.inject(this._page);
+        // Navigation and readiness are the only parts of init that depend on
+        // a live third-party site, and they had no retry at all: one hiccup
+        // from strudel.cc surfaced to the calling agent as a hard error
+        // (#315). chromium.launch is deliberately outside the retry — a
+        // local process launch does not fail transiently, and relaunching it
+        // would cost seconds per attempt.
+        const page = this._page;
+        // Everything past `newPage()` is rolled back if it fails.
+        //
+        // Without this, a failed navigation left `browser` and `_page`
+        // assigned with the page sitting on about:blank. `isAlive()` only
+        // asks whether the page is CLOSED, so it said yes; the server clears
+        // `isInitialized` only when `isAlive()` is false, so the next call
+        // re-entered `initialize()`, hit the `'Already initialized'`
+        // shortcut, and every tool after that failed on a blank page with
+        // "editor not found after 3 attempts" — permanently, with no path
+        // back short of a restart.
+        //
+        // #202 and #206 cover a page that DIED. This is a page that was
+        // never born, which their `isAlive()` check cannot distinguish from
+        // a healthy one (#456).
+        try {
+            await this.errorRecovery.executeWithRetry(async () => {
+                await page.goto(this.strudelUrl, {
+                    waitUntil: 'domcontentloaded', // Changed from networkidle for faster load
+                    timeout: 15000,
+                });
+                await waitForStrudelReady(page);
+            }, 'Browser Init', {
+                maxRetries: 2,
+                retryDelay: 750,
+                exponentialBackoff: true,
+                // Sessions that hit the same upstream hiccup must not retry in
+                // lockstep and concentrate load on a struggling service.
+                jitter: true,
+            });
+            // Set up console monitoring for runtime errors
+            this.setupConsoleMonitoring();
+            await this.analyzer.inject(this._page);
+        }
+        catch (error) {
+            // Leave nothing half-built behind, so the next init starts clean.
+            await this.cleanup().catch(() => undefined);
+            throw error;
+        }
         return 'Strudel initialized successfully';
     }
     /**
@@ -99,6 +199,16 @@ export class StrudelController {
     setupConsoleMonitoring() {
         if (!this._page)
             return;
+        // One listener per page.
+        //
+        // `page.on` appends, and nothing removed the previous listener, so
+        // a second call recorded every console message twice and doubled
+        // the error count `diagnostics` reports. `initialize()` calls this,
+        // and so does SessionManager on its own path; they do not currently
+        // overlap, but nothing stopped them (#488).
+        if (this.consoleMonitoredPage === this._page)
+            return;
+        this.consoleMonitoredPage = this._page;
         this._page.on('console', (msg) => {
             const type = msg.type();
             const text = msg.text();
@@ -127,13 +237,18 @@ export class StrudelController {
             throw new Error('Browser not initialized. Run init tool first.');
         // Invalidate cache before write to prevent stale reads
         this.invalidateCache();
+        // And forget the onsets collected from the PREVIOUS pattern. Without
+        // this the first tempo reading after a change describes the pattern
+        // before it: playing dnb at 174 and then house at 125, the first
+        // house reading came back 174 (#366).
+        await this.analyzer.resetTempoHistory(this._page);
         // Retry logic for timing edge cases
         const maxRetries = 3;
         const retryDelay = 100; // ms
         let success = false;
         for (let attempt = 0; attempt < maxRetries; attempt++) {
             // Use strudelMirror API (correct approach for strudel.cc)
-            success = await this._page.evaluate((newPattern) => {
+            success = await this._page.evaluate(/* istanbul ignore next */ (newPattern) => {
                 const sm = window.strudelMirror;
                 if (sm?.editor?.dispatch) {
                     const view = sm.editor;
@@ -156,7 +271,7 @@ export class StrudelController {
             throw new Error('Failed to write pattern - editor not found or view unavailable after 3 attempts');
         }
         // Verify the write by reading back from browser (fixes cache sync issues)
-        const verified = await this._page.evaluate(() => {
+        const verified = await this._page.evaluate(/* istanbul ignore next */ () => {
             const sm = window.strudelMirror;
             // Use code property or editor state
             if (sm?.code)
@@ -187,7 +302,7 @@ export class StrudelController {
         if (this.editorCache && (now - this.cacheTimestamp) < this.CACHE_TTL) {
             return this.editorCache;
         }
-        const pattern = await this._page.evaluate(() => {
+        const pattern = await this._page.evaluate(/* istanbul ignore next */ () => {
             const sm = window.strudelMirror;
             // Use code property or editor state
             if (sm?.code)
@@ -201,55 +316,236 @@ export class StrudelController {
         this.cacheTimestamp = now;
         return pattern;
     }
+    /**
+     * Reads Strudel's own scheduler state.
+     *
+     * `this.isPlaying` used to be set optimistically, which is how #218
+     * happened: stop() reported "Stopped" and diagnostics reported
+     * playing:false while audio kept running. Ask the page instead.
+     *
+     * @returns True if Strudel's REPL scheduler is started
+     */
+    async readPlaybackState() {
+        if (!this._page)
+            return 'unreadable';
+        try {
+            const started = await this._page.evaluate(/* istanbul ignore next */ () => {
+                const sm = window.strudelMirror;
+                return Boolean(sm?.repl?.state?.started ?? sm?.repl?.scheduler?.started);
+            });
+            return started ? 'playing' : 'stopped';
+        }
+        catch {
+            // Three values, not two. Returning `false` here meant "could not
+            // read" and "not playing" were the same answer — so
+            // waitForPlaybackState(false) succeeded instantly on a dead page and
+            // stop() reported "Stopped" for audio it never touched. That is the
+            // symptom #218 was filed for, reintroduced through the error path
+            // rather than through optimistic state (#278).
+            return 'unreadable';
+        }
+    }
+    /**
+     * Polls until Strudel's scheduler reaches the desired state.
+     * @param desired - State to wait for
+     * @param timeoutMs - Maximum time to wait
+     * @returns True if the state was reached before the timeout
+     */
+    async waitForPlaybackState(desired, timeoutMs) {
+        const target = desired ? 'playing' : 'stopped';
+        const deadline = Date.now() + timeoutMs;
+        for (;;) {
+            // 'unreadable' never satisfies the wait. It used to satisfy the
+            // stop case by coincidence, because it shared a value with
+            // 'stopped'.
+            if (await this.readPlaybackState() === target)
+                return true;
+            if (Date.now() >= deadline)
+                return false;
+            await this._page?.waitForTimeout(50);
+        }
+    }
     /**
      * Starts playing the current pattern
      * @returns Success message
-     * @throws {Error} When not initialized
+     * @throws {Error} When not initialized, or when playback fails to start
      */
     async play() {
         if (!this._page)
             throw new Error('Browser not initialized. Run init tool first.');
         // First play per session: click the play button to establish the user
         // gesture the AudioContext needs. Slow (~3s in headless) but only once.
-        // Subsequent plays: use Ctrl+Enter — AudioContext is already resumed,
-        // so the keyboard shortcut resumes playback cleanly and fast.
-        if (!this.hasEstablishedGesture) {
+        const firstPlay = !this.hasEstablishedGesture;
+        let usedKeyboardFallback = false;
+        if (firstPlay) {
             try {
                 const playButton = this._page.locator('button[title="play"]').first();
                 await playButton.click({ timeout: 3000 });
                 this.hasEstablishedGesture = true;
             }
             catch {
+                usedKeyboardFallback = true;
                 await this._page.keyboard.press('ControlOrMeta+Enter');
             }
         }
         else {
-            await this._page.keyboard.press('ControlOrMeta+Enter');
+            // AudioContext is already resumed, so drive strudelMirror directly.
+            // Ctrl+Enter is a CodeMirror keymap binding and only fires when the
+            // editor holds focus — see the comment on stop() (#218).
+            await this._page.evaluate(/* istanbul ignore next */ () => {
+                window.strudelMirror?.evaluate?.();
+            });
+        }
+        // The first play of a session pays for cold caches: the AudioContext
+        // resuming, and every sample the pattern names being fetched before
+        // a cycle can be scheduled. Measured, the first play sat right on a
+        // 3000ms budget — a corpus example failed at 3128ms while the one
+        // that followed it succeeded in 4008ms, so the margin was under a
+        // second either way and the first test to play went red about one
+        // run in five (#416). Later plays reuse everything and stay fast.
+        const startBudgetMs = firstPlay
+            ? this.playbackBudget.firstPlayMs
+            : this.playbackBudget.subsequentPlayMs;
+        if (!(await this.waitForPlaybackState(true, startBudgetMs))) {
+            const state = await this.readPlaybackState();
+            this.isPlaying = state === 'playing';
+            this.analyzer.clearCache();
+            // Name the cause we actually observed. This used to blame a syntax
+            // error for every startup failure, including a page that had gone
+            // away and an AudioContext that never resumed — confident about one
+            // cause when three were possible.
+            //
+            // The gesture-click fallback is a fourth: when the transport button
+            // could not be clicked we pressed Ctrl+Enter instead, which only
+            // reaches CodeMirror while the editor holds focus. That case used
+            // to be reported as a possible syntax error, sending the reader to
+            // look for a bug that is not in their pattern.
+            throw new Error(state === 'unreadable'
+                ? 'Playback did not start: the page could not be read. It may have ' +
+                    'navigated or closed — run init to recover.'
+                : usedKeyboardFallback
+                    ? 'Playback did not start: the transport button could not be clicked, ' +
+                        'so the keyboard fallback was used and the AudioContext may never ' +
+                        'have resumed. Run init to recover; the pattern is probably fine.'
+                    : `Playback did not start within ${String(startBudgetMs)}ms. The pattern ` +
+                        'may have a syntax error, or the AudioContext may not have resumed — ' +
+                        'check diagnostics({ level: "errors" }).');
         }
-        await this._page.waitForTimeout(50);
         this.isPlaying = true;
+        // Playback state just changed, so any cached analysis describes the
+        // previous state. Without this, analyze() can report the old state for
+        // up to ANALYSIS_CACHE_TTL after play/stop (#211).
+        this.analyzer.clearCache();
         return 'Playing';
     }
+    /**
+     * Halts playback without resetting the cycle position.
+     *
+     * `playback({ action: "pause" })` claimed this for months and did not
+     * do it — `pause` fell through to `stop` (#406). Strudel's scheduler
+     * distinguishes them: `stop()` zeroes the phase counters, `pause()`
+     * only halts the clock. Measured against live strudel.cc:
+     *
+     *   playing              started:true  lastEnd:1.35 phase:5.302
+     *   paused               started:false lastEnd:1.35 phase:5.302
+     *   play() after pause   started:true  lastEnd:2.50 phase:7.602
+     *   stopped              started:false lastEnd:0    phase:0
+     *
+     * So `play()` resumes rather than restarting, and needs no change.
+     *
+     * Tempo history is deliberately NOT cleared here, unlike `stop()`. A
+     * pause is a gap in one performance, and the onsets either side of it
+     * belong to the same pattern — but the gap itself would read as a
+     * silence, so the analyzer drops history across one longer than a bar
+     * on its own (#366). Clearing on top of that would throw away a
+     * reading that is about to be valid again.
+     *
+     * @returns Success message
+     * @throws {Error} When not initialized, or when playback fails to pause
+     */
+    async pause() {
+        if (!this._page)
+            throw new Error('Browser not initialized. Run init tool first.');
+        try {
+            await this._page.evaluate(/* istanbul ignore next */ () => {
+                window.strudelMirror?.repl?.pause?.();
+            });
+        }
+        catch {
+            // Same reasoning as stop(): the state check below is what decides
+            // whether this worked, and it produces a better message (#278).
+        }
+        if (!(await this.waitForPlaybackState(false, 2000))) {
+            const state = await this.readPlaybackState();
+            this.isPlaying = state === 'playing';
+            this.analyzer.clearCache();
+            throw new Error(state === 'unreadable'
+                ? 'Failed to pause playback: the page could not be read, so whether ' +
+                    'audio is still running is unknown. Run init to recover.'
+                : 'Failed to pause playback: Strudel scheduler is still running. ' +
+                    'Use playback({ action: "stop" }) to end playback outright.');
+        }
+        this.isPlaying = false;
+        // See play(): a stale cached analysis would report audio still
+        // playing immediately after a successful pause (#211).
+        this.analyzer.clearCache();
+        return 'Paused';
+    }
     /**
      * Stops the currently playing pattern
      * @returns Success message
-     * @throws {Error} When not initialized
+     * @throws {Error} When not initialized, or when playback fails to stop
      */
     async stop() {
         if (!this._page)
             throw new Error('Browser not initialized. Run init tool first.');
-        // Ctrl+Period stops cleanly when AudioContext is running (i.e. after
-        // a successful play). No user gesture needed — we only need one to
-        // RESUME AudioContext, not to stop it. Fall back to the button click
-        // if keyboard fails (e.g. editor lost focus).
+        // Drive strudelMirror.stop() directly. Ctrl+Period is bound in the
+        // CodeMirror keymap, so page.keyboard.press only reaches it while the
+        // editor holds focus — and it RESOLVES either way, so the old catch
+        // block never fired and stop() reported success while audio kept
+        // playing (#218). Verified against live strudel.cc: after a keyboard
+        // stop without focus, repl.state.started stayed true; after
+        // strudelMirror.stop() it went false.
         try {
-            await this._page.keyboard.press('ControlOrMeta+Period');
+            await this._page.evaluate(/* istanbul ignore next */ () => {
+                window.strudelMirror?.stop?.();
+            });
         }
         catch {
-            const playButton = this._page.locator('button[title="play"]').first();
-            await playButton.click({ timeout: 2000 });
+            // Fall through rather than surfacing a raw Playwright error. The
+            // state check below establishes whether the page is readable at all
+            // and produces a message that says what to do about it (#278).
+        }
+        if (!(await this.waitForPlaybackState(false, 2000))) {
+            // Fall back to the transport button. Note the title flips to "stop"
+            // while playing, so the old `button[title="play"]` locator could not
+            // have matched here either.
+            try {
+                await this._page.locator('button[title="stop"]').first().click({ timeout: 2000 });
+            }
+            catch {
+                await this._page.keyboard.press('ControlOrMeta+Period');
+            }
+            if (!(await this.waitForPlaybackState(false, 2000))) {
+                const state = await this.readPlaybackState();
+                this.isPlaying = state === 'playing';
+                this.analyzer.clearCache();
+                // An unreadable page is not a successful stop. Saying "Stopped"
+                // here is exactly what #218 was filed for.
+                throw new Error(state === 'unreadable'
+                    ? 'Failed to stop playback: the page could not be read, so whether ' +
+                        'audio is still running is unknown. Run init to recover.'
+                    : 'Failed to stop playback: Strudel scheduler is still running.');
+            }
         }
         this.isPlaying = false;
+        // See play(): a stale cached analysis would report audio still playing
+        // immediately after a successful stop (#211).
+        this.analyzer.clearCache();
+        // Onsets from before a stop belong to a finished performance. Kept,
+        // they put a multi-second silence in the middle of the next tempo
+        // reading's intervals (#366).
+        await this.analyzer.resetTempoHistory(this._page);
         return 'Stopped';
     }
     /**
@@ -262,7 +558,7 @@ export class StrudelController {
             throw new Error('Browser not initialized. Run init tool first.');
         const startTime = Date.now();
         while (Date.now() - startTime < timeoutMs) {
-            const isConnected = await this._page.evaluate(() => {
+            const isConnected = await this._page.evaluate(/* istanbul ignore next */ () => {
                 return window.strudelAudioAnalyzer?.isConnected || false;
             });
             if (isConnected) {
@@ -333,6 +629,8 @@ export class StrudelController {
             await this.browser.close();
             this.browser = null;
             this._page = null;
+            // The next page gets its own listener (#488).
+            this.consoleMonitoredPage = null;
         }
     }
     /**
@@ -466,9 +764,21 @@ export class StrudelController {
             throw new Error('Browser not initialized. Run init tool first.');
         }
         const current = await this.getCurrentPattern();
-        // Escape regex special characters to prevent injection
+        // Both sides literal.
+        //
+        // The search was escaped and the REPLACEMENT was not, so
+        // `String.replace` interpreted its special patterns. Measured:
+        //
+        //   replaceInPattern('bd', '$&x')   -> "bdx"    wanted "$&x"
+        //   replaceInPattern('bd', 'a$`b')  -> "ab"     wanted "a$`b"
+        //   replaceInPattern('bd', 'x$$y')  -> "x$y"    wanted "x$$y"
+        //
+        // The comment above the escape said it was there "to prevent
+        // injection", which is exactly half of the job it was doing.
+        // A replacer function is passed the match and its return value is
+        // used verbatim, so nothing in `replace` is interpreted (#488).
         const escaped = this.escapeRegex(search);
-        const newPattern = current.replace(new RegExp(escaped, 'g'), replace);
+        const newPattern = current.replace(new RegExp(escaped, 'g'), () => replace);
         if (current === newPattern) {
             return `No matches found for: ${search}`;
         }
@@ -606,20 +916,20 @@ export class StrudelController {
             throw new Error('Browser not initialized. Run init tool first.');
         }
         try {
-            // Default to tmp/ directory for screenshots
+            // Confine to tmp/. The old guard was inverted — it passed any
+            // filename *containing* a separator through unsanitized, which is
+            // exactly what a traversal payload looks like (#234).
             const tmpDir = path.join(process.cwd(), 'tmp');
             await fs.mkdir(tmpDir, { recursive: true });
-            // If filename has no path component, save to tmp/
-            let screenshotPath;
-            if (filename && path.dirname(filename) !== '.') {
-                screenshotPath = filename;
-            }
-            else {
-                const name = filename || `strudel-screenshot-${Date.now()}.png`;
-                screenshotPath = path.join(tmpDir, name);
-            }
-            await this._page.screenshot({ path: screenshotPath, fullPage: false });
-            return `Screenshot saved to ${screenshotPath}`;
+            const target = resolveSafeOutputPath(filename, {
+                directory: tmpDir,
+                extension: '.png',
+                defaultName: `strudel-screenshot-${Date.now()}.png`,
+            });
+            await this._page.screenshot({ path: target.path, fullPage: false });
+            return target.wasModified
+                ? `Screenshot saved to ${target.path} (requested name '${String(target.requested)}' was not usable)`
+                : `Screenshot saved to ${target.path}`;
         }
         catch (error) {
             this.logger.error('Failed to take screenshot', error);
@@ -632,7 +942,16 @@ export class StrudelController {
      */
     getStatus() {
         return {
-            initialized: this._page !== null,
+            // `isAlive()`, not "a page object exists". A user closing the
+            // visible browser window — the documented default is headless
+            // false — left this reporting `initialized: true` for a page that
+            // was gone (#456).
+            initialized: this.isAlive(),
+            // Cached: set by play/pause/stop and NOT reconciled with the page,
+            // so it is stale if playback changed outside this controller (the
+            // user pressing stop in the window). `readPlaybackState()` asks
+            // the page; this field is a last-known value and is named as such
+            // in the returned object.
             playing: this.isPlaying,
             patternLength: this.editorCache.length,
             cacheValid: this.editorCache.length > 0 && (Date.now() - this.cacheTimestamp) < this.CACHE_TTL,
@@ -646,8 +965,21 @@ export class StrudelController {
      */
     async getDiagnostics() {
         const diagnostics = {
-            browserConnected: this.browser !== null,
-            pageLoaded: this._page !== null,
+            // Connectivity, not existence.
+            //
+            // These were `this.browser !== null` and `this._page !== null`, so
+            // closing the browser out from under the controller left
+            // diagnostics reporting a connected browser and a loaded page.
+            // `isAlive()` two hundred lines up already asks `isClosed()`; the
+            // tool whose entire job is reporting system state was the one
+            // place that did not (#488).
+            //
+            // Note `browser` is deliberately null for session-managed
+            // controllers, which do not own it — so this reads false there,
+            // as it did before. That is a separate reporting gap, filed
+            // rather than papered over here.
+            browserConnected: this.browser?.isConnected() ?? false,
+            pageLoaded: this._page !== null && !this._page.isClosed(),
             editorReady: false,
             audioConnected: false,
             cacheStatus: {
@@ -659,11 +991,11 @@ export class StrudelController {
         if (this._page) {
             try {
                 // Check that strudelMirror API is available
-                diagnostics.editorReady = await this._page.evaluate(() => {
+                diagnostics.editorReady = await this._page.evaluate(/* istanbul ignore next */ () => {
                     const sm = window.strudelMirror;
                     return sm?.editor?.dispatch !== undefined;
                 });
-                diagnostics.audioConnected = await this._page.evaluate(() => {
+                diagnostics.audioConnected = await this._page.evaluate(/* istanbul ignore next */ () => {
                     return window.strudelAudioAnalyzer?.isConnected || false;
                 });
             }