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

package/dist/server/server.js

@@ -8,11 +8,13 @@ import { PatternGenerator } from '../services/PatternGenerator.js';
 import { GeminiService } from '../services/GeminiService.js';
 import { AudioCaptureService } from '../services/AudioCaptureService.js';
 import { MIDIExportService } from '../services/MIDIExportService.js';
+import { AudioExportService } from '../services/AudioExportService.js';
+import { MIDIImportService } from '../services/MIDIImportService.js';
 import { SessionManager } from '../services/SessionManager.js';
 import { readFileSync, existsSync } from 'fs';
 import { Logger } from '../utils/Logger.js';
 import { PerformanceMonitor } from '../utils/PerformanceMonitor.js';
-import { StrudelEngine } from '../services/StrudelEngine.js';
+import { IsolatedStrudelEngine } from '../services/IsolatedStrudelEngine.js';
 import { diagnosticsModule } from './tools/diagnostics.js';
 import { playbackModule } from './tools/playback.js';
 import { storageModule } from './tools/storage.js';
@@ -25,13 +27,47 @@ import { sessionModule } from './tools/session.js';
 import { captureModule } from './tools/capture.js';
 import { aiModule } from './tools/ai.js';
 import { composeModule } from './tools/compose.js';
-import { categorizeError, err, isEnvelope, ok } from './tools/types.js';
+import { categorizeError, err, isEnvelope, ok, isFailureShaped, PATTERN_STASHED_PREFIX } from './tools/types.js';
 import { readResource, resources as mcpResources } from './resources.js';
-import { join } from 'node:path';
+import { join, resolve } from 'node:path';
+import { parseServerConfig } from '../utils/ServerConfig.js';
+import { BusinessError } from '../utils/CategorisedError.js';
 const configPath = './config.json';
