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

package/dist/server/tools/compose.js

@@ -4,6 +4,7 @@
  * `browser_window` (show or screenshot the Strudel window).
  */
 import { InputValidator } from '../../utils/InputValidator.js';
+import { defaultTempoFor, resolveLayers } from '../../services/StyleRegistry.js';
 const SESSION_ID_PROP = {
     session_id: {
         type: 'string',
@@ -34,7 +35,7 @@ export const tools = [
         inputSchema: {
             type: 'object',
             properties: {
-                style: { type: 'string', description: 'Genre: techno, house, dnb, ambient, trap, jungle, jazz, experimental' },
+                style: { type: 'string', description: 'Genre: techno, house, dnb, breakbeat, trap, jungle, ambient, experimental, intelligent_dnb, trip_hop, boom_bap. Anything else (jazz included) gets techno drums, and the response says so.' },
                 tempo: { type: 'number', description: 'BPM (default: genre-appropriate)' },
                 key: { type: 'string', description: 'Musical key (default: C)' },
                 auto_play: { type: 'boolean', description: 'Start playback immediately (default: true)' },
@@ -46,27 +47,6 @@ export const tools = [
     },
 ];
 export const toolNames = new Set(tools.map(t => t.name));
-const TEMPO_BY_STYLE = {
-    techno: 130,
-    house: 125,
-    dnb: 174,
-    'drum and bass': 174,
-    ambient: 80,
-    trap: 140,
-    jungle: 160,
-    jazz: 110,
-    experimental: 120,
-    dubstep: 140,
-    trance: 138,
-    breakbeat: 130,
-    garage: 130,
-    electro: 128,
-    downtempo: 90,
-    idm: 115,
-};
-function defaultTempo(style) {
-    return TEMPO_BY_STYLE[style.toLowerCase()] ?? 120;
-}
 async function doShow(ctx, sid) {
     if (!sid && !ctx.isInitialized()) {
         return 'Browser not initialized. Run init first.';
@@ -98,13 +78,21 @@ export async function execute(name, args, ctx) {
                 InputValidator.validateBPM(args.tempo);
             }
             // Auto-init only the default session. Named sessions must be
-            // created via `create_session` first — ctx.getController(sid)
+            // created via `session({ action: "create" })` first — ctx.getController(sid)
             // throws if missing, which the dispatcher renders as err('business').
             if (!sid) {
                 await ctx.ensureInitialized();
             }
             const controller = ctx.getController(sid);
-            const tempo = args.tempo || defaultTempo(args.style);
+            // compose assembles four independently-resolved layers, each
+            // falling back on its own. One `style` field cannot describe that
+            // — reporting only the drum resolution called
+            // compose({style:'jazz'}) "techno" while its bassline, Dorian
+            // scale and jazz chords were all genuinely jazz, and let
+            // `breakbeat` claim itself supported over a techno bassline
+            // (#294, correcting #279).
+            const resolution = resolveLayers(args.style);
+            const tempo = args.tempo || defaultTempoFor(args.style);
             const key = args.key || 'C';
             const pattern = ctx.generator.generateCompletePattern(args.style, key, tempo);
             await controller.writePattern(pattern);
@@ -115,9 +103,21 @@ export async function execute(name, args, ctx) {
             const response = {
                 success: true,
                 pattern: pattern.substring(0, 200) + (pattern.length > 200 ? '...' : ''),
-                metadata: { style: args.style, bpm: tempo, key },
+                metadata: {
+                    style: args.style,
+                    bpm: tempo,
+                    key,
+                    layers: resolution.layers,
+                    substituted: resolution.substituted,
+                },
                 status: shouldPlay ? 'playing' : 'ready',
-                message: `Created ${args.style} pattern in ${key}${shouldPlay ? ' - now playing' : ''}`,
+                message: resolution.substituted.length === 0
+                    ? `Created ${args.style} pattern in ${key}${shouldPlay ? ' - now playing' : ''}`
+                    : `Created pattern in ${key}${shouldPlay ? ' - now playing' : ''}. ` +
+                        `No ${resolution.substituted.join(' or ')} defined for style "${args.style}" — ` +
+                        resolution.substituted
+                            .map(l => `${l}: ${resolution.layers[l]}`)
+                            .join(', ') + '.',
             };
             if (args.get_feedback) {
                 if (ctx.geminiService.isAvailable()) {

package/dist/server/tools/diagnostics.js

@@ -10,6 +10,7 @@
  * touch the browser (`level='full'`) or just inspect server state
  * (`perf`, `memory`).
  */
+import { empty } from './types.js';
 const SESSION_ID_PROP = {
     session_id: {
         type: 'string',
@@ -20,7 +21,7 @@ export const tools = [
     {
         name: 'diagnostics',
         description: 'Inspect server and browser state. ' +
-            'level=status returns a quick state snapshot (cache read, <15ms SLA). ' +
+            'level=status returns a quick state snapshot (cache read, <15ms SLA), plus which config.json was read and any warnings from it. ' +
             'level=full returns detailed browser diagnostics including caches, errors, and performance. ' +
             'level=perf returns server-side timing metrics + top bottlenecks. ' +
             'level=memory returns process memory usage. ' +
@@ -52,7 +53,23 @@ function getMemoryUsage(ctx) {
     return memory ? JSON.stringify(memory, null, 2) : 'Memory usage not available';
 }
 function getStatus(ctx, sid) {
-    return ctx.getController(sid).getStatus();
+    const status = ctx.getController(sid).getStatus();
+    const report = ctx.configReport;
+    if (!report)
+        return status;
+    // Config problems reached `logger.warn` and nothing else — a client
+    // log file the user may never open. A `strudel_url` typo, or an
+    // `audio_analysis` block that parsed to nothing, was invisible from
+    // inside the session. The path is reported whether or not a file was
+    // found, so a cwd surprise is visible rather than guessed at (#442).
+    return {
+        ...(typeof status === 'object' && status !== null ? status : { status }),
+        config: {
+            path: report.path,
+            found: report.found,
+            ...(report.warnings.length > 0 ? { warnings: report.warnings } : {}),
+        },
+    };
 }
 async function getFullDiagnostics(ctx, sid) {
     if (!sid && !ctx.isInitialized()) {
@@ -68,7 +85,7 @@ function getErrors(ctx, sid) {
     const errors = controller.getConsoleErrors();
     const warnings = controller.getConsoleWarnings();
     if (errors.length === 0 && warnings.length === 0) {
-        return 'No errors or warnings captured.';
+        return empty('No errors or warnings captured.');
     }
     let result = '';
     if (errors.length > 0) {

package/dist/server/tools/editor.js

@@ -5,7 +5,9 @@
  * write/append/insert/replace/clear modes, plus `get_pattern` (kept
  * separate — hot read path).
  */
+import { empty, ok, withStashField } from './types.js';
 import { InputValidator } from '../../utils/InputValidator.js';
+import { ValidationError } from '../../utils/CategorisedError.js';
 const SESSION_ID_PROP = {
     session_id: {
         type: 'string',
@@ -19,7 +21,8 @@ export const tools = [
             'mode=write replaces the editor contents (default; mirrors the old write tool exactly, including optional pattern validation and auto_play). ' +
             'mode=append concatenates `code` after the current pattern with a newline. ' +
             'mode=insert places `code` at the given line `position`. ' +
-            'mode=replace runs a single string-replace from `search` to `replace`. ' +
+            'mode=replace substitutes `search` with `replace` — the first occurrence only, unless replace_all is true. ' +
+            'The response reports how many occurrences matched, were replaced, and remain. ' +
             'mode=clear empties the editor. ' +
             'Example: edit_pattern({ mode: "write", pattern: "s(\\"bd\\")", auto_play: true }). ' +
             'For reading the editor without mutating it use get_pattern; for the on-disk pattern catalog use pattern_store.',
@@ -33,9 +36,14 @@ export const tools = [
                 },
                 pattern: { type: 'string', description: 'Pattern code (mode=write)' },
                 code: { type: 'string', description: 'Code to append/insert (mode=append/insert)' },
-                position: { type: 'number', description: 'Line number (mode=insert)' },
+                position: {
+                    type: 'number',
+                    description: 'mode=insert: 0-indexed line to insert BEFORE. 0 puts the code at the top; '
+                        + 'a value equal to the line count appends. Out of range is an error, not an append.',
+                },
                 search: { type: 'string', description: 'Text to replace (mode=replace)' },
                 replace: { type: 'string', description: 'Replacement text (mode=replace)' },
+                replace_all: { type: 'boolean', description: 'mode=replace: replace every occurrence instead of just the first (default false)' },
                 auto_play: { type: 'boolean', description: 'Start playback after write (mode=write only, default: false)' },
                 validate: { type: 'boolean', description: 'Validate pattern before write (mode=write only, default: true)' },
                 ...SESSION_ID_PROP,
@@ -84,20 +92,66 @@ async function doAppend(args, ctx, sid) {
     return await ctx.writePatternSafe(current + '\n' + args.code, sid);
 }
 async function doInsert(args, ctx, sid) {
-    InputValidator.validatePositiveInteger(args.position, 'position');
     InputValidator.validateStringLength(args.code, 'code', 10000, true);
     const lines = (await ctx.getCurrentPatternSafe(sid)).split('\n');
-    lines.splice(args.position, 0, args.code);
+    // 0-indexed, and 0 is a legal position.
+    //
+    // `validatePositiveInteger` rejected 0 while the `splice` below is
+    // 0-indexed, so inserting at the TOP of a pattern was impossible
+    // through this tool — and `StrudelController.insertAtLine`, which does
+    // the same job, documents the parameter as 0-indexed and permits 0.
+    //
+    // The other end was unguarded: `position: 9999` on a three-line
+    // pattern passed validation and `splice` silently appended, where
+    // `insertAtLine` throws. Now it matches that contract exactly
+    // (#442), so the two ways of doing this cannot disagree.
+    const position = args.position;
+    if (!Number.isInteger(position) || position < 0 || position > lines.length) {
+        throw new ValidationError(`Invalid position: ${String(position)}. Must be an integer between 0 and ${String(lines.length)} ` +
+            `(0 inserts before the first line, ${String(lines.length)} appends).`);
+    }
+    lines.splice(position, 0, args.code);
     return await ctx.writePatternSafe(lines.join('\n'), sid);
 }
 async function doReplace(args, ctx, sid) {
     InputValidator.validateStringLength(args.search, 'search', 1000, true);
     InputValidator.validateStringLength(args.replace, 'replace', 10000, true);
+    const search = args.search ?? '';
+    if (search.length === 0) {
+        throw new Error('Invalid search: must be a non-empty string.');
+    }
     const pattern = await ctx.getCurrentPatternSafe(sid);
+    // Literal string operations throughout — never a RegExp built from
+    // `search`. Interpolating caller text into a pattern is how #236
+    // happened: `(a+)+Z` against a crafted subject blocked the event loop
+    // for 25 seconds.
+    const matches = pattern.split(search).length - 1;
     // Escape $ in replacement to prevent special sequence injection ($&, $1, $', etc.)
     const safeReplacement = args.replace.replace(/\$/g, '$$$$');
-    const replaced = pattern.replace(args.search, safeReplacement);
-    return await ctx.writePatternSafe(replaced, sid);
+    const replaceAll = args.replace_all === true;
+    const updated = replaceAll
+        ? pattern.replaceAll(search, safeReplacement)
+        : pattern.replace(search, safeReplacement);
+    const replaced = replaceAll ? matches : Math.min(matches, 1);
+    const remaining = matches - replaced;
+    const written = await ctx.writePatternSafe(updated, sid);
+    // Counts are reported under BOTH settings. Previously a caller had no
+    // way to learn that other occurrences survived — and these callers are
+    // LLM agents, which do not reliably re-read the pattern to check (#243).
+    // Zero matches is a valid-empty: the search ran and found nothing.
+    // Wrapped in a plain ok() it was indistinguishable from a replace
+    // that actually changed the pattern (#288).
+    const wrap = matches === 0 ? empty : ok;
+    return wrap(withStashField({
+        success: true,
+        message: matches === 0
+            ? `No occurrences of ${JSON.stringify(search)} found`
+            : `Replaced ${String(replaced)} of ${String(matches)} occurrence(s)` +
+                (remaining > 0 ? `; ${String(remaining)} remain. Pass replace_all: true to replace them all.` : ''),
+        replaced,
+        remaining,
+        matches,
+    }, written));
 }
 async function doClear(ctx, sid) {
     return await ctx.writePatternSafe('', sid);

package/dist/server/tools/generate.js

@@ -9,7 +9,9 @@
  * Full-composition generation lives in `compose` (compose.ts), which
  * orchestrates init + generate + play + optional AI feedback.
  */
+import { withStashNotice } from './types.js';
 import { InputValidator } from '../../utils/InputValidator.js';
+import { BASS_STYLES, DRUM_STYLES, resolveBassStyle, resolveDrumStyle } from '../../services/StyleRegistry.js';
 const SESSION_ID_PROP = {
     session_id: {
         type: 'string',
@@ -85,10 +87,17 @@ export const tools = [
     },
 ];
 export const toolNames = new Set(tools.map(t => t.name));
+/**
+ * Appends generated material to the current pattern and writes it back.
+ *
+ * @returns Whatever `writePatternSafe` returned — callers must pass it
+ *   to `withStashNotice` rather than discard it, because a write with
+ *   no browser up is a stash, not a write (#285).
+ */
 async function appendOrSet(generated, ctx, sessionId) {
     const current = await ctx.getCurrentPatternSafe(sessionId);
     const combined = current ? current + '\n' + generated : generated;
-    await ctx.writePatternSafe(combined, sessionId);
+    return await ctx.writePatternSafe(combined, sessionId);
 }
 function doScale(args, ctx) {
     InputValidator.validateRootNote(args.root);
@@ -101,38 +110,52 @@ async function doChordProgression(args, ctx, sid) {
     InputValidator.validateChordStyle(args.style);
     const progression = ctx.theory.generateChordProgression(args.key, args.style);
     const chordPattern = ctx.generator.generateChords(progression);
-    await appendOrSet(chordPattern, ctx, sid);
-    return `Generated ${args.style} progression in ${args.key}: ${progression}`;
+    const written = await appendOrSet(chordPattern, ctx, sid);
+    return withStashNotice(`Generated ${args.style} progression in ${args.key}: ${progression}`, written);
 }
 async function doEuclidean(args, ctx, sid) {
     InputValidator.validateEuclidean(args.hits, args.steps);
     if (args.sound)
         InputValidator.validateStringLength(args.sound, 'sound', 100, false);
     const euclidean = ctx.generator.generateEuclideanPattern(args.hits, args.steps, args.sound || 'bd');
-    await appendOrSet(euclidean, ctx, sid);
-    return `Generated Euclidean rhythm (${args.hits}/${args.steps})`;
+    const written = await appendOrSet(euclidean, ctx, sid);
+    return withStashNotice(`Generated Euclidean rhythm (${args.hits}/${args.steps})`, written);
 }
 async function doPolyrhythm(args, ctx, sid) {
     args.sounds.forEach((s) => InputValidator.validateStringLength(s, 'sound', 100, false));
     args.patterns.forEach((p) => InputValidator.validatePositiveInteger(p, 'pattern'));
     const poly = ctx.generator.generatePolyrhythm(args.sounds, args.patterns);
-    await appendOrSet(poly, ctx, sid);
-    return 'Generated polyrhythm';
+    const written = await appendOrSet(poly, ctx, sid);
+    return withStashNotice('Generated polyrhythm', written);
 }
 async function doDrums(args, ctx, sid) {
     InputValidator.validateStringLength(args.style, 'style', 100, false);
     if (args.complexity !== undefined)
         InputValidator.validateNormalizedValue(args.complexity, 'complexity');
+    // Say which style actually produced the notes. An unknown genre falls
+    // back to techno, and echoing the request back made that invisible (#279).
+    const resolution = resolveDrumStyle(args.style);
     const drums = ctx.generator.generateDrumPattern(args.style, args.complexity || 0.5);
-    await appendOrSet(drums, ctx, sid);
-    return `Generated ${args.style} drums`;
+    const written = await appendOrSet(drums, ctx, sid);
+    return withStashNotice(resolution.supported
+        ? `Generated ${resolution.resolved} drums`
+        : `No drum pattern for style "${args.style}" — generated ${resolution.resolved} drums instead. ` +
+            `Styles with their own drums: ${DRUM_STYLES.join(', ')}.`, written);
 }
 async function doBassline(args, ctx, sid) {
     InputValidator.validateRootNote(args.key);
     InputValidator.validateStringLength(args.style, 'style', 100, false);
+    // role=bass echoed args.style back while the generator had silently
+    // fallen back to techno — #279 in the same file, eight lines below
+    // the sibling it fixed (#294).
+    const resolution = resolveBassStyle(args.style);
     const bass = ctx.generator.generateBassline(args.key, args.style);
-    await appendOrSet(bass, ctx, sid);
-    return `Generated ${args.style} bassline in ${args.key}`;
+    const written = await appendOrSet(bass, ctx, sid);
+    return withStashNotice(resolution.supported
+        ? `Generated ${resolution.resolved} bassline in ${args.key}`
+        : `No bassline for style "${args.style}" — generated ${resolution.resolved} ` +
+            `bassline in ${args.key} instead. ` +
+            `Styles with their own bassline: ${BASS_STYLES.join(', ')}.`, written);
 }
 async function doMelody(args, ctx, sid) {
     InputValidator.validateRootNote(args.root);
@@ -141,16 +164,16 @@ async function doMelody(args, ctx, sid) {
         InputValidator.validatePositiveInteger(args.length, 'length');
     const scale = ctx.theory.generateScale(args.root, args.scale);
     const melody = ctx.generator.generateMelody(scale, args.length || 8);
-    await appendOrSet(melody, ctx, sid);
-    return `Generated melody in ${args.root} ${args.scale}`;
+    const written = await appendOrSet(melody, ctx, sid);
+    return withStashNotice(`Generated melody in ${args.root} ${args.scale}`, written);
 }
 async function doFill(args, ctx, sid) {
     InputValidator.validateStringLength(args.style, 'style', 100, false);
     if (args.bars !== undefined)
         InputValidator.validatePositiveInteger(args.bars, 'bars');
     const fill = ctx.generator.generateFill(args.style, args.bars || 1);
-    await appendOrSet(fill, ctx, sid);
-    return `Generated ${args.bars || 1} bar fill`;
+    const written = await appendOrSet(fill, ctx, sid);
+    return withStashNotice(`Generated ${args.bars || 1} bar fill`, written);
 }
 export async function execute(name, args, ctx) {
     const sid = args?.session_id;

package/dist/server/tools/history.js

@@ -9,6 +9,7 @@
  * server pushes onto these arrays on every edit_pattern call, so all
  * mutations share the same underlying storage.
  */
+import { empty, err } from './types.js';
 const SESSION_ID_PROP = {
     session_id: {
         type: 'string',
@@ -96,8 +97,11 @@ async function doUndo(ctx, sid) {
     const { undoStack, redoStack, maxHistory } = ctx.getHistory(sid);
     if (!sid && !ctx.isInitialized())
         return 'Browser not initialized. Run init first.';
+    // A valid-empty, not a failure: the call worked, there was simply
+    // nothing on the stack. `empty()` lets an agent tell that apart from
+    // a rich result without parsing the prose (#288).
     if (undoStack.length === 0)
-        return 'Nothing to undo';
+        return empty('Nothing to undo');
     const controller = ctx.getController(sid);
     const current = await controller.getCurrentPattern();
     redoStack.push(current);
@@ -112,7 +116,7 @@ async function doRedo(ctx, sid) {
     if (!sid && !ctx.isInitialized())
         return 'Browser not initialized. Run init first.';
     if (redoStack.length === 0)
-        return 'Nothing to redo';
+        return empty('Nothing to redo');
     const controller = ctx.getController(sid);
     const current = await controller.getCurrentPattern();
     undoStack.push(current);
@@ -125,7 +129,14 @@ async function doRedo(ctx, sid) {
 function doList(args, ctx, sid) {
     const { historyStack } = ctx.getHistory(sid);
     if (historyStack.length === 0) {
-        return 'No pattern history yet. Make some edits to build history.';
+        // Same record shape as the populated branch below, so a caller can
+        // read `entries` unconditionally instead of branching on a string.
+        return empty({
+            count: 0,
+            showing: 0,
+            entries: [],
+            message: 'No pattern history yet. Make some edits to build history.',
+        });
     }
     const limit = args?.limit || 10;
     const recent = historyStack.slice(-limit).reverse();
@@ -148,7 +159,10 @@ async function doRestore(args, ctx, sid) {
     const controller = ctx.getController(sid);
     const entry = historyStack.find(e => e.id === args.id);
     if (!entry) {
-        return `History entry #${args.id} not found. Use history({ action: "list" }) to see available entries.`;
+        // Same bare-string false success as storage's load (#293): nothing
+        // was restored, but `ok: true` said otherwise.
+        return err('business', `History entry #${args.id} not found. ` +
+            'Use history({ action: "list" }) to see available entries.');
     }
     const current = await controller.getCurrentPattern();
     undoStack.push(current);
@@ -160,14 +174,22 @@ async function doRestore(args, ctx, sid) {
 async function doCompare(args, ctx, sid) {
     const { historyStack } = ctx.getHistory(sid);
     const first = historyStack.find(e => e.id === args.id1);
-    if (!first)
-        return `History entry #${args.id1} not found.`;
+    if (!first) {
+        // Bare strings reach the client as `{ok: true, data: "...not
+        // found."}` — the #287/#293 false success, still here twelve lines
+        // below the `doRestore` that fixed it for the identical condition
+        // (#453).
+        return err('business', `History entry #${args.id1} not found. ` +
+            'Use history({ action: "list" }) to see available entries.');
+    }
     let second;
     let label;
     if (args.id2) {
         const b = historyStack.find(e => e.id === args.id2);
-        if (!b)
-            return `History entry #${args.id2} not found.`;
+        if (!b) {
+            return err('business', `History entry #${args.id2} not found. ` +
+                'Use history({ action: "list" }) to see available entries.');
+        }
         second = b.pattern;
         label = `#${args.id2}`;
     }

package/dist/server/tools/playback.js

@@ -14,7 +14,7 @@ export const tools = [
         name: 'playback',
         description: 'Control transport on the current session. ' +
             'action=play starts the editor pattern. ' +
-            'action=pause stops without resetting clock. ' +
+            'action=pause halts the clock where it is, so play resumes mid-cycle. ' +
             'action=stop ends playback. ' +
             'Example: playback({ action: "play" }). ' +
             'For pattern editing use edit_pattern; for tempo use set_tempo.',
@@ -47,6 +47,7 @@ export async function execute(name, args, ctx) {
         case 'play':
             return await controller.play();
         case 'pause':
+            return await controller.pause();
         case 'stop':
             return await controller.stop();
         default:

package/dist/server/tools/session.js

@@ -5,6 +5,7 @@
  * list/switch actions. `init` stays separate — it's the global
  * bootstrap, not a session operation.
  */
+import { categorizeError, empty, err, ok } from './types.js';
 import { InputValidator } from '../../utils/InputValidator.js';
 export const tools = [
     {
@@ -41,7 +42,14 @@ async function doCreate(args, ctx) {
         };
     }
     catch (error) {
-        return { success: false, error: error instanceof Error ? error.message : String(error) };
+        // `err(...)` rather than `{ success: false }`: the dispatcher turns a
+        // failure-shaped object back into a PLAIN Error before categorising
+        // it, so a typed error thrown below this point loses its category on
+        // the way out and lands in `internal` — not retryable, and wrong
+        // about whose problem it is. Cross-model review caught that the
+        // typed errors were being destroyed at this seam (#382).
+        const message = error instanceof Error ? error.message : String(error);
+        return err(categorizeError(error), message);
     }
 }
 async function doDestroy(args, ctx) {
@@ -61,16 +69,33 @@ async function doDestroy(args, ctx) {
         };
     }
     catch (error) {
-        return { success: false, error: error instanceof Error ? error.message : String(error) };
+        // `err(...)` rather than `{ success: false }`: the dispatcher turns a
+        // failure-shaped object back into a PLAIN Error before categorising
+        // it, so a typed error thrown below this point loses its category on
+        // the way out and lands in `internal` — not retryable, and wrong
+        // about whose problem it is. Cross-model review caught that the
+        // typed errors were being destroyed at this seam (#382).
+        const message = error instanceof Error ? error.message : String(error);
+        return err(categorizeError(error), message);
     }
 }
 function doList(ctx) {
     const sm = ctx.sessionManager;
     const info = sm.getSessionsInfo();
-    return {
+    const wrap = info.length === 0 ? empty : ok;
+    return wrap({
         count: info.length,
         max_sessions: sm.getMaxSessions(),
-        default_session: sm.getDefaultSessionId(),
+        // Only when it exists. After a destroy, SessionManager resets this
+        // to the literal 'default', and reporting that named a session no
+        // caller could switch to or find in the list below (#421).
+        //
+        // Checked against `info` rather than by looking the session up:
+        // `getSession` stamps `lastActivity`, and listing sessions is not
+        // using one.
+        default_session: info.some(s => s.id === sm.getDefaultSessionId())
+            ? sm.getDefaultSessionId()
+            : null,
         sessions: info.map(s => ({
             id: s.id,
             created: s.created.toISOString(),
@@ -78,7 +103,7 @@ function doList(ctx) {
             is_playing: s.isPlaying,
             is_default: s.id === sm.getDefaultSessionId(),
         })),
-    };
+    });
 }
 function doSwitch(args, ctx) {
     const sm = ctx.sessionManager;
@@ -92,7 +117,14 @@ function doSwitch(args, ctx) {
         };
     }
     catch (error) {
-        return { success: false, error: error instanceof Error ? error.message : String(error) };
+        // `err(...)` rather than `{ success: false }`: the dispatcher turns a
+        // failure-shaped object back into a PLAIN Error before categorising
+        // it, so a typed error thrown below this point loses its category on
+        // the way out and lands in `internal` — not retryable, and wrong
+        // about whose problem it is. Cross-model review caught that the
+        // typed errors were being destroyed at this seam (#382).
+        const message = error instanceof Error ? error.message : String(error);
+        return err(categorizeError(error), message);
     }
 }
 export async function execute(name, args, ctx) {