-const config = existsSync(configPath)
-    ? JSON.parse(readFileSync(configPath, 'utf-8'))
-    : { headless: false };
+/**
+ * Parsed once at module load. parseServerConfig never throws — a bad
+ * value falls back to its default and records a warning — so a typo in
+ * config.json cannot stop the server starting. It also warns about keys
+ * nothing reads, which is what stops the next `strudel_url` from being
+ * silently ignored for two releases (#227).
+ */
+let configFound = false;
+function loadConfig() {
+    configFound = existsSync(configPath);
+    // No warning for an absent file — running without config.json is the
+    // normal case and warning about it every start would be crying wolf.
+    // The path checked is reported through `diagnostics` instead, so a
+    // user whose client launches the server from another cwd can SEE that
+    // their file was not the one read (#442).
+    if (!configFound)
+        return parseServerConfig(undefined);
+    try {
+        return parseServerConfig(JSON.parse(readFileSync(configPath, 'utf-8')));
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        const parsed = parseServerConfig(undefined);
+        parsed.warnings.push(`config.json could not be parsed (${message}); using defaults`);
+        return parsed;
+    }
+}
+/**
+ * How long shutdown may take before the process exits anyway. Browser
+ * cleanup talks to a wedged Chromium over CDP often enough that "wait
+ * forever" is not an option (#307).
+ */
+const SHUTDOWN_GRACE_MS = 5000;
+const config = loadConfig();
+const audioAnalysisConfig = config.audioAnalysis;
 export class StrudelMCPServer {
     server;
     controller;
@@ -46,12 +82,15 @@ export class StrudelMCPServer {
      * sessions no longer conflict.
      */
     audioCaptureServices = new Map();
+    /** In-flight recorder injections, so concurrent calls share one (#423). */
+    captureServiceBuilds = new Map();
     midiExportService;
+    audioExportService;
+    midiImportService;
     sessionManager;
     logger;
     perfMonitor;
     strudelEngine;
-    sessionHistory = [];
     /**
      * Per-session undo/redo/history bundles (#179). Keyed by session id;
      * 'default' for the legacy/single-session path. Bundles are lazily
@@ -63,27 +102,60 @@ export class StrudelMCPServer {
     /** Maximum history entries per session to prevent memory leaks */
     MAX_HISTORY = 100;
     isInitialized = false;
-    generatedPatterns = new Map();
+    /**
+     * A pattern produced before a browser existed, held for the next init.
+     *
+     * One slot, not a map. Both readers only ever took the last value, so
+     * the map's other entries were pure growth — nothing deleted from it,
+     * up to 10KB each, for the life of the process. Its keys were also
+     * `pattern_${Date.now()}`, so two stashes in the same millisecond
+     * collided and one was silently dropped (#262).
+     */
+    pendingPattern = null;
+    /** In-flight auto-init, so concurrent callers share one browser launch. */
+    initPromise = null;
     constructor() {
         this.server = new Server({
             name: 'live-coding-music-mcp',
-            version: '3.0.0',
+            version: '4.0.0',
         }, {
             capabilities: {
                 tools: {},
                 resources: {},
             },
         });
-        this.controller = new StrudelController(config.headless);
-        this.store = new PatternStore('./patterns');
+        this.controller = new StrudelController(config.headless, audioAnalysisConfig, config.strudelUrl, undefined, { viewport: config.viewport, blockResources: config.blockResources });
+        this.store = new PatternStore(config.patternsDir);
         this.theory = new MusicTheory();
         this.generator = new PatternGenerator();
         this.geminiService = new GeminiService();
-        this.midiExportService = new MIDIExportService();
-        this.sessionManager = new SessionManager(config.headless);
+        // Exports are confined to this directory (#224); `exports_dir` in
+        // config.json relocates it.
+        this.midiExportService = new MIDIExportService(config.exportsDir);
+        // Shares the export directory and sanitizer with MIDI export (#223, #224).
+        this.audioExportService = new AudioExportService(config.exportsDir);
+        this.midiImportService = new MIDIImportService();
+        this.sessionManager = new SessionManager(config.headless, audioAnalysisConfig, config.strudelUrl, { viewport: config.viewport, blockResources: config.blockResources });
+        // Covers every teardown path — the destroy tool, idle eviction, and
+        // destroyAll — rather than only the one the tool handler knew about.
+        // destroyAll fired none of these until #423; the claim above this
+        // line predated the code by some months.
+        this.sessionManager.onSessionDestroyed = (id) => {
+            this.historyBundles.delete(id);
+            this.audioCaptureServices.delete(id);
+        };
+        // The sweep cannot see a capture in progress: `audio_capture start`
+        // returns immediately and the recording runs on in the page, so the
+        // session looks idle while it is very much working (#423).
+        this.sessionManager.isSessionBusy = (id) => this.audioCaptureServices.get(id)?.isCapturing() === true;
         this.logger = new Logger();
+        // A config problem the user never sees is how #227 survived: two
+        // documented keys were read by nothing, with no warning anywhere.
+        for (const warning of config.warnings) {
+            this.logger.warn(warning);
+        }
         this.perfMonitor = new PerformanceMonitor();
-        this.strudelEngine = new StrudelEngine();
+        this.strudelEngine = new IsolatedStrudelEngine();
         this.setupHandlers();
     }
     getTools() {
@@ -128,7 +200,11 @@ export class StrudelMCPServer {
             try {
                 const content = await readResource(uri, {
                     store: this.store,
-                    examplesDir: join(process.cwd(), 'patterns', 'examples'),
+                    // Follows `patterns_dir`, like the store does. Hardcoding
+                    // `process.cwd()` meant a server launched from anywhere but
+                    // the repo root advertised `strudel://examples` and then
+                    // failed to read it (#442).
+                    examplesDir: join(config.patternsDir, 'examples'),
                 });
                 return { contents: [content] };
             }
@@ -173,6 +249,38 @@ export class StrudelMCPServer {
                 }
                 return ok(result);
             }
+            // A tool returning `{ success: false, ... }` is reporting a
+            // FAILURE. Wrapping it in ok() told MCP clients the call
+            // succeeded, with the real outcome buried one level down in a
+            // field the envelope contract does not mention — so an agent
+            // checking `envelope.ok` proceeded as though it had worked.
+            //
+            // 28 sites across the tool modules return this shape (capture,
+            // storage, ai). Rather than migrate them all at once, honour the
+            // shape here: it is unambiguous, and the alternative is a silent
+            // wrong answer.
+            if (isFailureShaped(result)) {
+                // Prefer whichever field actually carries the diagnosis, and
+                // combine them when both say something. transpile_pattern sets
+                // message:'Transpilation failed' with error:'Unexpected token
+                // (1:6)' — taking `message` alone would put the content-free half
+                // in the field an agent reads and bury the useful half in
+                // partialResult.
+                const detail = typeof result.error === 'string' && result.error.length > 0
+                    ? result.error
+                    : undefined;
+                const summary = typeof result.message === 'string' && result.message.length > 0
+                    ? result.message
+                    : undefined;
+                const message = summary !== undefined && detail !== undefined && !summary.includes(detail)
+                    ? `${summary}: ${detail}`
+                    : detail ?? summary ?? 'Tool reported failure without a message.';
+                return err(categorizeError(new Error(message)), message, {
+                    // Keep what the tool produced: some of these carry useful
+                    // context alongside the failure.
+                    partialResult: result,
+                });
+            }
             return ok(result);
         }
         catch (error) {
@@ -185,46 +293,69 @@ export class StrudelMCPServer {
     // execute() does its own session-aware init check. The hardcoded
     // tool-name lists had drifted and were silently wrong for explicit
     // session_id.
-    async getCurrentPatternSafe(sessionId) {
+    /**
+     * The session a call belongs to when it names none.
+     *
+     * Returns the default session's id when SessionManager actually holds
+     * that session, and `undefined` when it does not — which means the
+     * legacy single controller, the only thing a server that has run
+     * nothing but `init` has.
+     *
+     * There used to be two answers to this question.
+     * `getControllerForSession` resolved through
+     * `sessionManager.getDefaultSession()`, while `getCurrentPatternSafe`,
+     * `writePatternSafe` and `getAudioCaptureService` went straight to the
+     * legacy controller. So after `session({action:'switch'})`, `playback`
+     * followed the switch and `edit_pattern` did not — reproduced end to
+     * end in #421: a write with no `session_id` landed in the legacy
+     * browser while the session switched to still held strudel.cc's
+     * boilerplate.
+     *
+     * `getSession` stamps `lastActivity`, which is correct here: resolving
+     * a session is the first step of using it.
+     */
+    effectiveSessionId(sessionId) {
+        if (sessionId !== undefined)
+            return sessionId;
+        const defaultId = this.sessionManager.getDefaultSessionId();
+        return this.sessionManager.getSession(defaultId) !== undefined ? defaultId : undefined;
+    }
+    async getCurrentPatternSafe(rawSessionId) {
+        const sessionId = this.effectiveSessionId(rawSessionId);
         if (sessionId) {
             // Explicit session — strict lookup, no pre-init stash. Named sessions
-            // must be created via `create_session` before they're useful.
+            // must be created via `session({ action: "create" })` before they're useful.
             const sessionController = this.sessionManager.getSession(sessionId);
             if (!sessionController) {
-                throw new Error(`Session '${sessionId}' not found. Create it first with create_session.`);
-            }
-            try {
-                return await sessionController.getCurrentPattern();
-            }
-            catch {
-                return '';
+                throw new Error(`Session '${sessionId}' not found. Create it first with session({ action: "create" }).`);
             }
+            // Do NOT collapse a read failure into ''. An empty string already
+            // means "the editor is empty", and every read-modify-write caller
+            // treats it as a blank canvas — so a transient CDP failure made
+            // edit_pattern append OVERWRITE the live pattern with just the
+            // appended line, and report success (#277). Let it propagate; the
+            // dispatcher turns it into a failure envelope.
+            return await sessionController.getCurrentPattern();
         }
         if (!this.isInitialized) {
-            // Default session: return the last pre-init generated pattern if any
-            const lastPattern = Array.from(this.generatedPatterns.values()).pop();
-            return lastPattern || '';
-        }
-        try {
-            return await this.controller.getCurrentPattern();
-        }
-        catch {
-            return '';
+            // Default session: return the pre-init generated pattern if any
+            return this.pendingPattern ?? '';
         }
+        return await this.controller.getCurrentPattern();
     }
-    async writePatternSafe(pattern, sessionId) {
+    async writePatternSafe(pattern, rawSessionId) {
+        const sessionId = this.effectiveSessionId(rawSessionId);
         if (sessionId) {
             const sessionController = this.sessionManager.getSession(sessionId);
             if (!sessionController) {
-                throw new Error(`Session '${sessionId}' not found. Create it first with create_session.`);
+                throw new Error(`Session '${sessionId}' not found. Create it first with session({ action: "create" }).`);
             }
             return await sessionController.writePattern(pattern);
         }
         if (!this.isInitialized) {
             // Default session: stash the pattern for the next init/auto-init
-            const id = `pattern_${Date.now()}`;
-            this.generatedPatterns.set(id, pattern);
-            return `Pattern generated (initialize Strudel to use it): ${pattern.substring(0, 50)}...`;
+            this.pendingPattern = pattern;
+            return `${PATTERN_STASHED_PREFIX} ${pattern.substring(0, 50)}...`;
         }
         return await this.controller.writePattern(pattern);
     }
@@ -240,7 +371,7 @@ export class StrudelMCPServer {
         if (sessionId) {
             const controller = this.sessionManager.getSession(sessionId);
             if (!controller) {
-                throw new Error(`Session '${sessionId}' not found. Create it first with create_session.`);
+                throw new Error(`Session '${sessionId}' not found. Create it first with session({ action: "create" }).`);
             }
             return controller;
         }
@@ -274,30 +405,58 @@ export class StrudelMCPServer {
         // Save current state for undo and history (#41) before any edit
         // (#179): route to the session-specific bundle. Default session is
         // 'default'; named sessions get their own isolated stacks.
-        if (['write', 'append', 'insert', 'replace', 'clear'].includes(name)) {
-            const sid = args?.session_id;
+        if (name === 'edit_pattern') {
+            // The session this edit belongs to, resolved the same way the
+            // read and write below resolve it. `sid ?? 'default'` sent every
+            // unnamed edit's undo snapshot to a bundle keyed 'default', which
+            // then survived destroying the session it actually belonged to —
+            // so the next default session inherited the previous one's undo
+            // stack (#421).
+            const sid = this.effectiveSessionId(args?.session_id);
+            // A default session is enough to snapshot against; `init` is not
+            // required when SessionManager is the one holding the page.
             const canRead = sid !== undefined || this.isInitialized;
             if (canRead) {
+                // Two different failures used to share this catch. A missing
+                // controller or destroyed session legitimately means there is
+                // nothing to save — but a READ failure means we are about to
+                // overwrite a pattern we could not capture, leaving nothing for
+                // undo to restore. The fault that destroys the work also disabled
+                // the recovery (#277), so they are separated here.
+                let controller;
                 try {
-                    const controller = this.getControllerForSession(sid);
-                    const current = await controller.getCurrentPattern();
-                    const bundle = this.getHistoryBundle(sid ?? 'default');
-                    bundle.undoStack.push(current);
-                    this.historyIdCounter++;
-                    bundle.historyStack.push({
-                        id: this.historyIdCounter,
-                        pattern: current,
-                        timestamp: new Date(),
-                        action: name,
-                    });
-                    if (bundle.undoStack.length > this.MAX_HISTORY)
-                        bundle.undoStack.shift();
-                    if (bundle.historyStack.length > this.MAX_HISTORY)
-                        bundle.historyStack.shift();
-                    bundle.redoStack.length = 0;
+                    controller = this.getControllerForSession(sid);
                 }
                 catch {
-                    // Controller might not be initialized yet, or session is gone
+                    // No session to snapshot; the edit itself will report that.
+                    controller = undefined;
+                }
+                if (controller !== undefined) {
+                    const current = await controller.getCurrentPattern();
+                    // A destroy can land during that await. `getHistoryBundle`
+                    // creates lazily, so it would then build a fresh bundle for a
+                    // session that no longer exists — a permanent map entry the
+                    // destroy callback has already run past (#423).
+                    const destroyedMidRead = sid !== undefined && this.sessionManager.getSession(sid) === undefined;
+                    if (destroyedMidRead) {
+                        this.logger.warn(`Session '${sid}' was destroyed while snapshotting; skipping history.`);
+                    }
+                    const bundle = destroyedMidRead ? null : this.getHistoryBundle(sid ?? 'default');
+                    bundle?.undoStack.push(current);
+                    if (bundle !== null) {
+                        this.historyIdCounter++;
+                        bundle.historyStack.push({
+                            id: this.historyIdCounter,
+                            pattern: current,
+                            timestamp: new Date(),
+                            action: args?.mode ?? 'write',
+                        });
+                        if (bundle.undoStack.length > this.MAX_HISTORY)
+                            bundle.undoStack.shift();
+                        if (bundle.historyStack.length > this.MAX_HISTORY)
+                            bundle.historyStack.shift();
+                        bundle.redoStack.length = 0;
+                    }
                 }
             }
         }
@@ -305,7 +464,12 @@ export class StrudelMCPServer {
         // Part of the #104 file split — each module owns its own definitions
         // and handlers. server.ts keeps the protocol + state-tracking shell.
         const ctx = {
-            controller: this.controller,
+            // Surfaced by `diagnostics level=status`; see ConfigReport (#442).
+            configReport: {
+                path: resolve(configPath),
+                found: configFound,
+                warnings: config.warnings,
+            },
             perfMonitor: this.perfMonitor,
             store: this.store,
             generator: this.generator,
@@ -314,6 +478,8 @@ export class StrudelMCPServer {
             geminiService: this.geminiService,
             strudelEngine: this.strudelEngine,
             midiExportService: this.midiExportService,
+            audioExportService: this.audioExportService,
+            midiImportService: this.midiImportService,
             getAudioCaptureService: (sessionId) => this.getAudioCaptureService(sessionId),
             dropAudioCaptureService: (sessionId) => { this.audioCaptureServices.delete(sessionId); },
             getHistory: (sessionId) => {
@@ -325,7 +491,6 @@ export class StrudelMCPServer {
                     maxHistory: this.MAX_HISTORY,
                 };
             },
-            historyEntryId: () => ++this.historyIdCounter,
             dropHistory: (sessionId) => { this.historyBundles.delete(sessionId); },
             logger: this.logger,
             isInitialized: () => this.isInitialized,
@@ -373,13 +538,34 @@ export class StrudelMCPServer {
         if (name === 'init') {
             const initResult = await this.controller.initialize();
             this.isInitialized = true;
-            // Replay any pattern generated before init landed.
-            if (this.generatedPatterns.size > 0) {
-                const lastPattern = Array.from(this.generatedPatterns.values()).pop();
-                if (lastPattern) {
-                    await this.controller.writePattern(lastPattern);
-                    return `${initResult}. Loaded generated pattern.`;
-                }
+            // Install the recorder hook before any pattern playback connects the
+            // Strudel audio graph. Otherwise audio_capture can miss the first
+            // GainNode.connect call and remain disconnected even while diagnostics
+            // reports healthy WebAudio playback.
+            if (this._page) {
+                await this.getAudioCaptureService();
+            }
+            // Replay any pattern generated before init landed, then forget it.
+            //
+            // Clearing is the whole point: the stash exists to bridge the gap
+            // before a browser exists, and that gap closes the first time init
+            // succeeds. Without the clear, a second init — which agents call
+            // routinely, since it reports "Already initialized" and reads as a
+            // no-op — silently overwrote the live editor with a pattern from
+            // before the first init. Undo could not recover it either, because
+            // this writes through the controller and only edit_pattern pushes
+            // history (#262).
+            // Read without clearing, and clear only once the write lands.
+            //
+            // `takePendingPattern()` cleared first, so a write that threw —
+            // a page that died between init and this line — destroyed the
+            // pattern unrecoverably. The comment above justifies CLEARING;
+            // it does not justify clearing early (#453).
+            const pending = this.pendingPattern;
+            if (pending !== null) {
+                await this.controller.writePattern(pending);
+                this.pendingPattern = null;
+                return `${initResult}. Loaded generated pattern.`;
             }
             return initResult;
         }
@@ -398,11 +584,45 @@ export class StrudelMCPServer {
         return bundle;
     }
     /** Idempotent browser bring-up. Used by tools that promise auto-init (e.g. `compose`). */
+    /**
+     * Initializes the default browser if it is not already up.
+     *
+     * Single-flight. The MCP SDK does not serialize tool calls — each
+     * request is dispatched through a promise chain and returns immediately
+     * — so two `compose` calls arriving together both used to pass the
+     * `isInitialized` check, both call `initialize()`, and both assign
+     * `this.browser`. The second assignment orphaned the first Chromium
+     * process, which `cleanup()` could no longer reach. With the default
+     * `headless: false` the user also got two windows, half their tool
+     * calls addressing the one they were not watching (#265).
+     *
+     * The in-flight promise is the same shape `checkADC()` already uses.
+     */
     async ensureInitialized() {
+        // `isInitialized` was only ever set true, so once the browser died —
+        // user closed the window, or cleanup() ran — this returned early and
+        // never reached the self-healing initialize(). compose, the tool that
+        // advertises auto-init, then failed permanently with 'Target page,
+        // context or browser has been closed' (#265).
+        // Strict false, and an optional call: a controller that cannot answer
+        // (or does not implement the check) should mean 'assume alive' rather
+        // than tearing down a working browser. Recovery is the optimization
+        // here; a false negative just preserves the old behaviour.
+        if (this.isInitialized && this.controller.isAlive?.() === false) {
+            this.isInitialized = false;
+        }
         if (this.isInitialized)
             return;
-        await this.controller.initialize();
-        this.isInitialized = true;
+        // Promise.resolve wrap: initialize() is not guaranteed to return a
+        // thenable (a mocked controller returns undefined), and chaining
+        // directly off it would throw before ever launching a browser.
+        this.initPromise ??= Promise.resolve(this.controller.initialize())
+            .then(() => { this.isInitialized = true; })
+            .finally(() => { this.initPromise = null; });
+        await this.initPromise;
+        if (this._page) {
+            await this.getAudioCaptureService();
+        }
     }
     /** Getter for page access in audio capture. */
     get _page() {
@@ -413,18 +633,25 @@ export class StrudelMCPServer {
     // the class. Post-#180: per-session — each session's recorder injects
     // into its own page; concurrent captures across sessions no longer
     // share a singleton stream.
-    async getAudioCaptureService(sessionId) {
-        // Resolve the right page: explicit session via SessionManager, or
-        // legacy/default via this.controller.
+    async getAudioCaptureService(rawSessionId) {
+        // Resolve the right page: the named or default session via
+        // SessionManager, or the legacy controller when neither exists.
+        //
+        // This used to treat "no session_id" as "legacy, always", so a
+        // recorder was injected into the legacy page while `startCapture`
+        // ran against the default session's page — two different browser
+        // contexts (#421). It also refused with "Browser not initialized"
+        // when a live default session was sitting right there.
+        const sessionId = this.effectiveSessionId(rawSessionId);
         let page;
         let key;
         if (sessionId) {
             const sessionController = this.sessionManager.getSession(sessionId);
             if (!sessionController) {
-                throw new Error(`Session '${sessionId}' not found. Create it first with create_session.`);
+                throw new Error(`Session '${sessionId}' not found. Create it first with session({ action: "create" }).`);
             }
             if (!sessionController.page) {
-                throw new Error(`Session '${sessionId}' has no active page yet.`);
+                throw new BusinessError(`Session '${sessionId}' has no active page yet.`);
             }
             page = sessionController.page;
             key = sessionId;
@@ -436,23 +663,104 @@ export class StrudelMCPServer {
             page = this._page;
             key = 'default';
         }
-        let service = this.audioCaptureServices.get(key);
-        if (!service) {
-            service = new AudioCaptureService();
-            await service.injectRecorder(page);
-            this.audioCaptureServices.set(key, service);
+        // Re-inject when the cached service is bound to a different page.
+        //
+        // A cached service used to be returned unconditionally, which broke
+        // in two ways (#264). A session recreated under a previously-evicted
+        // id got the old session's recorder, pointing at a closed page. And
+        // after `init` recovered a dead browser (#206), the 'default' service
+        // still referenced the old page — so audio capture was permanently
+        // broken by the very mechanism meant to recover from a crash, with
+        // "Audio capture not initialized" until restart.
+        //
+        // Strict false, like the liveness check in ensureInitialized: a
+        // service that cannot answer keeps the old reuse-the-cache
+        // behaviour, so this can only ever add a re-injection that was
+        // needed, never drop one that was working.
+        const service = this.audioCaptureServices.get(key);
+        // Awaited: the check asks the page whether the recorder is still
+        // there, because a Playwright `Page` outlives the JS realm it points
+        // at and a reload wipes the recorder while identity still matches
+        // (#437).
+        if (service && (await service.isInjectedInto?.(page)) !== false) {
+            return service;
+        }
+        // Single-flight, like `SessionManager.ensureBrowser` (#263).
+        //
+        // This was check-then-act: two concurrent `audio_capture` calls on
+        // one uncached session both missed, both constructed, both awaited
+        // `injectRecorder`, and the last `set` won. `injectRecorder` assigns
+        // `window.strudelAudioCapture` unconditionally, so the second
+        // injection WIPED a capture the first had started, and the orphaned
+        // service still reported itself injected (#423).
+        const existing = this.captureServiceBuilds.get(key);
+        if (existing !== undefined)
+            return await existing;
+        const build = (async () => {
+            const fresh = new AudioCaptureService();
+            await fresh.injectRecorder(page);
+            // A destroy landing during the await deleted a key that was not
+            // there yet; re-inserting here would resurrect a service for a
+            // dead session. The caller still gets its recorder — the page it
+            // asked about is the page it got — but nothing is cached for an
+            // id that no longer exists.
+            if (key === 'default' || this.sessionManager.getSession(key) !== undefined) {
+                this.audioCaptureServices.set(key, fresh);
+            }
+            return fresh;
+        })();
+        this.captureServiceBuilds.set(key, build);
+        try {
+            return await build;
+        }
+        finally {
+            this.captureServiceBuilds.delete(key);
         }
-        return service;
     }
     async run() {
         const transport = new StdioServerTransport();
         await this.server.connect(transport);
         this.logger.info('Enhanced Strudel MCP server v2.0.1 running (fixed)');
-        process.on('SIGINT', async () => {
-            this.logger.info('Shutting down...');
+        // SIGTERM as well as SIGINT. The isolated engine child is a real
+        // process, and `docker stop`, systemd and most supervisors send
+        // SIGTERM — handling only SIGINT left the child orphaned in exactly
+        // the deployments where nobody is watching a terminal (#307).
+        let shuttingDown = false;
+        const shutdown = async (signal) => {
+            if (shuttingDown) {
+                // A second signal means the operator is not willing to wait any
+                // longer, and they are usually right. Swallowing it left Ctrl+C
+                // doing nothing at all while a wedged browser held the first
+                // shutdown open forever.
+                this.logger.warn(`${signal} during shutdown — exiting now.`);
+                process.exit(1);
+            }
+            shuttingDown = true;
+            this.logger.info(`Shutting down (${signal})...`);
+            // cleanup() and destroyAll() both talk to a browser over CDP, and a
+            // wedged one never answers. Without this the process hangs in
+            // shutdown indefinitely and the supervisor eventually SIGKILLs it,
+            // which is the one path that CAN orphan the engine child. unref'd
+            // so it never keeps a healthy process alive.
+            const forceExit = setTimeout(() => {
+                this.logger.error(`Shutdown exceeded ${String(SHUTDOWN_GRACE_MS)}ms — forcing exit.`);
+                process.exit(1);
+            }, SHUTDOWN_GRACE_MS);
+            forceExit.unref();
+            // Disposed FIRST and synchronously. The two awaits below can hang
+            // on a wedged browser, and the child must not outlive us because
+            // cleanup took too long.
+            this.strudelEngine.dispose();
             await this.controller.cleanup();
             await this.sessionManager.destroyAll();
+            clearTimeout(forceExit);
             process.exit(0);
-        });
+        };
+        process.on('SIGINT', () => void shutdown('SIGINT'));
+        process.on('SIGTERM', () => void shutdown('SIGTERM'));
+        // Last resort: a path that reaches exit without a signal — an
+        // uncaught throw, or the transport closing — still must not leak a
+        // process. Synchronous only; this handler cannot await.
+        process.on('exit', () => { this.strudelEngine.dispose(); });
     }
 }